Self-Hosted Deployment

Run the Caged MCP server and sandbox agent on your own infrastructure for full control over data and compute.

Self-hosted mode uses the open-source components only. Features like the dashboard, trust scoring, and billing require the managed platform at caged.dev.

Requirements

Linux server with KVM support (for Firecracker)
Docker (for containerized deployment)
4+ CPU cores, 8+ GB RAM recommended

Quick Start with Docker Compose

version: "3.8"

services:
  mcp-server:
    image: ghcr.io/caged-dev/mcp-server:latest
    ports:
      - "9090:9090"
    volumes:
      - ./workspace:/workspace
    environment:
      - CAGED_MCP_MODE=ws
      - CAGED_MCP_PORT=9090
      - CAGED_MCP_WORKSPACE=/workspace
      - CAGED_MCP_READ_ONLY=false
    restart: unless-stopped

docker compose up -d

The MCP server is now available at ws://localhost:9090.

Standalone Binary

# Download from GitHub Releases
curl -fsSL https://github.com/caged-dev/mcp-server/releases/latest/download/caged-mcp-server_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz | tar xz

# Run
./caged-mcp-server --mode ws --port 9090 --workspace /path/to/project

Connecting AI Agents

Claude Code

Add to your MCP config (~/.config/claude/mcp.json):

{
  "servers": {
    "caged": {
      "command": "caged-mcp-server",
      "args": ["--mode", "stdio", "--workspace", "/path/to/project"]
    }
  }
}

Cursor

In Cursor settings, add an MCP server:

{
  "name": "caged",
  "command": "caged-mcp-server",
  "args": ["--mode", "stdio", "--workspace", "."]
}

WebSocket (Remote)

For remote agents connecting over the network:

# Server
caged-mcp-server --mode ws --port 9090 --workspace /workspace

# Agent connects to ws://your-server:9090

Security Considerations

The MCP server executes commands on the host. In production, always use:

--read-only to disable write operations when not needed
--allowed-commands to restrict which commands can be executed
Network isolation (firewall rules, VPN)
Run in a container or VM for defense-in-depth

Read-Only Mode

caged-mcp-server --mode ws --workspace /project --read-only

Only exposes: file_read, file_list, file_search, git_status, git_diff, git_log.

Command Allowlist

caged-mcp-server --mode ws --workspace /project \
  --allowed-commands "npm,node,python,git,make"

Only listed commands can be executed via terminal_exec.

Running the Agent

The agent is designed to run inside sandbox VMs but can also be used standalone for metrics collection:

caged-agent --workspace /workspace --socket /tmp/agent.sock

It will report CPU, memory, and disk metrics over the Unix socket.

Systemd Service

# /etc/systemd/system/caged-mcp.service
[Unit]
Description=Caged MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/caged-mcp-server --mode ws --port 9090 --workspace /workspace
Restart=always
RestartSec=5
User=caged
Group=caged

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now caged-mcp

Upgrading

# Docker
docker compose pull && docker compose up -d

# Binary
brew upgrade caged-mcp-server

# Or re-download from releases