DEV Community

Cover image for Self-Hosting a Crypto Wallet: Docker Setup Guide
Wallet Guy
Wallet Guy

Posted on

Self-Hosting a Crypto Wallet: Docker Setup Guide

#web3 #ai #opensource #tutorial

Would you trust a third party with your AI agent's private keys? When your autonomous trading bot or DeFi agent is managing real funds, the last thing you want is some hosted service going down, changing their terms, or worse — getting hacked with your keys in their custody. Self-hosting your wallet infrastructure isn't just about control; it's about not becoming another headline in the "exchange hack" news cycle.

Why Self-Hosting Matters for Crypto Infrastructure

The crypto space is littered with the corpses of centralized services that promised to keep user funds safe. From exchange hacks to API outages that freeze trading operations, relying on third parties introduces single points of failure that can destroy months of careful algorithm development in minutes.

But beyond the obvious security benefits, self-hosting your wallet infrastructure gives you something equally valuable: complete operational control. No rate limits throttling your trading algorithms. No surprise API changes breaking your carefully tuned bots. No terms of service updates that suddenly prohibit your use case. When you run your own wallet service, you set the rules.

For AI agents specifically, this control becomes critical. Your agent needs predictable, reliable access to execute trades, manage DeFi positions, and handle payments. A hosted service might work fine during normal market conditions, but when volatility spikes and your agent needs to execute emergency liquidations, the last thing you want is an "API temporarily unavailable" error.

WAIaaS: Self-Hosted Wallet Infrastructure That Actually Works

WAIaaS (Wallet-as-a-Service for AI Agents) solves this problem by giving you enterprise-grade wallet infrastructure that you can run on your own hardware. Think of it as the crypto equivalent of running your own email server — except it's actually practical and doesn't require a PhD in systems administration.

The core philosophy is simple: your keys stay on your hardware, your transactions go through your chosen RPC endpoints, and your policies are enforced by software you control. No phone-home telemetry, no vendor lock-in, no mysterious third-party dependencies that could disappear tomorrow.

What sets WAIaaS apart from just running a basic wallet is its agent-first design. It includes 14 DeFi protocol integrations, a policy engine with 21 policy types and 4 security tiers, and 39 REST API endpoints specifically designed for programmatic access. Your AI agent gets all the sophisticated wallet features it needs, while you maintain complete sovereignty over the infrastructure.

Docker Deployment: From Zero to Running in 60 Seconds

The fastest way to get WAIaaS running on your own hardware is with Docker Compose. The entire setup requires exactly two commands:

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

That's it. The Docker image comes from ghcr.io/minhoyoo-iotrust/waiaas:latest with default port binding on 127.0.0.1:3100:3100, so it's only accessible from your local machine unless you explicitly configure otherwise.

For production deployments, you'll want to use the auto-provision feature to avoid having to set a master password interactively:

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 the auto-generated master password
docker exec waiaas cat /data/recovery.key
Enter fullscreen mode Exit fullscreen mode

The auto-provision mode generates a cryptographically random master password and saves it to /data/recovery.key inside the container. You can retrieve this password, store it securely, and then later use the CLI to set a more memorable password if needed.

Production-Ready Security Features

Self-hosting isn't just about running docker run and hoping for the best. WAIaaS includes several production-ready security features designed specifically for unattended operation.

The Docker entrypoint supports Docker Secrets for secure credential management in swarm deployments. There's also a production secrets overlay via docker-compose.secrets.yml that lets you store sensitive configuration in separate files:

# 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 container runs as a non-root user (UID 1001) and includes built-in health checks. It's designed to work with watchtower for automatic updates, though you probably want to test updates in staging first if you're running trading algorithms.

For high-availability setups, the architecture separates the main daemon from the optional push-relay service. The main image handles all wallet operations and API endpoints, while the push-relay service (packages/push-relay/Dockerfile) handles mobile notifications and external signing workflows. You can scale these independently based on your needs.

Configuration and RPC Management

One of the biggest advantages of self-hosting is controlling your RPC endpoints. Instead of being subject to rate limits from shared infrastructure, you can configure your own endpoints or use premium providers:

WAIAAS_RPC_SOLANA_MAINNET=https://your-solana-node.com
WAIAAS_RPC_EVM_ETHEREUM_MAINNET=https://your-ethereum-node.com
WAIAAS_DAEMON_PORT=3100
WAIAAS_DAEMON_HOSTNAME=0.0.0.0
WAIAAS_DATA_DIR=/data
Enter fullscreen mode Exit fullscreen mode

The system supports 2 chain types (solana, evm) with 15 networks total. You can configure different RPC endpoints for each network, use multiple endpoints for redundancy, or even run your own nodes if you're serious about sovereignty.

For development, you can run everything on testnets without any mainnet risk. The same Docker image works across all networks — just change the environment variables and wallet creation parameters.

Monitoring and Observability

Self-hosted infrastructure is only as good as your ability to monitor it. WAIaaS includes several observability features that make operational monitoring straightforward.

The built-in health check endpoint at /health returns detailed status information about database connectivity, RPC endpoints, and system resources. The Docker Compose configuration includes health check configuration with reasonable defaults:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
  interval: 30s
  timeout: 5s
  start_period: 10s
  retries: 3
Enter fullscreen mode Exit fullscreen mode

Log levels are configurable via WAIAAS_DAEMON_LOG_LEVEL (trace/debug/info/warn/error), and all transaction activity is logged with structured JSON for easy parsing by log aggregation tools.

The OpenAPI 3.0 spec is auto-generated at /doc with an interactive Scalar API reference UI at /reference. This makes it easy to monitor API endpoints and test functionality without writing custom scripts.

Integration with AI Agents

The whole point of self-hosting wallet infrastructure is to give your AI agents reliable access to crypto operations. WAIaaS provides 45 MCP tools for AI agent integration, making it easy to connect agents built on frameworks like Claude, LangChain, or custom implementations.

For Claude Desktop users, the MCP integration requires just a simple configuration file update:

{
  "mcpServers": {
    "waiaas": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_SESSION_TOKEN": "wai_sess_<your-token>",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

For custom agents, the TypeScript SDK (@waiaas/sdk) and Python SDK (waiaas) provide clean, async interfaces with zero external dependencies. The SDKs handle authentication, error handling, and connection management so your agent code can focus on trading logic rather than wallet plumbing.

Getting Started with Self-Hosted WAIaaS

Ready to take control of your AI agent's wallet infrastructure? Here's how to get started:

  1. Clone and start the daemon: git clone https://github.com/minhoyoo-iotrust/WAIaaS.git && cd WAIaaS && docker compose up -d

  2. Install the CLI tools: npm install -g @waiaas/cli

  3. Initialize and create wallets: waiaas quickset --mode mainnet (creates wallets + MCP sessions automatically)

  4. Set up agent integration: waiaas mcp setup --all (auto-registers with Claude Desktop)

  5. Test the connection: Open http://127.0.0.1:3100/reference in your browser to explore the API interactively

Your AI agents now have access to self-hosted wallet infrastructure with no third-party dependencies, no custody risk, and no API rate limits beyond what you configure.

What's Next

This Docker setup gets you running quickly, but there's much more to explore. The policy engine lets you configure sophisticated spending controls and security tiers. The DeFi integrations support everything from Jupiter swaps to Aave lending to Polymarket prediction markets. The notification system can alert you when your agents make large trades or hit policy limits.

Check out the full documentation and source code at https://github.com/minhoyoo-iotrust/WAIaaS, or visit https://waiaas.ai to learn more about building AI agents with self-hosted wallet infrastructure. Your keys, your server, your rules.

Top comments (0)