DEV Community

Cover image for CLI Session Management: prompt, set-master, and owner Commands for Self-Hosted Wallets
Wallet Guy
Wallet Guy

Posted on

CLI Session Management: prompt, set-master, and owner Commands for Self-Hosted Wallets

#selfhosted #opensource #ai #web3

Managing CLI sessions for self-hosted wallet infrastructure requires careful balance between security and usability. When running your own WAIaaS instance, you control the entire authentication flow — from master password setup to owner verification — without relying on third-party services that could compromise your agent's private keys.

Why Self-Hosted Session Management Matters

The choice between hosted and self-hosted wallet services isn't just about convenience — it's about sovereignty. With self-hosted WAIaaS, your AI agents' private keys never leave your infrastructure. You set the security policies, control the authentication flow, and maintain complete audit trails of every transaction. This becomes critical when your agents manage significant funds or operate in regulated environments where data residency matters.

Traditional hosted wallet services create a fundamental trust problem: you're asking a third party to secure your agents' spending power. Self-hosting eliminates this dependency while giving you granular control over session lifecycles, authentication methods, and security policies.

CLI Session Commands Overview

WAIaaS provides three core CLI commands for session management:

  • waiaas session prompt — Interactive session creation with automatic MCP integration
  • waiaas set-master — Secure master password management for production deployment
  • waiaas owner connect/disconnect/status — Owner authentication for high-value transaction approval

Interactive Session Creation

The session prompt command provides the fastest path from wallet to working AI agent:

waiaas session prompt
Enter fullscreen mode Exit fullscreen mode

This interactive command walks you through wallet selection, policy configuration, and MCP integration. Behind the scenes, it:

  1. Lists all available wallets in your instance
  2. Creates a new session with configurable TTL and renewal limits
  3. Generates the MCP configuration block for Claude Desktop
  4. Optionally applies basic security policies

The generated session token uses JWT HS256 signing with your instance's secret, ensuring tokens can't be forged or used against other WAIaaS instances. Session tokens include wallet binding, expiration, and renewal tracking.

For automation, you can create sessions programmatically:

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>"}'
Enter fullscreen mode Exit fullscreen mode

Production Master Password Setup

The set-master command addresses a common self-hosting challenge: transitioning from development to production security. When you first run waiaas init --auto-provision, it generates a random master password stored in recovery.key. This gets you started quickly but isn't suitable for production.

# Initial setup with auto-generated password
waiaas init --auto-provision
waiaas start                    # Uses password from recovery.key
waiaas quickset                 # Creates wallets + sessions

# Later: harden for production
waiaas set-master
# Enter new secure master password
rm ~/.waiaas/recovery.key      # Remove auto-generated file
Enter fullscreen mode Exit fullscreen mode

The master password protects the most sensitive operations:

  • Wallet creation and private key access
  • Session creation and revocation
  • Policy configuration
  • System-level configuration changes

WAIaaS uses Argon2id for master password hashing, providing resistance against both CPU and GPU-based attacks. The derived key encrypts wallet private keys using AES-256-GCM.

Owner Authentication Flow

Owner commands handle the human-in-the-loop approval system for high-value transactions. This implements a separation of concerns: AI agents can initiate transactions via session auth, but humans retain veto power through owner auth.

Check current owner connection status:

waiaas owner status
Enter fullscreen mode Exit fullscreen mode

Connect an owner wallet for transaction approval:

waiaas owner connect
# Prompts for private key or hardware wallet connection
# Generates SIWS/SIWE signatures for authentication
Enter fullscreen mode Exit fullscreen mode

Once connected, owners can approve pending transactions through multiple channels:

  • WalletConnect integration for hardware wallet approval
  • Telegram bot notifications with approval buttons
  • Push notification service for mobile approval

The owner authentication uses message signing (SIWS for Solana, SIWE for Ethereum) rather than direct private key exposure. This allows hardware wallets and multisig setups to participate in the approval flow.

Security Policy Integration

