MCP & agent runtime

cps-mcp exposes cps as Model Context Protocol tools, so any MCP-capable agent (Claude Code, Claude Desktop, …) can create isolated Linux sandboxes, run code in them, publish ports, and tear them down — all over the public cps API.

A sandbox is the agent-facing name for an ephemeral machine at the MCP layer. It’s a Firecracker microVM with VM-level isolation, a persistent disk for the task, outbound networking, an optional HTTPS preview, and an automatic TTL — so an agent can run untrusted code and never leak resources.

cps-mcp speaks MCP over stdio and ships inside the cps CLI — installing the CLI installs cps-mcp too.

1. Install & get a token

Install the CLI (see Getting started for details):

curl -fsSL https://cps.run/install.sh | sh
cps version          # confirms both `cps` and `cps-mcp` are installed

cps login --token <your-token>
cps token create --ttl 24h --name mcp

2. Configuration

cps-mcp reads its settings from the environment, and falls back to your cps CLI config after cps login (so CPS_TOKEN is optional once you’re logged in):

Variable	Required	Default	Purpose
`CPS_TOKEN`	yes*	—	A cps token (`cpsk_…`). *Optional if `cps login` already configured the CLI.
`CPS_API_URL`	no	`https://cps.run`	Control-plane base URL (e.g. a lab endpoint).
`CPS_PROJECT_ID`	no	auto-detected	Project to create sandboxes in; inferred from the token’s org if unset.

3. Connect an MCP client

Claude Code — one command:

claude mcp add cps -e CPS_TOKEN=cpsk_your_token -- cps-mcp

Claude Desktop / generic MCP client — add to the client’s mcpServers config:

{
  "mcpServers": {
    "cps": {
      "command": "cps-mcp",
      "env": { "CPS_TOKEN": "cpsk_your_token", "CPS_API_URL": "https://cps.run" }
    }
  }
}

Verify the connection with /mcp — the cps server should show as connected with 8 tools.

4. Tools

Tool	Purpose
`create_sandbox(image?, ttl_seconds?)`	Boot an ephemeral microVM, wait until ready, return `sandbox_id`. Auto-deletes after the TTL (default 900s).
`run(sandbox_id, command[], timeout_secs?)`	Run an argv array in the sandbox; returns `exit_code`, `stdout`, `stderr`. Not shell-parsed — use `["sh", "-c", "…"]` for pipes/globs.
`write_file(sandbox_id, path, content)`	Write a text file inside the sandbox.
`read_file(sandbox_id, path)`	Read a text file from the sandbox.
`expose(sandbox_id, port)`	Publish a port over a public HTTPS URL.
`destroy(sandbox_id)`	Delete the sandbox and its routes.
`fork_sandbox(sandbox_id, ttl_seconds?)`	Clone a sandbox’s disk into a new ready sandbox (briefly stops the source for a consistent copy).
`list_sandboxes()`	List the sandboxes in the project.

Typical agent flow:

create_sandbox → sandbox_id
write_file(sandbox_id, "/root/app.py", "…")
run(sandbox_id, ["python3", "/root/app.py"])
expose(sandbox_id, 8080) → public HTTPS URL
destroy(sandbox_id) (or let the TTL reap it)

5. Claude Code plugin & skill

For Claude Code, installing the cps-agent-runtime plugin gives an agent both the cps MCP tools and the cps-agent-runtime skill, which teaches the agent to use them correctly (TTL cleanup, argv vs shell, route reclaim on destroy).

The plugin registers the cps-mcp command — the binary must already be on PATH (step 1). Install from the Git remote:

/plugin marketplace add https://git.codelab.vc/cps/cli
/plugin install cps-agent-runtime@cps

Or from a local checkout of the cli repository:

/plugin marketplace add /absolute/path/to/cli
/plugin install cps-agent-runtime@cps

Then ask naturally — e.g. “run this script in an isolated cps sandbox and show the output” — and the skill drives create_sandbox → write_file/run → destroy.

6. Updating

cps-mcp, the CLI, and the plugin update independently — there is no cps update command yet.

CLI + cps-mcp (one binary, one step) — re-run the installer, which overwrites the binary in place, then restart your MCP client so it re-spawns cps-mcp:

curl -fsSL https://cps.run/install.sh | sh
cps version          # confirm the new version

From a source checkout instead:

git pull && cargo install --path . --locked --force

Plugin + skill — refresh Claude Code’s marketplace (re-pulls the cli repo), then re-enable the plugin:

/plugin marketplace update cps
/plugin install cps-agent-runtime@cps
/reload-plugins            # apply changes without restarting the session

The plugin only registers cps-mcp — updating the plugin does not update the binary. Update the CLI (above) to get new tool behavior.

Notes (alpha)

Public expose HTTPS previews need the cps routing layer. Single-host lab deployments create the route record but do not serve traffic yet.
cps-mcp talks only to the public cps API, so it works against any reachable control plane via CPS_API_URL.
New CLI versions reach https://cps.run/install.sh only after the cps team publishes a release — re-running the installer picks up whatever is current.

Keyboard shortcuts

cps — documentation