20 CLI Commands for Complete Self-Hosted Wallet Management: From Setup to Backup

2026-09-18

20 CLI Commands for Complete Self-Hosted Wallet Management: From Setup to Backup

Self-hosted wallet management for AI agents means your private keys never leave your server — and WAIaaS gives you a full CLI with 20 commands to set up, operate, and back up your entire wallet infrastructure without trusting a single third party. If you've ever run your own email server, your own VPN, or your own Nextcloud instance, you already understand the philosophy: ownership is worth the extra ten minutes of setup.

Why Self-Hosting Your Agent's Wallet Actually Matters

Here's the uncomfortable question: would you hand your private keys to a hosted service you don't control, just because it's convenient? For personal wallets, most people already know the answer. For AI agent wallets, the question is even sharper. An agent wallet isn't just holding funds — it's actively executing transactions, interacting with DeFi protocols, and potentially moving significant value on your behalf.

Hosted wallet services come with trade-offs that are easy to overlook: rate limits that can stop your agent mid-task, API terms that can change overnight, custody arrangements where someone else technically controls your keys, and privacy implications around transaction metadata. Self-hosting eliminates all of that. WAIaaS runs entirely on your hardware, behind your firewall, with your keys in your encrypted data directory. No phone-home, no usage telemetry you didn't consent to, no third-party rate limits.

The CLI is how you manage all of it from the terminal — which is exactly where self-hosters want to be.

The 20 Commands, Organized by What You're Actually Doing

WAIaaS ships a CLI with exactly 20 commands (fact CLI-01). Rather than dumping them as a flat list, here's how they map to the actual lifecycle of running your own wallet infrastructure.

Getting Started: init, start, stop, status, quickstart, quickset

Everything begins with init. This creates your data directory and config.toml. It's the git init of your wallet infrastructure.

npm install -g @waiaas/cli
waiaas init                    # Create data directory + config.toml
waiaas start                   # Start daemon (sets master password on first run)
waiaas quickset --mode mainnet # Create wallets + MCP sessions in one step

quickstart gets you running with sensible defaults in the least number of steps. quickset is slightly more deliberate — it creates wallets and MCP sessions for you but lets you specify a mode. For self-hosters who want to automate first-run provisioning (say, in a Docker entrypoint or an Ansible playbook), there's an auto-provision flag:

waiaas init --auto-provision   # Generates random master password → recovery.key
waiaas start                   # No password prompt
waiaas quickset                # Creates wallets + sessions automatically
waiaas set-master              # (Later) Harden password, then delete recovery.key

That pattern — auto-provision for first boot, set-master to harden later — is exactly what you want for unattended server deployments. The recovery.key file holds your auto-generated master password. Lock it down, back it up, then replace it with something you've chosen yourself once you're ready.

stop and status are exactly what they sound like. status is particularly useful for health-checking from a monitoring script or a cron job.

Wallet Operations: wallet create, wallet info

Once your daemon is running, you create wallets:

waiaas wallet create   # Interactive wallet creation
waiaas wallet info     # Show wallet details, address, chain

Under the hood, wallet creation is also exposed via the REST API if you want to script it:

curl -X POST http://127.0.0.1:3100/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"name": "trading-wallet", "chain": "solana", "environment": "mainnet"}'

The CLI wraps this in an interactive flow, which is friendlier for manual setup. For automation, the API is the right tool. Both paths lead to the same place: a wallet whose keys live in your encrypted local data directory, on hardware you control.

WAIaaS supports 2 chain types (EVM and Solana) across 18 networks (fact NET-01). That covers the chains where most real AI agent activity happens today.

Session Management: session prompt, set-master

Sessions are how AI agents authenticate. You create a session token, hand it to your agent (via environment variable, MCP config, or SDK constructor), and the agent uses it to sign transactions, check balances, and execute DeFi actions — all scoped to a specific wallet.

session prompt generates a session token interactively. set-master lets you change or harden your master password — the root credential that protects everything else.

WAIaaS uses three distinct auth layers (fact SEC-02):

This separation matters for self-hosters. Your master password stays on the server. Your session tokens are scoped and can be rotated without touching your keys. Your owner auth is a signature from a wallet you control independently — it's the kill switch that doesn't depend on the server at all.

Owner Control: owner connect, owner disconnect, owner status

The owner commands hook into WalletConnect (fact FEAT-WC), letting you connect your personal wallet as the fund owner. This is how you approve transactions that exceed your policy thresholds — the agent submits a transaction, the policy engine routes it to APPROVAL tier, and you get a notification to your connected wallet app.

waiaas owner connect    # Connect owner wallet via WalletConnect
waiaas owner status     # Check connected owner wallet
waiaas owner disconnect # Disconnect owner wallet

For self-hosters, this is the human-in-the-loop bridge. Your AI agent can operate autonomously within the spending limits and whitelists you've defined, but anything that exceeds those limits requires your explicit cryptographic approval. No third party can approve transactions on your behalf — that's the point.

Notifications: notification setup

waiaas notification setup   # Configure notification channels

