CLI Ownership Management: master, owner, and session Commands for Self-Hosted Wallets

WAIaaS has introduced a three-tier ownership model for self-hosted AI agent wallets, comprising master, owner, and session layers. The CLI tool enables developers to manage wallet infrastructure on their own hardware, ensuring autonomous agent operation without unrestricted signing authority. This approach provides sovereignty and security by avoiding third-party custody of private keys.

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. 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. 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. 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. 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 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 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. 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 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. 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. 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. npm install -g @waiaas/cli waiaas init --auto-provision && waiaas start 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 DesktopThe 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 https://github.com/minhoyoo-iotrust/WAIaaS to read the full documentation and see the 15-package monorepo, and visit waiaas.ai https://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.