15-Package Monorepo in Docker: Microservices Architecture for AI Agent Wallets

Building an AI agent's wallet infrastructure shouldn't require trusting third parties with your private keys or being locked into hosted services. WAIaaS's 15-package monorepo architecture runs entirely on your hardware, giving you complete control over your agent's financial operations while maintaining the convenience of microservices design.

Why Self-Hosted Wallet Infrastructure Matters

The cryptocurrency space was built on the principle of "not your keys, not your crypto" — yet many AI agent wallet solutions force you to trust external services with your most sensitive operations. When your trading bot needs to execute thousands of transactions daily, or your DeFi agent manages substantial positions, custody becomes a critical concern.

Beyond security, self-hosting eliminates API rate limits, reduces latency to your local applications, and ensures your agent wallet infrastructure remains available even when third-party services experience outages. You're building for the long term, not renting access to someone else's vision of how wallets should work.

The Monorepo Microservices Solution

WAIaaS solves this through a carefully designed 15-package monorepo that runs as containerized microservices. Each package handles a specific concern, from transaction processing to DeFi integrations, while maintaining clear separation of responsibilities.

The core packages break down into several categories:

Core Infrastructure: The daemon package provides the REST API with 39 route modules, while core contains shared schemas and types. The shared package handles cross-package utilities, and wallet-sdk manages private key operations.

AI Agent Integration: The mcp package provides 45 MCP tools for Claude and other AI frameworks, while openclaw-plugin offers 5 tools for external agent platforms. The sdk package delivers both TypeScript and Python client libraries.

DeFi Operations: The actions package integrates 15 DeFi protocol providers including Jupiter, Uniswap, Aave, and Lido. Protocol-specific logic stays isolated while sharing common transaction patterns.

User Interfaces: The admin package provides a Preact-based web UI for policy management and wallet oversight. The cli package offers 20 commands for setup and maintenance operations.

Specialized Services: push-relay handles mobile notifications, adapters manages external service integrations, and skills provides pre-built agent behaviors.

Here's how the architecture looks in practice:

services:
  daemon:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
    container_name: waiaas-daemon
    ports:
      - "127.0.0.1:3100:3100"
    volumes:
      - waiaas-data:/data
    environment:
      - WAIAAS_DATA_DIR=/data
      - WAIAAS_DAEMON_HOSTNAME=0.0.0.0
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
      interval: 30s
      timeout: 5s
      retries: 3

  push-relay:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
    command: ["push-relay"]
    environment:
      - WAIAAS_DAEMON_URL=http://daemon:3100
    depends_on:
      - daemon

volumes:
  waiaas-data:
    driver: local

The daemon serves as the central coordinator, exposing a REST API that handles everything from balance queries to complex DeFi operations. The 7-stage transaction pipeline ensures security while maintaining performance — each transaction flows through validation, authentication, policy checks, optional delays, execution, and confirmation stages.

Production-Ready Container Design

The Docker implementation prioritizes security and operational best practices. The container runs as a non-root user (UID 1001), includes comprehensive healthchecks, and supports Docker Secrets for production credential management.

Auto-provisioning eliminates the cold-start problem for new deployments:

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

The auto-provision feature generates a cryptographically secure master password and stores recovery credentials in the persistent volume. This solves the bootstrapping challenge while maintaining security — you can harden the password later using the CLI.

For production deployments, the secrets overlay provides secure credential injection:

# 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

Policy Engine for Multi-Tenant Security

Self-hosting doesn't mean sacrificing security controls. WAIaaS includes a comprehensive policy engine with 21 policy types and 4 security tiers (INSTANT/NOTIFY/DELAY/APPROVAL) that enforce default-deny semantics.

Create spending limits with graduated security:

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
    }
  }'

The policy system operates on default-deny principles — transactions are blocked unless explicitly allowed through ALLOWED_TOKENS or CONTRACT_WHITELIST policies. This ensures your AI agents can't accidentally drain wallets or interact with malicious contracts.

Comprehensive Monitoring and Operations

Self-hosting requires observability, and WAIaaS provides multiple monitoring channels. The Admin Web UI offers real-time dashboards for wallet balances, transaction history, and DeFi positions across all 15 integrated protocols.

The CLI provides operational commands for backup, restore, and health monitoring:

# Create encrypted backups
waiaas backup create --encrypt

# Monitor system status
waiaas status

# Update to latest version
waiaas update

Transaction monitoring operates in real-time, tracking incoming deposits and notifying relevant systems through configurable channels including Telegram, push notifications, and webhook endpoints.

Quick Start: Self-Hosted Setup

Getting your own WAIaaS instance running takes just a few commands:

1. Deploy with Docker Compose:

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

1. Initialize and create wallets:

npm install -g @waiaas/cli
waiaas init --auto-provision
waiaas quickset --mode mainnet

1. Configure AI agent integration:

waiaas mcp setup --all  # Auto-register with Claude Desktop

1. Create your first policy:

waiaas policy create SPENDING_LIMIT --instant-max 10 --daily-limit 500

1. Access the admin interface: Open http://localhost:3100/admin for wallet management and monitoring.

Your self-hosted wallet infrastructure is now ready to handle AI agent operations with complete sovereignty over your private keys and transaction data.

For deeper technical insights, check out WAIaaS MCP Integration: 45 Tools for AI Agent Wallet Operations and Policy-Based Security for AI Agent Wallets: 21 Rules, 4 Tiers, Default-Deny.

What's Next

Your self-hosted WAIaaS instance provides the foundation for sophisticated AI agent financial operations without compromising on custody or control. Explore the full capabilities in the GitHub repository or visit waiaas.ai for comprehensive documentation and community resources.