Skip to main content

​
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

docker-compose.yml
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