---
title: Open Source
description: "Caged's open-source components — use them standalone or self-hosted."
---

# Open Source

Caged publishes several components as open-source under the MIT license. You can use these independently or combine them for a fully self-hosted setup.

## Repositories

<CardGroup cols={3}>
  <Card title="CLI" icon="terminal" href="https://github.com/caged-dev/cli">
    Command-line interface for managing sandboxes
  </Card>
  <Card title="Sandbox Agent" icon="cpu" href="https://github.com/caged-dev/agent">
    Lightweight agent running inside each sandbox VM
  </Card>
  <Card title="MCP Server" icon="plug" href="https://github.com/caged-dev/mcp-server">
    Model Context Protocol server for AI coding agents
  </Card>
</CardGroup>

## CLI

The `caged` CLI lets developers create, manage, and connect to sandboxes from the terminal.

```bash
brew tap caged-dev/tap
brew install caged
```

Or install from source:

```bash
go install github.com/caged-dev/cli/cmd/caged@latest
```

See the [CLI Reference](/cli/overview) for full documentation.

## Sandbox Agent

The agent runs inside each Firecracker microVM and provides:

- **Heartbeat** — reports health to the host every 5 seconds
- **Metrics collection** — CPU, memory, disk usage
- **Socket communication** — JSON message protocol over Unix socket
- **Graceful shutdown** — responds to host shutdown commands

### Install

```bash
brew tap caged-dev/tap
brew install caged-agent
```

### Docker

```bash
docker pull ghcr.io/caged-dev/agent:latest
```

### Configuration

| Flag / Env | Description | Default |
|---|---|---|
| `--workspace` / `CAGED_WORKSPACE` | Workspace root directory | `/workspace` |
| `--socket` / `CAGED_SOCKET` | Communication socket path | `/run/caged/agent.sock` |
| `--heartbeat-interval` / `CAGED_HEARTBEAT_INTERVAL` | Heartbeat interval | `5s` |
| `--metrics-interval` / `CAGED_METRICS_INTERVAL` | Metrics collection interval | `10s` |
| `--log-level` / `CAGED_LOG_LEVEL` | Log level (debug, info, warn, error) | `info` |

## MCP Server

A standalone [Model Context Protocol](https://modelcontextprotocol.io) server that exposes filesystem, terminal, and git tools to AI agents.

### Install

```bash
brew tap caged-dev/tap
brew install caged-mcp-server
```

### Docker

```bash
docker pull ghcr.io/caged-dev/mcp-server:latest
```

### Usage

```bash
# Stdio mode (for direct agent integration)
caged-mcp-server --mode stdio --workspace /path/to/project

# WebSocket mode (for remote connections)
caged-mcp-server --mode ws --port 9090 --workspace /path/to/project

# Read-only mode (restrict to read-only tools)
caged-mcp-server --mode stdio --workspace . --read-only
```

### Configuration

| Flag / Env | Description | Default |
|---|---|---|
| `--mode` / `CAGED_MCP_MODE` | Transport: `stdio` or `ws` | `stdio` |
| `--port` / `CAGED_MCP_PORT` | WebSocket listen port | `9090` |
| `--workspace` / `CAGED_MCP_WORKSPACE` | Workspace root directory | `.` |
| `--read-only` / `CAGED_MCP_READ_ONLY` | Disable write/exec tools | `false` |
| `--allowed-commands` / `CAGED_MCP_ALLOWED_COMMANDS` | Comma-separated command allowlist | (all) |
| `--log-level` / `CAGED_MCP_LOG_LEVEL` | Log level | `info` |

### Available Tools

**Filesystem:**
- `file_read` — Read file contents
- `file_write` — Write/create files
- `file_list` — List directory contents
- `file_delete` — Delete files
- `file_search` — Search files by glob pattern

**Terminal:**
- `terminal_exec` — Execute shell commands (respects allowlist)

**Git:**
- `git_status` — Show working tree status
- `git_diff` — Show file diffs
- `git_log` — Show commit history
- `git_commit` — Create a commit

## Contributing

We welcome contributions to all open-source repos. Each repo has a `CONTRIBUTING.md` with guidelines.

```bash
git clone https://github.com/caged-dev/cli.git
cd cli
go test ./...
```

See [GitHub Issues](https://github.com/caged-dev) for open tasks and feature requests.