---
title: Self-Hosted Deployment
description: "Deploy Caged on your own infrastructure."
---

# Self-Hosted Deployment

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

<Info>
Self-hosted mode uses the open-source components only. Features like the dashboard, trust scoring, and billing require the managed platform at [caged.dev](https://caged.dev).
</Info>

## Requirements

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

## Quick Start with Docker Compose

```yaml 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
```

```bash
docker compose up -d
```

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

## Standalone Binary

```bash
# 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`):

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

### Cursor

In Cursor settings, add an MCP server:

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

### WebSocket (Remote)

For remote agents connecting over the network:

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

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

## Security Considerations

<Warning>
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
</Warning>

### Read-Only Mode

```bash
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

```bash
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:

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

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

## Systemd Service

```ini
# /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
```

```bash
sudo systemctl enable --now caged-mcp
```

## Upgrading

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

# Binary
brew upgrade caged-mcp-server

# Or re-download from releases
```