Backing up a self-hosted wallet is one of those tasks that feels optional right up until the moment it isn't — and for AI agents managing real funds on your own server, a failed drive or a misconfigured Docker volume can mean permanent loss. WAIaaS ships a built-in CLI disaster recovery workflow with backup create
, backup inspect
, and backup list
commands designed specifically for operators who have chosen to run their own wallet infrastructure rather than hand keys to a third party.
When you use a hosted wallet service, the provider handles backups, redundancy, and key recovery. You trade control for convenience. But if you're running WAIaaS on your own hardware or VPS — your keys, your server, your rules — the responsibility for data durability sits entirely with you.
That's not a downside. It's the whole point. You get no API rate limits from an external service, no terms-of-service changes that could freeze your agent's funds overnight, and no third-party ever touches your private keys. The crypto equivalent of running your own email server — except WAIaaS is actually practical to operate. The tradeoff is that operational discipline matters more. A self-hosted wallet with no backup strategy is one bad docker compose down -v
away from disaster. The CLI makes that discipline easy to maintain.
WAIaaS CLI includes 20 commands (fact CLI-01). Three of them form the complete disaster recovery workflow:
backup create
backup list
backup inspect
restore
Let's walk through each one in context.
Before you can back anything up, you need a running WAIaaS daemon. If you haven't set one up yet, the fastest path is:
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
Or via Docker, which many self-hosters prefer since it keeps the process isolated and restartable:
git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d
With the daemon running on 127.0.0.1:3100
(fact DOCKER-02), you now have wallet data worth protecting.
The backup create
command snapshots your current wallet state. Run it after any significant configuration change — new wallets, updated policies, or new session tokens issued to agents.
waiaas backup create
That's the whole command. WAIaaS handles the rest: serializing wallet keys, policy configurations, session metadata, and anything else needed to reconstruct a working instance. The result is a timestamped archive stored in your data directory.
For Docker deployments, wallet data lives in the named volume defined in docker-compose.yml
:
volumes:
waiaas-data:
driver: local
This means your backups persist across container restarts and even across image upgrades — docker compose down
(without -v
) leaves your data intact. But the volume is still on a single host. A good backup strategy copies that archive off-box.
A practical routine for a homelab setup:
waiaas backup create
The specific destination is yours to choose — WAIaaS creates the archive, you own the transport layer.
Here's the part most operators skip: verifying that a backup is actually usable before you need it. backup inspect
lets you examine the contents of a backup file without restoring it.
waiaas backup inspect
This is useful in two scenarios. First, as part of a regular health check — run it weekly to confirm your backups contain the wallet IDs and configuration you expect. Second, before a restore — when you're recovering from an incident, you want to confirm you're restoring the right snapshot, not an old one that's missing recently created wallets.
The inspect command gives you visibility into what's inside the archive: which wallets are included, timestamps, and structural integrity. Think of it as tar -tvf
for your wallet infrastructure.
When you need to choose between multiple restore points, backup list
shows you what's available:
waiaas backup list
This is particularly useful if you've automated backup creation (a cron job or a post-deploy hook, for example) and have accumulated multiple snapshots. You can identify the most recent clean backup, compare timestamps against when you last made a configuration change, and pick the right restore point before committing.
When the moment comes — hardware failure, accidental docker compose down -v
, a botched config migration — restore
gets you back:
waiaas restore
The restore command reconstructs your wallet state from the backup archive. After restore, you'll want to verify the daemon is healthy:
waiaas status
And if you're running Docker, confirm the health check passes:
docker compose logs -f
The Docker Compose configuration includes a built-in health check (fact FEAT-DOCKER):
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
interval: 30s
timeout: 5s
start_period: 10s
retries: 3
Once the daemon is healthy again, your AI agents can reconnect using their existing session tokens — nothing on the agent side needs to change.
For production self-hosted deployments, WAIaaS supports Docker Secrets via a secrets overlay file (fact DOCKER-04). This keeps your master password out of environment variables and shell history:
mkdir -p secrets
echo "your-secure-password" > secrets/master_password.txt
chmod 600 secrets/master_password.txt
docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d
The entrypoint also supports WAIAAS_AUTO_PROVISION
for headless first-run scenarios (fact DOCKER-03):
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
docker exec waiaas cat /data/recovery.key
recovery.key
is the credential you absolutely need to include in your backup strategy. Back it up separately from the wallet data archive, stored in a different physical location. If you lose the wallet archive, you can rebuild. If you lose the master password, you cannot.
Once you've manually set a hardened password, delete recovery.key
:
waiaas set-master
Here's a concrete routine that covers the fundamentals without overcomplicating things:
Step 1: Initial setup with auto-provision
waiaas init --auto-provision
waiaas start
waiaas quickset
Step 2: Create your first backup immediately after setup
waiaas backup create
Step 3: Inspect it to confirm it's good
waiaas backup inspect
Step 4: Copy it somewhere else. Your NAS, an encrypted S3 bucket, a USB drive kept offline — anywhere that isn't the same disk. WAIaaS creates the archive; you handle the transport.
Step 5: Set a calendar reminder to run backup create
backup inspect
after any significant change to wallets or policies, and on a regular schedule regardless.
That's it. Five steps, most of which take seconds. The goal isn't a perfect enterprise DR strategy — it's not losing months of wallet configuration and key material because you forgot to plan ahead.
Hosted services abstract away backup and recovery entirely. That's convenient, but it means you're dependent on the provider's infrastructure, their uptime, their policies, and their continued existence. Self-hosting with WAIaaS means none of those dependencies apply — but it also means the CLI is your primary operational interface, and these three commands are genuinely critical.
The WAIaaS CLI has 20 commands total (fact CLI-01), covering everything from daemon management (start
, stop
, status
) to wallet operations (wallet create
, wallet info
) to the MCP integration setup (mcp setup
) that connects your wallets to AI agents. Backup and restore are first-class citizens in that list — not afterthoughts.
Combined with the 683+ test files across the codebase (fact TEST-01) and a 7-stage transaction pipeline with validation built in (fact PIPE-01), WAIaaS is built with the kind of operational rigor that makes self-hosting viable rather than heroic.
If you're running a self-hosted WAIaaS instance, the next logical step is locking down what your AI agents can actually do with those wallets. The policy engine supports 21 policy types across 4 security tiers (fact POLICY-01, POLICY-02) — from simple spending limits to DeFi-specific controls like PERP_MAX_LEVERAGE
and LENDING_LTV_LIMIT
. Combine solid backup hygiene with a well-configured policy set, and you have wallet infrastructure that's both recoverable and defensible.
Explore the full source code and documentation at github.com/minhoyoo-iotrust/WAIaaS, or visit waiaas.ai to learn more about what the platform can do.