{"slug": "cli-ownership-management-master-owner-and-session-commands-for-self-hosted", "title": "CLI Ownership Management: master, owner, and session Commands for Self-Hosted Wallets", "summary": "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.", "body_md": "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.\n\nRunning 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.\n\nHosted 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.\n\nThe 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.\n\nBefore looking at CLI commands, it helps to understand what each tier is for.\n\n**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.\n\n**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.\n\n**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.\n\nThis 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.\n\nThe CLI is the primary tool for managing a self-hosted WAIaaS installation:\n\n```\nnpm install -g @waiaas/cli\n```\n\nOnce installed, you have access to 20 commands covering everything from daemon lifecycle to backup and restore.\n\n`init`\n\n, `start`\n\n, and `set-master`\n\nThe fastest path from zero to running daemon:\n\n```\nwaiaas init                  # Create data directory + config.toml\nwaiaas start                 # Start daemon (prompts for master password on first run)\n```\n\nIf 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:\n\n```\nwaiaas init --auto-provision   # Generates a random master password → saved to recovery.key\nwaiaas start                   # No password prompt\n```\n\nAfter auto-provision, retrieve your generated master password from `recovery.key`\n\n, store it somewhere safe, and then harden it:\n\n```\nwaiaas set-master              # Change the master password to something you chose\n# After confirming the new password works:\n# Delete recovery.key — it's no longer needed\n```\n\nThe `set-master`\n\ncommand 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.\n\n`owner connect`\n\n, `owner disconnect`\n\n, `owner status`\n\nThe 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.\n\n```\nwaiaas owner connect     # Link your wallet address as the fund owner\nwaiaas owner status      # Check which address is connected as owner\nwaiaas owner disconnect  # Remove the owner connection\n```\n\nOnce 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.\n\nThe 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.\n\n`session prompt`\n\nand the Session API\nSessions 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.\n\nThe `session prompt`\n\ncommand is the CLI interface for managing session interactions:\n\n```\nwaiaas session prompt\n```\n\nFor creating sessions programmatically (which is the common case when you're wiring up an agent), use the REST API:\n\n```\n# First, create a wallet (masterAuth required)\ncurl -X POST http://127.0.0.1:3100/v1/wallets \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Master-Password: my-secret-password\" \\\n  -d '{\"name\": \"trading-wallet\", \"chain\": \"solana\", \"environment\": \"mainnet\"}'\n\n# Then create a session for the agent (masterAuth required)\ncurl -X POST http://127.0.0.1:3100/v1/sessions \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Master-Password: my-secret-password\" \\\n  -d '{\"walletId\": \"<wallet-uuid>\"}'\n```\n\nThe 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:\n\n```\n# What the agent does with its session token:\ncurl http://127.0.0.1:3100/v1/wallet/balance \\\n  -H \"Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9...\"\n```\n\nIf 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.\n\nFor people who want to get from install to \"Claude has a wallet\" as fast as possible, `quickset`\n\ncreates wallets and MCP sessions in one command:\n\n```\nwaiaas quickset --mode mainnet\n```\n\nThis 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:\n\n```\nwaiaas mcp setup --all   # Auto-register all wallets with Claude Desktop\n```\n\nAfter 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.\n\n`backup create`\n\n, `backup list`\n\n, `backup inspect`\n\n, `restore`\n\nSelf-hosting means you're responsible for your own backups. The CLI has this covered:\n\n```\nwaiaas backup create      # Create a backup of the current daemon state\nwaiaas backup list        # List all available backups\nwaiaas backup inspect     # Inspect the contents of a specific backup\nwaiaas restore            # Restore from a backup\n```\n\nThis 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.\n\nFor 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.\n\nMost 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`\n\nand the default port binding is `127.0.0.1:3100:3100`\n\n— localhost only by default, which is the right default.\n\n```\n# Clone and start in three commands\ngit clone https://github.com/minhoyoo-iotrust/WAIaaS.git\ncd WAIaaS\ndocker compose up -d\n```\n\nFor unattended first boot with auto-provision:\n\n```\ndocker run -d \\\n  --name waiaas \\\n  -p 127.0.0.1:3100:3100 \\\n  -v waiaas-data:/data \\\n  -e WAIAAS_AUTO_PROVISION=true \\\n  ghcr.io/minhoyoo-iotrust/waiaas:latest\n\n# Get the auto-generated master password\ndocker exec waiaas cat /data/recovery.key\n```\n\nFor production deployments, use the secrets overlay to avoid putting passwords in environment variables:\n\n```\nmkdir -p secrets\necho \"your-secure-password\" > secrets/master_password.txt\nchmod 600 secrets/master_password.txt\n\ndocker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d\n```\n\nThe 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.\n\nHere's the mental model that ties all three tiers together for a self-hosted deployment:\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**Your server** runs the daemon. The keys never leave your infrastructure.\n\nThis 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.\n\n`npm install -g @waiaas/cli`\n\n`waiaas init --auto-provision && waiaas start`\n\n`cat ~/.waiaas/recovery.key`\n\n`waiaas quickset --mode mainnet`\n\n— creates wallets and sessions`waiaas owner connect`\n\n— link your personal wallet as fund owner`waiaas set-master`\n\n— harden the master password, delete recovery.key`waiaas mcp setup --all`\n\n— 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.", "url": "https://wpnews.pro/news/cli-ownership-management-master-owner-and-session-commands-for-self-hosted", "canonical_source": "https://dev.to/walletguy/cli-ownership-management-master-owner-and-session-commands-for-self-hosted-wallets-20l4", "published_at": "2026-07-14 15:01:22+00:00", "updated_at": "2026-07-14 15:30:25.502592+00:00", "lang": "en", "topics": ["ai-agents", "ai-infrastructure", "developer-tools"], "entities": ["WAIaaS", "Solana", "Ethereum"], "alternates": {"html": "https://wpnews.pro/news/cli-ownership-management-master-owner-and-session-commands-for-self-hosted", "markdown": "https://wpnews.pro/news/cli-ownership-management-master-owner-and-session-commands-for-self-hosted.md", "text": "https://wpnews.pro/news/cli-ownership-management-master-owner-and-session-commands-for-self-hosted.txt", "jsonld": "https://wpnews.pro/news/cli-ownership-management-master-owner-and-session-commands-for-self-hosted.jsonld"}}