DEV Community

Cover image for Docker Compose for Crypto Wallets: Self-Hosted AI Agent Infrastructure
Wallet Guy
Wallet Guy

Posted on

Docker Compose for Crypto Wallets: Self-Hosted AI Agent Infrastructure

#docker #selfhosted #web3 #devops

Docker Compose makes it possible to run your own crypto wallet infrastructure for AI agents in just one command, giving you complete control over your private keys without trusting any third-party service. Self-hosted wallet infrastructure eliminates custody risks while providing unlimited API access without rate limits or monthly fees.

Why Self-Custody Matters for AI Agents

When your AI agents handle real money, custody becomes critical. Hosted wallet services create a fundamental contradiction: you're building autonomous agents while surrendering control to centralized providers. Every transaction flows through someone else's infrastructure, subject to their terms, rate limits, and potential service interruptions.

Self-hosting puts you back in control. Your private keys never leave your server. Your transaction policies run on your hardware. Your AI agents operate with the sovereignty that crypto was designed to enable. It's the difference between renting computational power and owning your infrastructure.

WAIaaS: Docker-First Wallet Infrastructure

WAIaaS delivers enterprise-grade wallet functionality through a 15-package monorepo designed for self-hosting. The Docker deployment supports 2 Docker images (the main daemon plus push-relay for notifications), auto-provision for zero-touch setup, and production secrets overlay via docker-compose.secrets.yml.

The architecture provides 39 REST API route modules accessible through a simple session-based authentication system. AI agents authenticate with JWT tokens while owners retain ultimate control through cryptographic signatures. This separation lets you grant spending permissions without giving up custody.

Quick Start: Zero to Running

Clone and start — that's it:

git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

For completely hands-off deployment with auto-generated credentials:

docker run -d \
  --name waiaas \
  -p 127.0.0.1:3100:3100 \
  -v waiaas-data:/data \
  -e WAIAAS_AUTO_PROVISION=true \
  ghcr.io/minhoyoo-iotrust/waiaas:latest

# Retrieve auto-generated master password
docker exec waiaas cat /data/recovery.key
Enter fullscreen mode Exit fullscreen mode

The default port binding (127.0.0.1:3100:3100) keeps your API private to localhost unless you explicitly expose it. Auto-provision generates a secure master password and saves it to /data/recovery.key for later hardening.

Production Deployment with Secrets

For production environments, use Docker Secrets to avoid environment variable exposure:

# Create secret files
mkdir -p secrets
echo "your-secure-password" > secrets/master_password.txt
chmod 600 secrets/master_password.txt

# Deploy with secrets overlay
docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d
Enter fullscreen mode Exit fullscreen mode

The secrets overlay supports production patterns like external secret management and automated rotation. The daemon runs as non-root (UID 1001) with healthcheck endpoints and restart policies.

Multi-Chain Support Out of the Box

WAIaaS supports 2 chain types (evm, solana) across 18 networks, from Ethereum mainnet to Solana devnet. Chain configuration happens through environment variables:

WAIAAS_RPC_SOLANA_MAINNET=https://api.mainnet-beta.solana.com
WAIAAS_RPC_EVM_ETHEREUM_MAINNET=https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY
WAIAAS_DAEMON_PORT=3100
WAIAAS_DAEMON_LOG_LEVEL=info
Enter fullscreen mode Exit fullscreen mode

No external dependencies beyond your chosen RPC providers. You can use public endpoints for testing or private RPC services for production workloads.

Policy-Driven Security

Self-hosting doesn't mean self-endangering. WAIaaS includes a sophisticated policy engine with 21 policy types and 4 security tiers (INSTANT/NOTIFY/DELAY/APPROVAL) that let you define exactly what your AI agents can do.

Create spending limits that escalate based on transaction size:

curl -X POST http://localhost:3100/v1/policies \
  -H 'Content-Type: application/json' \
  -H 'X-Master-Password: <password>' \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 10,
      "notify_max_usd": 100,
      "delay_max_usd": 1000,
      "delay_seconds": 300,
      "daily_limit_usd": 500,
      "monthly_limit_usd": 5000
    }
  }'
Enter fullscreen mode Exit fullscreen mode

