Skip to main content

​
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

CLI

Command-line interface for managing sandboxes

Sandbox Agent

Lightweight agent running inside each sandbox VM

MCP Server

Model Context Protocol server for AI coding agents

​
CLI

The caged CLI lets developers create, manage, and connect to sandboxes from the terminal. 
brew tap caged-dev/tap
brew install caged
Or install from source: 
go install github.com/caged-dev/cli/cmd/caged@latest
See the CLI Reference 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

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

​
Docker

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

​
Configuration

Flag / EnvDescriptionDefault
--workspace / CAGED_WORKSPACEWorkspace root directory/workspace
--socket / CAGED_SOCKETCommunication socket path/run/caged/agent.sock
--heartbeat-interval / CAGED_HEARTBEAT_INTERVALHeartbeat interval5s
--metrics-interval / CAGED_METRICS_INTERVALMetrics collection interval10s
--log-level / CAGED_LOG_LEVELLog level (debug, info, warn, error)info

​
MCP Server

A standalone Model Context Protocol server that exposes filesystem, terminal, and git tools to AI agents.

​
Install

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

​
Docker

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

​
Usage

# 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 / EnvDescriptionDefault
--mode / CAGED_MCP_MODETransport: stdio or wsstdio
--port / CAGED_MCP_PORTWebSocket listen port9090
--workspace / CAGED_MCP_WORKSPACEWorkspace root directory.
--read-only / CAGED_MCP_READ_ONLYDisable write/exec toolsfalse
--allowed-commands / CAGED_MCP_ALLOWED_COMMANDSComma-separated command allowlist(all)
--log-level / CAGED_MCP_LOG_LEVELLog levelinfo

​
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. 
git clone https://github.com/caged-dev/cli.git
cd cli
go test ./...
See GitHub Issues for open tasks and feature requests.