DEV Community

Cover image for Auto-Provision Your Self-Hosted Crypto Wallet: Docker Entrypoint Magic
Wallet Guy
Wallet Guy

Posted on

Auto-Provision Your Self-Hosted Crypto Wallet: Docker Entrypoint Magic

#docker #devops #opensource #selfhosted

Setting up self-hosted crypto wallet infrastructure typically requires juggling database schemas, RPC endpoints, and security configurations before you can even start managing funds. Docker auto-provisioning changes this by generating secure defaults automatically, letting you bootstrap a complete Wallet-as-a-Service in a single command while maintaining full control over your infrastructure and private keys.

Why Self-Hosting Your Wallet Infrastructure Matters

When you're building AI agents that need to handle cryptocurrency transactions, you face a fundamental choice: trust a third-party service with your keys, or maintain your own infrastructure. Self-hosting isn't just about privacy — it's about eliminating external dependencies, avoiding API rate limits, and ensuring your agents can operate without relying on services that could disappear, change pricing, or impose restrictions.

The challenge has always been complexity. Traditional wallet infrastructure requires deep blockchain knowledge, security expertise, and significant setup time. WAIaaS's Docker auto-provisioning solves this by generating secure configurations automatically while preserving the sovereignty benefits of self-hosting.

The Auto-Provision Solution

WAIaaS includes an auto-provision feature that generates all necessary secrets, configurations, and initial setup automatically. When you enable auto-provisioning, the Docker container creates a master password, initializes the database, and saves recovery credentials — all without requiring manual intervention.

Here's how to deploy a complete self-hosted wallet service in seconds:

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 auto-provision process generates a cryptographically secure master password, stores it in /data/recovery.key, and immediately starts the daemon. Your wallet service is ready to create wallets and authenticate AI agents without any manual configuration.

Docker Compose for Production Deployments

For production self-hosting, Docker Compose provides better control over the deployment:

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
      - WAIAAS_AUTO_PROVISION=true
    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
Enter fullscreen mode Exit fullscreen mode

This configuration includes health checks, automatic restart policies, and named volumes for data persistence. The service binds to localhost by default, ensuring your wallet API isn't exposed to external networks without explicit configuration.

Security Through Docker Secrets

For production deployments, WAIaaS supports Docker Secrets for secure credential management. Instead of auto-provisioning, you can provide your own master password through the secrets system:

# 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 mounts your password file into the container without exposing it in environment variables or command line arguments. This approach gives you control over credential generation while maintaining Docker best practices.

Environment Configuration for Self-Hosters

Self-hosting means you control every aspect of the infrastructure. WAIaaS exposes key configuration through environment variables:

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
Enter fullscreen mode Exit fullscreen mode

By providing your own RPC endpoints, you eliminate dependency on public nodes and gain better performance and reliability. Many self-hosters run their own blockchain nodes or use private RPC services for complete infrastructure control.

Data Persistence and Backup Strategy

The Docker entrypoint creates all data in the configured data directory (/data by default). This includes:

  • SQLite database with wallet data
  • Generated private keys (encrypted)
  • Session tokens and authentication state
  • Policy configurations
  • Transaction history

Since everything lives in a single directory, backup becomes straightforward:

# Backup data volume
docker run --rm -v waiaas-data:/data -v $(pwd):/backup alpine tar czf /backup/waiaas-backup.tar.gz -C /data .

# Restore data volume
docker run --rm -v waiaas-data:/data -v $(pwd):/backup alpine tar xzf /backup/waiaas-backup.tar.gz -C /data
Enter fullscreen mode Exit fullscreen mode

This approach gives you complete control over your backup strategy and recovery procedures.

Container Security Considerations

The WAIaaS Docker image runs as a non-root user (UID 1001) and includes security scanning in the build process. The container exposes only the necessary port (3100) and doesn't require privileged access. For additional security, you can run the container with read-only filesystem and tmpfs mounts:

docker run -d \
  --name waiaas \
  --read-only \
  --tmpfs /tmp \
  -p 127.0.0.1:3100:3100 \
  -v waiaas-data:/data \
  -e WAIAAS_AUTO_PROVISION=true \
  ghcr.io/minhoyoo-iotrust/waiaas:latest
Enter fullscreen mode Exit fullscreen mode

This configuration prevents any writes outside the data volume, reducing attack surface while maintaining full functionality.

Quick Start: Self-Hosted Wallet in 5 Steps

  1. Deploy with auto-provision: 
   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
Enter fullscreen mode Exit fullscreen mode
  1. Retrieve master password: 
   docker exec waiaas cat /data/recovery.key
Enter fullscreen mode Exit fullscreen mode
  1. Create your first wallet: 
   curl -X POST http://127.0.0.1:3100/v1/wallets \
     -H "Content-Type: application/json" \
     -H "X-Master-Password: $(docker exec waiaas cat /data/recovery.key)" \
     -d '{"name": "trading-wallet", "chain": "solana", "environment": "mainnet"}'
Enter fullscreen mode Exit fullscreen mode
  1. Create AI agent session: 
   curl -X POST http://127.0.0.1:3100/v1/sessions \
     -H "Content-Type: application/json" \
     -H "X-Master-Password: $(docker exec waiaas cat /data/recovery.key)" \
     -d '{"walletId": "<wallet-uuid>"}'
Enter fullscreen mode Exit fullscreen mode
  1. Test with balance check: 
   curl http://127.0.0.1:3100/v1/wallet/balance \
     -H "Authorization: Bearer <session-token>"
Enter fullscreen mode Exit fullscreen mode

Your self-hosted wallet infrastructure is now ready to serve AI agents with full transaction capabilities, 39 REST API routes, and 15 integrated DeFi protocols.

Related Posts

Docker Deployment Guide: Self-Hosted AI Agent Wallets provides comprehensive Docker deployment strategies beyond auto-provisioning.

Policy-Based Security for AI Agent Wallets covers how to configure the 21 policy types and 4 security tiers after your initial deployment.

What's Next

You now have a self-hosted wallet service with auto-provisioned security running in Docker. Explore the interactive API documentation at http://127.0.0.1:3100/reference to discover all available endpoints, or check the full deployment guide at GitHub and learn more about production configurations at waiaas.ai.

Top comments (0)