svamp-cli

AI workspace daemon and CLI for Hypha Cloud. Run AI agents locally with cloud sync, manage sessions, share with teammates, and orchestrate tasks.

Svamp (Swedish for "mushroom") is the interactive layer of Hypha Cloud — where teams and AI agents collaborate in real time.

Installation

npm install -g svamp-cli

Requires Node.js >= 22 (for native WebSocket support).

Quick Start

# Login to Hypha Cloud
svamp login

# Start interactive Claude session (synced to web app)
svamp

# Or start the daemon for background sessions
svamp daemon start

# Spawn a session
svamp session spawn claude -d ~/my-project

# Send a message
svamp session send <session-id> "Fix the failing tests"

Configuration

Credentials are stored in ~/.svamp/.env:

HYPHA_SERVER_URL=https://hypha.aicell.io
HYPHA_TOKEN=<your-token>
HYPHA_WORKSPACE=<your-workspace>

Commands

Interactive Mode

svamp                              # Start Claude in terminal with cloud sync
svamp start [-d <path>]            # Same, with explicit directory

When you run svamp with no arguments, Claude starts in your terminal with full interactive access. Your session is synced to Hypha Cloud and visible in the web app. When a message arrives from the web app, svamp switches to remote mode automatically. Press Space-Space to return to local mode.

Login

svamp login [server-url]           # Login via browser OAuth

Daemon Management

svamp daemon start                 # Start daemon (detached)
svamp daemon stop                  # Stop (sessions preserved for auto-restore)
svamp daemon stop --cleanup        # Stop and mark all sessions as stopped
svamp daemon restart               # Restart seamlessly
svamp daemon status                # Show daemon status
svamp daemon install               # Install as system service (launchd/systemd)
svamp daemon uninstall             # Remove system service

Session Management

All session commands support --machine <id> / -m <id> to target a specific machine.

svamp session list [--active] [--json]
svamp session machines                         # List discoverable machines
svamp session spawn <agent> [-d <path>] [--message <msg>] [--wait]
svamp session stop <id>
svamp session info <id> [--json]
svamp session send <id> <message> [--wait] [--timeout N]
svamp session wait <id> [--timeout N]
svamp session messages <id> [--last N] [--json]
svamp session attach <id>                      # Interactive terminal attach
svamp session approve <id>                     # Approve pending permission
svamp session deny <id>                        # Deny pending permission

Session Sharing

svamp session share <id> --list
svamp session share <id> --add <email>[:<role>]    # Roles: view, interact, admin
svamp session share <id> --remove <email>

Isolation & Security Flags (on spawn)

svamp session spawn claude -d <path> --isolate
svamp session spawn claude -d <path> --share [email protected]:admin
svamp session spawn claude -d <path> --security-context ./context.json
svamp session spawn claude -d <path> --deny-network
svamp session spawn claude -d <path> --deny-read /etc --allow-write /tmp/work
svamp session spawn claude -d <path> --allow-domain api.anthropic.com

Ralph Loop (Iterative Task Automation)

svamp session ralph-start <id> "<task>" [--promise DONE] [--max 10] [--cooldown 1]
svamp session ralph-cancel <id>
svamp session ralph-status <id>

The Ralph Loop enables agents to iterate on tasks with verifiable completion. Each iteration the agent works toward a goal and signals completion via <promise>DONE</promise>.

Machine Management

svamp machine share --list
svamp machine share --add <email>[:<role>]
svamp machine share --remove <email>
svamp machine share --config <path>            # Apply security context config
svamp machine share --show-config

Skills Marketplace

svamp skills find <query> [--json]             # Search marketplace
svamp skills install <name> [--force]          # Install to ~/.claude/skills/<name>/
svamp skills list                              # List installed skills
svamp skills remove <name>                     # Remove skill
svamp skills publish <path>                    # Publish to marketplace

Service Exposure (Cloud HTTP Services)

Expose HTTP services from cloud sandboxes or local machines to stable external URLs.

svamp service expose <name> --port <port>      # Create + join (auto-detect cloud/tunnel)
svamp service create <name> --port <port>
svamp service list [--json]
svamp service info <name> [--json]
svamp service delete <name>
svamp service tunnel <name> --port <port>      # Tunnel local ports

Local Agent Sessions

svamp agent list                               # List known agents (ACP + MCP)
svamp agent <name>                             # Start local agent session (gemini, codex)
svamp agent -- <cmd> [args]                    # Start custom ACP agent

Agent Backends

| Agent | Protocol | Transport | |-------|----------|-----------| | Claude | Native | CLI subprocess | | Codex | MCP | STDIO (codex mcp-server) | | Gemini | ACP | STDIO (gemini --experimental-acp) |

Security & Isolation

Sessions can be isolated using OS-level sandboxes:

| Method | Platform | Description | |--------|----------|-------------| | nono | macOS/Linux | Kernel-enforced capability sandbox (preferred) | | Docker | Any | Container-based isolation | | Podman | Any | Rootless container fallback |

Security contexts define per-user filesystem and network rules. See --security-context flag.

Development

yarn install
yarn workspace svamp-cli build
yarn workspace svamp-cli test          # Run unit tests (235+ tests)
yarn workspace svamp-cli test:e2e      # Run E2E session tests
yarn workspace svamp-cli test:hypha    # Run Hypha service integration tests

License

See LICENSE in the repository root.