The policy system follows default-deny enforcement — transactions are blocked unless explicitly allowed by ALLOWED_TOKENS or CONTRACT_WHITELIST policies. This prevents your agents from interacting with unknown contracts or tokens without your approval.

Time-based restrictions, rate limiting, and network restrictions provide additional guardrails. Your agents operate within bounds you define, with escalation paths for larger transactions.

API-First Architecture

The 39 REST API endpoints expose every wallet function through consistent HTTP interfaces. AI agents authenticate with session tokens and interact through standard HTTP:

# Check wallet balance (sessionAuth)
curl http://127.0.0.1:3100/v1/wallet/balance \
  -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

# Execute DeFi action (sessionAuth)
curl -X POST http://127.0.0.1:3100/v1/actions/jupiter-swap/swap \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "inputMint": "So11111111111111111111111111111111111111112",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000000000"
  }'
Enter fullscreen mode Exit fullscreen mode

The API includes OpenAPI 3.0 spec auto-generated at /doc with interactive Scalar API reference UI at /reference. Standard error codes and consistent response formats make integration straightforward.

The 7-stage transaction pipeline (validate, auth, policy, wait, execute, confirm) provides full visibility into transaction state. Dry-run API support lets you test transactions before execution.

DeFi Integration Without Vendor Lock-in

WAIaaS integrates 15 DeFi protocol providers covering swaps, lending, staking, and bridges. Your agents can interact with Jupiter, Aave, Lido, Hyperliquid, and other major protocols without depending on external aggregator APIs.

curl -X POST http://127.0.0.1:3100/v1/actions/lido-staking/stake \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{"amount": "1000000000000000000"}'
Enter fullscreen mode Exit fullscreen mode

Cross-chain bridging via LI.FI and Across protocols enables multi-chain strategies. Liquid staking via Lido (EVM) and Jito (Solana) generates yield. Hyperliquid integration provides perpetual futures, spot trading, and sub-accounts.

All DeFi interactions respect your policy constraints and follow the same authentication model. No separate API keys or external service dependencies.

Monitoring and Observability

The Admin Web UI (Preact) provides wallet management, policy editor, and DeFi positions dashboard through a clean interface at /admin. Real-time monitoring shows transaction status, policy violations, and system health.

Incoming transaction monitoring with real-time notifications ensures you know when funds arrive. Push notifications through Telegram or custom webhooks keep you informed of significant events.

Structured logging and health check endpoints support standard monitoring tools. The Docker healthcheck uses curl -f http://localhost:3100/health with configurable intervals.

Quick Start: From Zero to AI Agent Trading

Here's how to get a trading AI agent running against your self-hosted infrastructure:

1. Deploy WAIaaS 

git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

2. Create Wallet and Session 

# Install CLI
npm install -g @waiaas/cli

# Quick setup with auto-generated wallets
waiaas init --auto-provision
waiaas start
waiaas quickset --mode mainnet
Enter fullscreen mode Exit fullscreen mode

3. Configure Policies 

# Set spending limits for safety
waiaas policy create spending-limit \
  --instant-max 10 \
  --daily-limit 500
Enter fullscreen mode Exit fullscreen mode

4. Connect Your AI Agent 

# Install SDK in your AI agent project
npm install @waiaas/sdk
Enter fullscreen mode Exit fullscreen mode 
import { WAIaaSClient } from '@waiaas/sdk';

const client = new WAIaaSClient({
  baseUrl: 'http://127.0.0.1:3100',
  sessionToken: process.env.WAIAAS_SESSION_TOKEN,
});

// Your agent can now trade autonomously within policy limits
const balance = await client.getBalance();
const positions = await client.getDeFiPositions();
Enter fullscreen mode Exit fullscreen mode

5. Scale and Monitor

Access the admin dashboard at http://localhost:3100/admin to monitor positions and adjust policies as your agent's strategy evolves.

Self-hosted wallet infrastructure gives you the foundation to build sophisticated AI trading systems without custody compromises. Your keys, your server, your rules.

What's Next

Self-hosting WAIaaS puts you in complete control of your AI agent's financial infrastructure while maintaining enterprise-grade security and DeFi access. Check out the full documentation and source code at https://github.com/minhoyoo-iotrust/WAIaaS, or visit https://waiaas.ai to explore the complete platform capabilities.

Top comments (0)