lobstercage-cli

Command-line interface for LobsterCage -- Secure AI Agent Sandboxes.

Installation

npm install -g lobstercage-cli

Requires Node.js >= 20.0.0.

Quick Start

# Authenticate via browser
lobster login

# Deploy a new cage
lobster deploy my-cage

# Open an interactive SSH shell
lobster ssh my-cage

# Run a command inside a cage
lobster exec my-cage --local -- ls -la /workspace

# Tunnel a port to localhost
lobster tunnel my-cage --port 3000

# Stream lifecycle events
lobster tail my-cage

# Set up SSH config for `ssh [email protected]`
lobster ssh-config

Global Flags

| Flag | Description | | --- | --- | | --api-url <url> | Override the API URL (default: https://api.lobstercage.ai) | | --debug | Show detailed error information and stack traces | | --version | Print CLI version | | --help | Show help for any command |

Commands

Authentication

| Command | Description | | --- | --- | | lobster login | Login to LobsterCage via browser | | lobster logout | Logout from LobsterCage | | lobster whoami | Display current user information |

Cage Lifecycle

| Command | Description | | --- | --- | | lobster deploy <name> | Create and start a new cage | | lobster list | List all cages | | lobster status <name> | Get cage status and details | | lobster start <name> | Start a stopped cage | | lobster stop <name> | Stop a running cage | | lobster hibernate <name> | Hibernate a cage (preserves state and storage) | | lobster wake <name> | Wake a hibernated cage | | lobster destroy <name> | Permanently delete a cage | | lobster logs <name> | View cage logs (requires --local) | | lobster tail <name> | Stream cage events in real-time |

Connectivity

| Command | Description | | --- | --- | | lobster ssh <name> | SSH into a running cage (extra args passed to ssh) | | lobster tunnel <name> | Create a secure tunnel to a cage port | | lobster dashboard <name> | Open the OpenClaw dashboard for a running cage | | lobster port-forward <name> | Forward a port from a cage via HTTPS proxy URL | | lobster exec <name> [cmd...] | Execute a command in a cage (requires --local) | | lobster proxy <name> | SSH ProxyCommand handler (used by SSH config, not invoked directly) | | lobster ssh-config | Install SSH config for *.lobster hosts |

Environment Variables

| Command | Description | | --- | --- | | lobster env list <cage> | List environment variables | | lobster env set <cage> KEY=VAL... | Set environment variables | | lobster env get <cage> <key> | Get an environment variable value | | lobster env delete <cage> <key...> | Delete environment variables | | lobster env scan <cage> | Scan for security issues in environment variables |

API Keys

| Command | Description | | --- | --- | | lobster apikeys list | List all API keys | | lobster apikeys create <name> | Create a new API key | | lobster apikeys revoke <keyId> | Revoke an API key |

Billing

| Command | Description | | --- | --- | | lobster billing | View billing status and credit usage | | lobster billing portal | Open Stripe billing portal | | lobster upgrade | Upgrade to Starter plan |

Command Details

deploy

lobster deploy my-cage                         # Default size, Ubuntu 22.04
lobster deploy my-cage --size standard         # Standard tier (more CPU/RAM)
lobster deploy my-cage --image ubuntu:22.04    # Custom image
lobster deploy my-cage --egress deny-all       # No outbound network
lobster deploy my-cage --egress allowlist --allow-host api.openai.com
lobster deploy my-cage --no-start              # Create without starting
lobster deploy my-cage --local                 # Local Docker cage
lobster deploy my-cage --local --template ai-agent

Size tiers: starter, standard, power, extreme.

ssh

lobster ssh my-cage                            # Interactive SSH session
lobster ssh my-cage -L 8080:localhost:8080     # SSH with local port forward
lobster ssh my-cage -- cat /etc/hostname       # Run remote command

Uses lobster proxy as the SSH ProxyCommand internally. Cages use empty-password auth (the tunnel proxy is the real auth boundary).

ssh-config

lobster ssh-config            # Install config block in ~/.ssh/config
lobster ssh-config --print    # Print config without installing
lobster ssh-config --remove   # Remove LobsterCage config block

After installation, you can use standard SSH tooling:

ssh [email protected]
scp file.txt [email protected]:/workspace/
sftp [email protected]
# Also works with VS Code Remote SSH

tunnel

lobster tunnel my-cage --port 3000              # localhost:3000 -> cage:3000
lobster tunnel my-cage --port 8080 --local-port 9090  # localhost:9090 -> cage:8080
lobster tunnel my-cage --ssh                    # Shorthand for --port 22

port-forward

lobster port-forward my-cage --port 3000        # Get HTTPS proxy URL
lobster port-forward my-cage --port 3000 --local-port 3000  # Start local HTTP proxy

Alias: lobster pf.

tail

lobster tail my-cage                # Stream events (Ctrl+C to stop)
lobster tail my-cage -n 50          # Show last 50 events first
lobster tail my-cage --no-follow    # Print history and exit
lobster tail my-cage --json         # NDJSON output
lobster tail my-cage -v             # Show event metadata

exec

lobster exec my-cage --local                    # Interactive shell (local Docker)
lobster exec my-cage --local -- ls -la          # Run a command
lobster exec my-cage --local --shell sh         # Force /bin/sh

Note: Remote exec is not available via the API. Use lobster ssh for remote access.

apikeys

lobster apikeys list                            # List all keys
lobster apikeys create "My Key"                 # Create a key
lobster apikeys create "CI Key" --scope cages   # Scoped key
lobster apikeys create "Temp" --expires 2026-04-01
lobster apikeys revoke lc_live_abc123           # Revoke (with confirmation)
lobster apikeys revoke lc_live_abc123 --force   # Revoke without confirmation

Common flags

Most commands support --json for machine-readable JSON output and --local for local Docker mode (where applicable).

Documentation

See the Quickstart Guide for the full walkthrough.

License

BUSL-1.1