CLI Disaster Recovery: backup, restore, and inspect Commands for Self-Hosted Wallets

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.

Why Self-Hosting Changes the Risk Profile

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.

The Three Commands You Need to Know

WAIaaS CLI includes 20 commands (fact CLI-01). Three of them form the complete disaster recovery workflow:

backup create — Snapshot the current wallet state to an archive
backup list — Show all available backups with timestamps and metadata
backup inspect — Examine the contents of a specific backup before restoring
restore — Recover wallet state from a backup archive

Let's walk through each one in context.

Starting From a Running Instance

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.

Creating a Backup

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:

# Create a backup
waiaas backup create

# Then copy the latest backup file off-box
# (rsync, rclone, S3, whatever fits your setup)

The specific destination is yours to choose — WAIaaS creates the archive, you own the transport layer.

Inspecting Backups Before You Trust Them

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.

Listing Available Backups

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.

Restoring From a Backup

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.

Production Hardening: Secrets and Credentials

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:

# 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

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

# Retrieve auto-generated master password
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
# Then: rm /data/recovery.key (or equivalent path)

A Minimal Backup Routine for Self-Hosters

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.

Why the CLI Approach Works Well for Self-Hosters

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.

What's Next

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.

推荐订阅源

DEV Community