Docker Network Security: Binding Your AI Wallet to 127.0.0.1:3100
Docker deployment for AI wallet infrastructure brings unique security considerations, especially when running locally with access to private keys. The default port binding of 127.0.0.1:3100:3100 in WAIaaS provides essential network isolation, but understanding why this matters could save your AI agent's funds from unauthorized access.
When you're self-hosting wallet infrastructure, every network configuration decision becomes a security boundary. Unlike hosted services where the provider manages security, your Docker containers become the front line of defense for your AI agent's private keys and transaction capabilities.
Why localhost binding matters for wallet security
Self-hosted wallet services face a critical challenge: they need to be accessible to your AI agents while remaining isolated from external threats. A misconfigured network binding can expose your wallet API to the entire internet, creating attack vectors that don't exist in traditional web applications.
Unlike a typical web app that handles user sessions, a wallet service has direct access to private keys and can sign transactions worth real money. The blast radius of a security breach extends beyond data theft to immediate financial loss through unauthorized transactions.
The WAIaaS security model
WAIaaS implements network security through careful localhost binding in its Docker configuration. Here's the default setup that prioritizes security:
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
start_period: 10s
retries: 3
The 127.0.0.1:3100:3100 binding ensures that only processes running on your local machine can reach the wallet API. Even if your firewall has other openings, this container remains isolated from external network traffic.
Understanding the binding syntax
Docker's port binding syntax follows the pattern host_ip:host_port:container_port. Let's break down what different configurations mean for security:
# SECURE: Only localhost access
-p 127.0.0.1:3100:3100
# DANGEROUS: Accessible from any network interface
-p 3100:3100
-p 0.0.0.0:3100:3100
# NETWORK-SPECIFIC: Only accessible from specific subnet
-p 192.168.1.100:3100:3100
The secure configuration means your AI agents running on the same machine can access http://127.0.0.1:3100, but external attackers cannot reach the service even if they gain network access to your host.
Authentication layers beyond network binding
While localhost binding provides the first security layer, WAIaaS implements multiple authentication methods for different access patterns:
# masterAuth — system administrator access
curl -X POST http://127.0.0.1:3100/v1/wallets \
-H "X-Master-Password: my-secret-password" \
-d '{"name": "trading-wallet", "chain": "solana"}'
# sessionAuth — AI agent access with limited permissions
curl http://127.0.0.1:3100/v1/wallet/balance \
-H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."
# ownerAuth — human approval for high-value transactions
curl -X POST http://127.0.0.1:3100/v1/transactions/<tx-id>/approve \
-H "X-Owner-Signature: <ed25519-signature>" \
-H "X-Owner-Message: <signed-message>"
Each authentication method serves a different security tier. Network binding ensures these authentication challenges happen only for legitimate local processes, not external attackers.
Policy-based transaction controls
Beyond authentication, WAIaaS implements 21 policy types with 4 security tiers to control what authenticated agents can do:
curl -X POST http://127.0.0.1:3100/v1/policies \
-H "Content-Type: application/json" \
-H "X-Master-Password: my-secret-password" \
-d '{
"walletId": "<wallet-uuid>",
"type": "SPENDING_LIMIT",
"rules": {
"instant_max_usd": 100,
"notify_max_usd": 500,
"delay_max_usd": 2000,
"delay_seconds": 900,
"daily_limit_usd": 5000
}
}'
This creates a spending policy where transactions under $100 execute instantly, amounts up to $500 trigger notifications, transactions up to $2000 wait 15 minutes (allowing cancellation), and anything higher requires human approval. Even if an attacker somehow reached your API, these policies limit potential damage.
Production network considerations
For production deployments that need network access beyond localhost, WAIaaS supports Docker Secrets for secure credential management:
# Create secret files with proper permissions
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 overlay allows you to gradually expand network access while maintaining credential security through Docker's built-in secrets management.
Health monitoring and failure detection
The default Docker configuration includes health checks that verify the service is responding correctly:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
interval: 30s
timeout: 5s
start_period: 10s
retries: 3
These health checks run inside the container, so they work regardless of external network accessibility. Your monitoring systems can check container health status without needing direct API access.
Integration with reverse proxies
If you need to expose the wallet service through a reverse proxy (for multi-machine AI setups), you can maintain localhost binding and let the proxy handle external access:
# WAIaaS remains on localhost
-p 127.0.0.1:3100:3100
# Reverse proxy (nginx, traefik, etc.) handles external exposure
# with its own authentication, rate limiting, and SSL termination
This architecture keeps the wallet service itself isolated while allowing controlled external access through your proxy's security policies.
Common misconfigurations to avoid
Several Docker networking patterns that work fine for web applications create security risks for wallet services:
# DON'T: Exposes wallet API to entire network
docker run -p 3100:3100 ghcr.io/minhoyoo-iotrust/waiaas:latest
# DON'T: Binds to all interfaces
docker run -p 0.0.0.0:3100:3100 ghcr.io/minhoyoo-iotrust/waiaas:latest
# DON'T: Uses host networking (inherits all host ports)
docker run --network=host ghcr.io/minhoyoo-iotrust/waiaas:latest
These configurations might seem convenient for development, but they eliminate the network isolation that protects your private keys and transaction signing capabilities.
Quick start with secure defaults
Get WAIaaS running with secure network binding in minutes:
- Clone and start with secure defaults:
git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d
- Verify localhost-only binding:
docker port waiaas-daemon
# Should show: 3100/tcp -> 127.0.0.1:3100
- Test local access works:
curl http://127.0.0.1:3100/health
# Should return: {"status": "ok"}
- Confirm external access is blocked:
curl http://<your-external-ip>:3100/health
# Should fail to connect (connection refused)
- Set up your AI agent with the localhost endpoint:
export WAIAAS_BASE_URL=http://127.0.0.1:3100
# Your AI agents use this URL for wallet operations
The secure defaults mean you can start developing immediately while maintaining proper network isolation for your wallet infrastructure.
Network security for AI wallet services starts with proper Docker port binding, but extends through authentication, policies, and monitoring. The 127.0.0.1:3100:3100 default in WAIaaS provides essential isolation while maintaining accessibility for your local AI agents.
Ready to deploy your own secure AI wallet infrastructure? Check out the complete setup guide at waiaas.ai or explore the open-source implementation at github.com/minhoyoo-iotrust/WAIaaS. Your keys, your server, your rules.