Zero-Config AI Wallet Deployment: Docker Auto-Provisioning Magic Explained

2026-10-15

Zero-Config AI Wallet Deployment: Docker Auto-Provisioning Magic Explained

Docker auto-provisioning for AI agent wallets sounds like it should be complicated — but it doesn't have to be. If you've ever asked yourself whether you'd trust a third party with your AI agent's private keys, the answer probably shapes everything about how you want to run wallet infrastructure. This post is for the people who already know the answer.

The Problem With "Just Use Our Hosted Service"

Hosted wallet APIs are convenient right up until they aren't. You're subject to rate limits you didn't set, terms of service that can change, and most critically: someone else holds the keys. For an AI agent that needs to move funds autonomously, that's not a philosophical concern — it's a practical risk.

When your agent's private keys live on someone else's server, you don't have a self-custody wallet. You have an IOU. The crypto space learned this lesson the hard way, multiple times. Running your own wallet infrastructure is the crypto equivalent of running your own email server, except in 2026 the tooling has actually caught up to make it practical.

WAIaaS (Wallet-as-a-Service for AI agents) is an open-source, self-hosted project that puts the entire wallet stack on your own hardware. Your keys stay on your machine. Your data doesn't leave your network. Your AI agent talks to a local API endpoint you control.

Let's walk through exactly how to get it running, with zero manual configuration on first boot.

What "Auto-Provisioning" Actually Means

The WAIaaS Docker entrypoint supports an auto-provision mode. When you pass WAIAAS_AUTO_PROVISION=true, the daemon generates a master password on first start and writes it to /data/recovery.key inside the container.

This is important for a self-hosted context: you don't need to pre-generate secrets, store them somewhere safe before the container starts, or write a provisioning script. The container handles the bootstrap itself, and then you retrieve the generated credential from the volume.

Here's what that looks like in practice:

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

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

Notice the port binding: 127.0.0.1:3100:3100. The daemon only listens on localhost by default. You're not accidentally exposing your wallet API to the public internet the moment you run this command. That's a deliberate default.

The image is ghcr.io/waiaas/waiaas:latest — hosted on GitHub Container Registry, built from the open-source repository you can audit yourself.

The Full Docker Compose Setup

For a more permanent homelab deployment, Docker Compose gives you the restart policy, healthcheck, and volume management you want:

services:
  daemon:
    image: ghcr.io/waiaas/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
    env_file:
      - path: .env
        required: false
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

volumes:
  waiaas-data:
    driver: local

A few things worth calling out here for the self-hosters in the room:

restart: unless-stopped — Your wallet daemon comes back up after a reboot without you touching it. This matters when your agent is supposed to be running autonomously overnight.

The healthcheck — The daemon has a /health endpoint. Docker will restart the container if it becomes unresponsive. You're not flying blind.

Named volume waiaas-data — Your wallet data, keys, and transaction history persist across container restarts and image updates. docker compose down won't nuke your data. Only docker compose down -v does that, and you'd be doing that intentionally.

WAIAAS_DAEMON_HOSTNAME=0.0.0.0 — This sets what address the daemon binds to inside the container. Combined with the port binding to 127.0.0.1 on the host, the service is reachable from your machine but not exposed externally unless you add a reverse proxy in front of it.

Production Secrets: The Docker Secrets Overlay

Auto-provision is great for initial setup. For production, you want your master password in a Docker secret, not an environment variable that shows up in docker inspect.

WAIaaS ships with a docker-compose.secrets.yml overlay specifically for this:

# 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

The secrets file gets mounted into the container separately from the main environment, keeping your credentials out of the compose file itself and out of your shell history. This is the pattern you want if WAIaaS is running on a server rather than just your local machine.

Key Environment Variables to Know

The daemon is configured entirely through environment variables — no config file editing required. Here are the ones you'll actually use:

WAIAAS_AUTO_PROVISION=true              # Auto-generate master password on first start
WAIAAS_DAEMON_PORT=3100                 # Listening port
WAIAAS_DAEMON_HOSTNAME=0.0.0.0         # Bind address
WAIAAS_DAEMON_LOG_LEVEL=info            # Log level (trace/debug/info/warn/error)
WAIAAS_DATA_DIR=/data                   # Data directory
WAIAAS_RPC_SOLANA_MAINNET=<url>         # Solana mainnet RPC endpoint
WAIAAS_RPC_EVM_ETHEREUM_MAINNET=<url>   # Ethereum mainnet RPC endpoint

