Your Keys, Your Server, Your Rules: CLI Ownership Management in WAIaaS
Self-hosting your AI agent's wallet infrastructure means you never hand your private keys to a third party — and WAIaaS gives you a complete CLI to manage exactly who controls what, on your own machine. If you've ever asked yourself whether you'd trust a hosted service with the signing keys for an autonomous agent that moves real money, you already know why this matters. This post walks through the three-tier ownership model in WAIaaS and the CLI commands that make it practical to run on your own hardware.
Why Key Custody Is a Different Problem for AI Agents
Running a self-hosted wallet for a human is already a well-understood pattern. Running one for an AI agent is a harder problem because the agent needs to operate autonomously — it can't stop and ask you for a password every time it wants to send a transaction. At the same time, you absolutely cannot give the agent unrestricted signing authority over everything.
Hosted Wallet-as-a-Service products solve this by centralizing custody on their servers. That trades sovereignty for convenience. You get an API key, they hold the keys, and you trust their infrastructure, their security practices, and their uptime. For many use cases that's fine. But if you're building something where privacy matters, where regulatory exposure matters, or where you simply don't want a third party able to freeze your agent's funds, self-hosting is the answer — and it's the crypto equivalent of running your own email server, except WAIaaS makes it genuinely practical in a single Docker command.
The architecture that makes autonomous-but-safe agent wallets work is a three-tier ownership model: a master layer for system administration, an owner layer for fund sovereignty, and a session layer for the agent itself. Each tier has different privileges, different auth methods, and different CLI commands.
The Three Tiers: Master, Owner, Session
Before looking at CLI commands, it helps to understand what each tier is for.
masterAuth is the system administrator role. It uses an Argon2id-hashed password and is used to create wallets, create sessions, set policies, and manage the daemon itself. Think of it as root access to the WAIaaS daemon — you use it at setup time and when you need to change configuration, not during normal agent operation.
ownerAuth is the fund sovereignty layer. It uses SIWS (Sign-In With Solana) or SIWE (Sign-In With Ethereum) signatures — meaning it's tied to a wallet you control independently. The owner can approve pending transactions, connect via WalletConnect, and exercise a kill switch. Crucially, the owner can recover control even if the master password is compromised.
sessionAuth is what the AI agent actually uses. It's a JWT (HS256) with a configurable TTL, max renewals, and absolute lifetime. The agent never touches master or owner credentials — it only holds a session token that can be revoked at any time.
This separation is the security foundation. The agent can't escalate its own privileges, and you can pull the session token without affecting the wallet itself.
Installing the CLI
The CLI is the primary tool for managing a self-hosted WAIaaS installation:
npm install -g @waiaas/cli
Once installed, you have access to 20 commands covering everything from daemon lifecycle to backup and restore.
Setting Up: init, start, and set-master
The fastest path from zero to running daemon:
waiaas init # Create data directory + config.toml
waiaas start # Start daemon (prompts for master password on first run)
If you want a fully unattended first boot — useful for a homelab server or a Docker environment where you can't type a password interactively — use auto-provision:
waiaas init --auto-provision # Generates a random master password → saved to recovery.key
waiaas start # No password prompt
After auto-provision, retrieve your generated master password from recovery.key, store it somewhere safe, and then harden it:
waiaas set-master # Change the master password to something you chose
# After confirming the new password works:
# Delete recovery.key — it's no longer needed
The set-master command is the point where you go from "auto-generated for convenience" to "deliberately chosen and controlled by me." Don't skip it on a production deployment.
Owner Management: owner connect, owner disconnect, owner status
The owner layer is where your personal sovereignty over the funds lives. Connecting an owner means linking a wallet address (Solana or EVM) to the WAIaaS daemon so that you can approve transactions and exercise the kill switch from a wallet you control.
waiaas owner connect # Link your wallet address as the fund owner
waiaas owner status # Check which address is connected as owner
waiaas owner disconnect # Remove the owner connection
Once an owner is connected, high-value transactions that exceed policy thresholds will require an owner signature to proceed. You can approve these via WalletConnect from your phone, or via the Telegram signing channel, or via the push-relay signing channel — three signing channels are supported.
The owner connection is also how you access the kill switch. If an agent session is behaving unexpectedly, the owner can revoke approvals without needing the master password. This is intentional: it means the two roles can be held by different people in a team, or it means that even if someone gets your master password, they can't spend funds without the owner signature on transactions above your policy thresholds.
Session Management: session prompt and the Session API
Sessions are what you hand to the AI agent. They're scoped JWTs — the agent authenticates with the session token, and the token has a TTL, a maximum renewal count, and an absolute lifetime ceiling.
The session prompt command is the CLI interface for managing session interactions:
waiaas session prompt
For creating sessions programmatically (which is the common case when you're wiring up an agent), use the REST API:
# First, create a wallet (masterAuth required)
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"}'
# Then create a session for the agent (masterAuth required)
curl -X POST http://127.0.0.1:3100/v1/sessions \
-H "Content-Type: application/json" \
-H "X-Master-Password: my-secret-password" \
-d '{"walletId": "<wallet-uuid>"}'
The session token returned by that second call is what you put in the agent's environment. The agent uses it for everything it does — checking balances, sending transactions, executing DeFi actions — without ever touching the master password or owner credentials:
# What the agent does with its session token:
curl http://127.0.0.1:3100/v1/wallet/balance \
-H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."
If the agent is compromised, you revoke the session. The wallet and its funds remain intact. The owner connection remains intact. You create a new session with whatever constraints are appropriate and move on.
Quickset: Standing Up a Full Environment in One Step
For people who want to get from install to "Claude has a wallet" as fast as possible, quickset creates wallets and MCP sessions in one command:
waiaas quickset --mode mainnet
This is the "I understand the security model, let me see it working" command. After it completes, you get MCP configuration JSON that you paste into Claude Desktop's config file, or you can auto-register:
waiaas mcp setup --all # Auto-register all wallets with Claude Desktop
After that, Claude has 45 MCP tools available: balance checks, token sends, DeFi actions across 15 integrated protocols, NFT operations, transaction simulation, and more. All going through your self-hosted daemon, with your keys, on your server.
Backup and Restore: backup create, backup list, backup inspect, restore
Self-hosting means you're responsible for your own backups. The CLI has this covered:
waiaas backup create # Create a backup of the current daemon state
waiaas backup list # List all available backups
waiaas backup inspect # Inspect the contents of a specific backup
waiaas restore # Restore from a backup
This is the part that hosted services handle for you behind the scenes. The tradeoff of self-hosting is that you own the backup responsibility. The tradeoff in your favor is that you own the data entirely — it never leaves your infrastructure.
For a homelab or VPS deployment, pair these backup commands with a scheduled job that ships encrypted backups to cold storage. The daemon's data directory is a named Docker volume by default, so backup strategies from the Docker ecosystem apply directly.
Running in Docker: The Practical Path for Self-Hosters
Most self-hosters will want to run WAIaaS in Docker rather than installing Node.js directly on the host. The Docker image is ghcr.io/minhoyoo-iotrust/waiaas:latest and the default port binding is 127.0.0.1:3100:3100 — localhost only by default, which is the right default.
# Clone and start in three commands
git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d
For unattended first boot with 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/minhoyoo-iotrust/waiaas:latest
# Get the auto-generated master password
docker exec waiaas cat /data/recovery.key
For production deployments, use the secrets overlay to avoid putting passwords in environment variables:
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 Docker setup includes a healthcheck out of the box, runs as a non-root user (UID 1001), and supports Watchtower for automatic image updates if you want them. The entrypoint supports auto-provision and Docker Secrets natively.
Putting It Together: The Ownership Model in Practice
Here's the mental model that ties all three tiers together for a self-hosted deployment:
You hold the master password. You use it to create wallets, create sessions, and configure policies. You use it rarely, and never from automated code.
You (via your personal wallet) connect as owner. This gives you the ability to approve high-value transactions and exercise the kill switch from a wallet you already control.
Your agent holds only a session token. It operates within policy constraints you defined. It cannot create new sessions, cannot change policies, cannot access other wallets.
Your policies enforce default-deny. If you haven't explicitly whitelisted a token, a contract, or a recipient, the transaction is blocked. The policy engine has 21 policy types and 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL) to express exactly the risk tolerance you're comfortable with.
Your server runs the daemon. The keys never leave your infrastructure.
This is meaningfully different from the hosted alternative — not just philosophically, but operationally. You control the blast radius of any compromise. You control what data is logged and where. You control uptime and maintenance windows. You control who has access to the admin interface.
Quick Start Summary
npm install -g @waiaas/cliwaiaas init --auto-provision && waiaas start- Retrieve master password:
cat ~/.waiaas/recovery.key -
waiaas quickset --mode mainnet— creates wallets and sessions -
waiaas owner connect— link your personal wallet as fund owner -
waiaas set-master— harden the master password, delete recovery.key -
waiaas mcp setup --all— wire up Claude Desktop
What's Next
The ownership model described here is the foundation — everything else in WAIaaS (DeFi integrations, NFT support, cross-chain bridging, the x402 payment protocol) runs on top of it. Start with the GitHub repository to read the full documentation and see the 15-package monorepo, and visit waiaas.ai for the official site. If you want to go deeper on what agents can actually do once they have a session token, the policy engine and the 45 MCP tools are the logical next stops.
Top comments (0)