WAIaaS supports multiple signing channels including push relay, Telegram, and wallet notification channels (fact SIGN-01). notification setup walks you through connecting one of them. Self-hosters who run their own Telegram bots or push notification infrastructure can route alerts through those.

MCP Integration: mcp setup

waiaas mcp setup --all   # Auto-register all wallets with Claude Desktop

This is the command that takes your self-hosted daemon and wires it into AI agent frameworks like Claude Desktop. It writes the MCP server configuration JSON that Claude (or any MCP-compatible client) reads at startup. The --all flag registers every wallet you've created as a separate MCP server entry.

The MCP package (@waiaas/mcp) exposes 45 tools (fact MCP-01) covering wallet queries, transactions, DeFi actions, NFT operations, and x402 payment handling. After running mcp setup, your AI agent can check balances, swap tokens, query DeFi positions, and more — all authenticated through the session token scoped to the wallet you've configured.

A typical multi-wallet MCP config looks like this:

{
  "mcpServers": {
    "waiaas-trading": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c47d6-51ef-7f43-a76b-d50e875d95f4",
        "WAIAAS_AGENT_NAME": "trading-agent",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    },
    "waiaas-solana": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c4cd2-86e8-758f-a61e-9c560307c788",
        "WAIAAS_AGENT_NAME": "solana-wallet",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

The daemon is running locally, the base URL points to 127.0.0.1:3100, and no traffic goes to an external service. That's self-hosted MCP wallet infrastructure in the most literal sense.

Backup and Restore: backup create, backup inspect, backup list, restore

This is where self-hosting gets serious. If you're running your own infrastructure, you're responsible for your own backups. WAIaaS gives you four commands to manage this properly.

waiaas backup create   # Create an encrypted backup of wallet data
waiaas backup list     # List available backups
waiaas backup inspect  # Inspect a specific backup file
waiaas restore         # Restore from a backup

The backup create command should be part of your regular cron schedule. Backup to an encrypted external drive, an S3-compatible bucket you control (MinIO on your NAS works perfectly), or an off-site server you manage. backup inspect lets you verify a backup before you need it — not after. restore gets you back to a known-good state if your server dies.

This is the self-hosted responsibility that hosted services hide from you. It's also the self-hosted superpower: you have the backup, on your hardware, in your custody. Nobody can lose it for you.

Updates: update

waiaas update   # Update the WAIaaS daemon to the latest version

If you're running via Docker (more on that below), Watchtower can handle this automatically. If you're running the CLI-managed daemon directly, update is your command for pulling the latest version.

Running It All in Docker

For homelab setups, Docker is often the cleaner path. WAIaaS ships a production-ready Docker image (fact DOCKER-01):

# Clone and start — that's it
git clone https://github.com/waiaas/WAIaaS.git
cd WAIaaS
docker compose up -d

The default port binding is 127.0.0.1:3100:3100 (fact DOCKER-02) — localhost only, not exposed to the network by default. That's a sensible security default for a service that manages private keys.

For a single-container start with auto-provisioning:

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

For production, use Docker Secrets instead of environment variables for your master password (fact DOCKER-03):

# 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 secrets overlay (docker-compose.secrets.yml, fact DOCKER-04) keeps your credentials out of environment variables and process lists. Healthcheck is built in, the container runs as a non-root user (UID 1001, fact FEAT-DOCKER), and you can wire up Watchtower for automatic updates.

The Policy Layer: Why Your Self-Hosted Agent Isn't Just a Hot Wallet

Running your own wallet infrastructure doesn't mean running without guardrails. WAIaaS includes a policy engine with 21 policy types and 4 security tiers (fact POLICY-01, POLICY-02).

The most important thing to understand about the policy engine is that it's default-deny (fact SEC-03). If you haven't explicitly whitelisted a token or contract, transactions involving it are blocked. This is the right default for an autonomous agent — restrict first, expand as needed.

A basic spending limit policy looks like this:

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
    }
  }'

Under $100: executes immediately. $100–$500: executes and notifies you. $500–$2,000: queues for 15 minutes (cancellable). Over $2,000: requires your explicit approval. You set these thresholds. They live on your server. No hosted service is enforcing them on your behalf — you are.

Quick Start: Five Steps to a Running Self-Hosted Setup

  1. Install the CLI: npm install -g @waiaas/cli
  2. Initialize and start: waiaas init --auto-provision && waiaas start
  3. Create wallets and sessions: waiaas quickset --mode mainnet
  4. Wire up MCP: waiaas mcp setup --all → paste config into Claude Desktop
  5. Schedule backups: waiaas backup create in a daily cron job

That's the full path from zero to a running self-hosted AI agent wallet, with MCP integration and backups in place.

What's Next

The CLI gives you the operational layer — starting, stopping, creating wallets, managing sessions, and keeping backups. The REST API (39 route modules, fact API-01) gives you the programmable layer for integrating WAIaaS into your own tooling and agents. Between the two, you have everything you need to run production wallet infrastructure on hardware you own.

Start with the GitHub repository at https://github.com/waiaas/WAIaaS, or visit https://waiaas.ai for documentation and the full list of supported chains and DeFi protocols. Your keys, your server, your rules.