The RPC endpoint variables matter for sovereignty too. By default the daemon needs to talk to blockchain nodes. Pointing WAIAAS_RPC_SOLANA_MAINNET at your own node or a private RPC provider you trust means no third-party node operator sees your wallet's queries. That's the full stack of self-custody: keys on your machine, node calls to your infrastructure.

After the Container Starts: Creating Your First Wallet

Once the daemon is running, you interact with it through a local REST API. The master password (either auto-generated or the one you set) authenticates administrative operations like creating wallets and sessions.

curl -X POST http://127.0.0.1:3100/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"name": "trading-wallet", "chain": "solana", "environment": "mainnet"}'

Then create a session token for your AI agent:

curl -X POST http://127.0.0.1:3100/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"walletId": "<wallet-uuid>"}'

The session token (wai_sess_...) is what your AI agent uses. It has limited permissions by default — the master password stays with you, the session token goes to the agent. This separation is intentional. If a session token is compromised, you revoke it. The master password controls wallet creation and policy configuration; the session token controls what the agent can do within those policies.

Check the balance to confirm everything is wired up:

curl http://127.0.0.1:3100/v1/wallet/balance \
  -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

The CLI Quickset Path

If you'd rather not touch curl at all, the CLI handles the full setup flow. WAIaaS ships with a 20-command CLI that wraps the daemon API:

npm install -g @waiaas/cli
waiaas init --auto-provision     # Generates random master password → recovery.key
waiaas start                     # No password prompt
waiaas quickset                  # Creates wallets + sessions automatically
waiaas set-master                # (Later) Harden password, then delete recovery.key

The quickset command is what makes this genuinely fast — it creates wallets and session tokens in a single step, then prints the MCP configuration JSON you need to paste into Claude Desktop. From zero to a working AI agent wallet: one docker compose up -d and a handful of CLI commands.

Security Layers You Get Out of the Box

Running self-hosted doesn't mean you're on your own for security design. WAIaaS has a 3-layer security model built in:

Layer 1: Authentication — Three separate auth methods: masterAuth (Argon2id hashing) for admin operations, ownerAuth (SIWE/SIWS cryptographic signatures) for the fund owner, and sessionAuth (JWT) for the AI agent. The agent never touches the master password.
Layer 2: Policy engine — 21 policy types with 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL). Default-deny enforcement means a transaction to an address not on the whitelist is blocked, not just flagged. You configure what's allowed; everything else is rejected.
Layer 3: Monitoring and kill switch — Incoming transaction monitoring with real-time notifications, and the ability to approve or reject pending transactions via WalletConnect before they execute.

For a self-hosted context, the kill switch is particularly meaningful. Large transactions can require your explicit approval before they go through. Your agent proposes; you approve. The approval request comes to you via WalletConnect, which means you can approve or reject from your phone even if you're not at your desk.

Keeping the Daemon Updated

WAIaaS's Docker setup is compatible with Watchtower for automatic image updates. If you run Watchtower in your homelab stack, you can point it at the waiaas-daemon container and get updates automatically when new images are published. Combined with the named data volume, updates don't touch your wallet data.

Basic compose operations for day-to-day use:

docker compose up -d          # Start daemon
docker compose logs -f        # Follow logs
docker compose down           # Stop (data preserved in named volume)

The Interactive API Docs Live Locally

Because this is self-hosted, the API documentation also runs on your own machine. WAIaaS auto-generates an OpenAPI 3.0 spec and serves an interactive Scalar API reference UI:

# Download OpenAPI 3.0 spec
curl http://127.0.0.1:3100/doc -o openapi.json

# View interactive API reference
open http://127.0.0.1:3100/reference

No external documentation site required. The reference is generated from the actual running code, so it always reflects what your instance supports — all 39 REST API route modules.

Quick Start Summary

Five steps from nothing to a running AI agent wallet:

git clone https://github.com/waiaas/WAIaaS.git && cd WAIaaS
docker compose up -d
npm install -g @waiaas/cli && waiaas init --auto-provision
waiaas quickset — creates wallets, sessions, and prints MCP config
Paste the MCP config into Claude Desktop and start chatting with your wallet

For production: add your RPC endpoints to .env, create a secrets directory, and deploy with the secrets overlay. That's the full hardened setup.

What's Next

The wallet daemon is the foundation — but what you build on top of it is where things get interesting. The 45 MCP tools expose everything from balance queries to DeFi position management to the AI agent, and the policy engine gives you fine-grained control over what the agent is actually allowed to do with those capabilities.

*The full source code, Dockerfiles, and compose files are at https://github.com/waiaas/WAIaaS. Documentation and the official site live at https://waiaas.ai.* Your keys. Your server. Your rules.