CLI session management integrates directly with WAIaaS's 21 policy types. When creating sessions, you can enforce spending limits that trigger owner approval:

curl -X POST http://localhost:3100/v1/policies \
  -H 'Content-Type: application/json' \
  -H 'X-Master-Password: <password>' \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 10,
      "notify_max_usd": 100,
      "delay_max_usd": 1000,
      "delay_seconds": 300,
      "daily_limit_usd": 500
    }
  }'
Enter fullscreen mode Exit fullscreen mode

This creates a 4-tier security system:

  • INSTANT (≤$10): Executes immediately
  • NOTIFY ($10-$100): Executes with notification
  • DELAY ($100-$1000): 5-minute delay, cancellable
  • APPROVAL (>$1000): Requires owner approval

The owner disconnect command provides an emergency kill switch:

waiaas owner disconnect
# Immediately revokes approval capability
# Pending APPROVAL transactions become stuck until owner reconnects
Enter fullscreen mode Exit fullscreen mode

Docker Integration for Production

Self-hosted WAIaaS deployments typically run in Docker for consistency across environments. The CLI commands work seamlessly with containerized deployments:

# Start with Docker Compose
docker compose up -d

# Access CLI through container
docker exec waiaas-daemon waiaas session prompt
docker exec waiaas-daemon waiaas owner status
Enter fullscreen mode Exit fullscreen mode

For production deployments, use Docker Secrets for master password management:

services:
  daemon:
    image: ghcr.io/minhoyoo-iotrust/waiaas:latest
    secrets:
      - master_password
    environment:
      - WAIAAS_MASTER_PASSWORD_FILE=/run/secrets/master_password
Enter fullscreen mode Exit fullscreen mode

This avoids exposing the master password in environment variables or command history.

Session Lifecycle Management

WAIaaS sessions support configurable lifecycles to balance security and usability:

  • TTL: Session expires after fixed duration (default: unlimited)
  • Max Renewals: Limit how many times a session can extend (default: unlimited)
  • Absolute Lifetime: Hard expiration regardless of activity (default: unlimited)

For production agents, consider bounded sessions:

{
  "walletId": "<uuid>",
  "ttlSeconds": 3600,
  "maxRenewals": 24,
  "absoluteLifetimeSeconds": 86400
}
Enter fullscreen mode Exit fullscreen mode

This creates 1-hour sessions that can renew 24 times, with a hard 24-hour limit. Agents must reauthenticate daily, limiting blast radius from compromised tokens.

Quick Start: Secure Self-Hosted Setup

Here's the complete flow for production-ready WAIaaS deployment:

  1. Deploy with Docker Compose: 
git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d
Enter fullscreen mode Exit fullscreen mode
  1. Initial setup with auto-provision: 
docker exec waiaas-daemon waiaas init --auto-provision
docker exec waiaas-daemon waiaas quickset
Enter fullscreen mode Exit fullscreen mode
  1. Harden master password: 
docker exec -it waiaas-daemon waiaas set-master
docker exec waiaas-daemon rm /data/recovery.key
Enter fullscreen mode Exit fullscreen mode
  1. Connect owner for approvals: 
docker exec -it waiaas-daemon waiaas owner connect
Enter fullscreen mode Exit fullscreen mode
  1. Create session for your AI agent: 
docker exec -it waiaas-daemon waiaas session prompt
Enter fullscreen mode Exit fullscreen mode

The session prompt will output MCP configuration for Claude Desktop, giving your AI agent immediate access to wallet functionality with the security policies you've defined.

What's Next

Self-hosted WAIaaS gives you complete control over your AI agents' financial capabilities while maintaining security through owner approval flows and configurable policies. Your keys stay on your infrastructure, your policies enforce your risk tolerance, and your agents operate with the autonomy you define.

Ready to deploy your own instance? Visit the GitHub repository for complete setup instructions, or explore the full documentation at waiaas.ai to dive deeper into policy configuration and advanced features.

Top comments (0)