Automated Backup and Recovery for Self-Hosted AI Wallets: Docker + CLI Integration

Would you trust a third party with your AI agent's private keys? If you're running AI agents that hold real funds, that's not a rhetorical question — it's the difference between owning your infrastructure and renting it. Self-hosting your wallet backend means no third-party custody, no surprise API rate limits, and no one between your agents and their assets. But self-hosting comes with a responsibility that hosted services quietly handle for you: backups.

Why Backup Strategy Matters More When You're in Control

The appeal of self-hosted wallet infrastructure is ownership. Your keys live on your server, your agents talk to your daemon, and no external company can freeze your account or throttle your requests. But that ownership cuts both ways. If your server catches fire — metaphorically or literally — and you haven't thought through recovery, those keys are gone.

This isn't unique to wallets. Anyone who runs their own email server, their own Nextcloud instance, or their own Gitea knows the deal: the freedom is real, and so is the homework. The good news is that WAIaaS, an open-source self-hosted Wallet-as-a-Service for AI agents, has backup and recovery built directly into both its CLI and its Docker deployment model. You don't have to bolt it on yourself.

What You're Actually Backing Up

Before diving into commands, it helps to understand what matters. WAIaaS stores its state in a data directory (/data inside Docker, ~/.waiaas by default outside it). That directory contains your encrypted wallet keys, session configuration, policies, and any other daemon state. The master password — which you either set yourself or auto-generate at first run — is the encryption key for everything inside.

Lose the data directory without a backup: gone. Lose the master password without recording it: also gone, even if the data directory survives. A complete backup strategy covers both.

The CLI Backup Commands

WAIaaS ships with a CLI (@waiaas/cli) that includes dedicated backup tooling as part of its 20 commands. The relevant ones for backup and recovery are:

• backup create — create a new backup
• backup inspect — examine the contents of a backup file
• backup list — list available backups
• restore — restore from a backup

These aren't afterthoughts. They're first-class commands sitting alongside wallet create, start, stop, and the rest of the operational toolkit.

Creating a Backup

npm install -g @waiaas/cli

# Create a backup
waiaas backup create

This snapshots your current daemon state into a portable backup file. You'd typically run this after making significant changes — creating new wallets, updating policies, adding sessions — and on a regular schedule via cron.

Inspecting What You've Got

Before you trust a backup file, it's worth knowing what's in it:

waiaas backup inspect

This lets you verify the backup contains what you expect before you ever need to use it for recovery. Running this as part of your backup workflow (create, then inspect) gives you confidence the file is valid, not just present.

Listing Your Backups

waiaas backup list

When you're staring at a recovery situation at 2am, knowing exactly which backups exist and when they were created matters. This command gives you that view.

Restoring from Backup

waiaas restore

The restore command brings your daemon state back from a backup file. Combined with your master password (which you've stored separately and securely), this is your full recovery path.

Docker Integration: Where Self-Hosters Live

If you're running WAIaaS in Docker — which is the recommended production deployment — the backup strategy plugs naturally into the container model.

The Basic Setup

WAIaaS publishes two Docker images: the main daemon and a push-relay for notification signing. The daemon image is ghcr.io/waiaas/waiaas:latest, and the default port binding is 127.0.0.1:3100:3100, keeping the API off the public interface by default.

The simplest production-ready Docker Compose setup looks like this:

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

Notice the named volume waiaas-data. This is your primary target for backups. Docker named volumes persist independently of the container lifecycle — you can docker compose down and your data survives. But they don't survive docker compose down -v, and they definitely don't survive a failed disk.

Auto-Provision: Securing the Master Password

For self-hosters who want a clean first-run experience, the Docker entrypoint supports WAIAAS_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/waiaas/waiaas:latest

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

The auto-provision flow generates a random master password and writes it to recovery.key inside the data directory. Treat this file like a root CA private key. Copy it out of the container immediately, store it somewhere offline (a password manager, an encrypted USB drive, a piece of paper in a fireproof safe — pick your threat model), and then optionally harden it later:

waiaas set-master   # Replace auto-generated password with one you chose

Once you've set a proper master password, delete recovery.key from the data directory. The recovery key was a bootstrap mechanism, not a permanent secret.

Production Secrets Overlay

For production deployments, WAIaaS supports Docker Secrets via a secrets overlay file (docker-compose.secrets.yml). This keeps sensitive values out of environment variables and out of your shell history:

# 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

Docker Secrets mount files into the container rather than exposing values as environment variables, which matters if you're running in environments where docker inspect output might be logged or observable.

A Practical Backup Workflow for Self-Hosters

Here's a complete workflow that combines the CLI backup commands with Docker volume management:

Step 1: Start with a solid foundation

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

Step 2: Initialize with auto-provision (optional but recommended)

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

# Save the generated master password somewhere safe — RIGHT NOW
docker exec waiaas cat /data/recovery.key

Step 3: Create your first backup after setup

# After creating wallets, sessions, and policies
waiaas backup create

# Verify it looks right
waiaas backup inspect

# See what's available
waiaas backup list

Step 4: Automate with cron

A daily backup cron job is the minimum viable schedule for any self-hosted service that changes frequently. Something like:

0 3 * * * waiaas backup create && waiaas backup inspect

The inspect after create gives you a canary — if the backup file is malformed, the inspect will surface that, and you can alert on the exit code.

Step 5: Test your restore path

The most common backup failure mode isn't the backup itself — it's never testing the restore. Spin up a second instance, point it at a backup, run waiaas restore, and verify your wallets and policies come back correctly. Do this before you ever need it in production.

Recovery: When Things Go Wrong

If you need to recover from a backup:

# On a fresh system with the CLI installed
waiaas init          # Set up the data directory structure
waiaas restore       # Point at your backup file
waiaas start         # Start the daemon with restored state

You'll need your master password at the restore step. This is why offline storage of the master password isn't optional — it's the decryption key for everything in the backup.

The Philosophy: Your Keys, Your Server, Your Rules

Running WAIaaS self-hosted puts you in the same position as running your own mail server: you get full control, full privacy, and full responsibility. No third party can see your agent's transactions, throttle its API calls, or decide your use case violates their terms of service. Your agents talk to a daemon you control, on a server you own, with keys that never leave your infrastructure.

The Docker deployment is designed to make this practical rather than painful. The healthcheck (curl -f http://localhost:3100/health) means container orchestration tools can detect and restart a failed daemon automatically. The non-root UID (1001) inside the container follows container security best practices. The named volume means your data outlives any individual container. And the backup CLI means recovery is a documented, testable process rather than a disaster-recovery improvisation.

What's Next

The backup and restore workflow is the foundation of responsible self-hosting — but it's only the operational layer. Once you've got that solid, the next interesting territory is locking down what your AI agents can actually do: WAIaaS's policy engine gives you 21 policy types and 4 security tiers to constrain agent behavior, and pairing that with the MCP integration means your Claude or GPT-based agent has a well-guarded wallet rather than an open one.

Explore the codebase and deployment docs at https://github.com/waiaas/WAIaaS, and learn more about the full platform at https://waiaas.ai. If you're already running self-hosted infrastructure, WAIaaS slots into that world naturally — it's Docker Compose and a CLI, not a SaaS signup form.