MCP server

zode mcp runs an MCP server on stdio. Your agent starts it as a subprocess and gets nine tools for sandboxes. It acts with your zode sign-in, in your workspace, with your plan’s limits. The server reads the same credentials as the CLI: the API key saved by zode login, or the API key in ZODE_TOKEN when set. With neither, it exits with not signed in: run zode login first, then start your agent.

Add it to your agent

Claude Code
Codex
Cursor

claude mcp add zode -- zode mcp

codex mcp add zode -- zode mcp

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "zode": {
      "command": "zode",
      "args": ["mcp"]
    }
  }
}

To use an API key instead of your sign-in, for example on a shared machine, give the server ZODE_TOKEN in its environment. In the Cursor config, add "env": { "ZODE_TOKEN": "zode_tok_..." } next to args. The server also sends the agent short instructions: work happens in /workspace, refer to sandboxes by name, fork to try two approaches, delete when done.

Agent skill

A skill teaches Claude Code, Codex, Cursor and other agents when and how to use Zode: making sandboxes, forking for parallel work, snapshots, images and secrets. It is built from these docs, so it stays current.

npx skills add https://docs.zode.dev

Tools

Every sandbox parameter takes a sandbox name or sbx_ id. Tools that return a sandbox return name, id, status, size and region.

Tool	Parameters	Does
`sandbox_list`	none	Lists the workspace’s sandboxes.
`sandbox_create`	`name`, `size`, `image`, `browser`, `desktop`, `git_repo`, `git_branch`, `pr_number` (all optional)	Makes a sandbox. See sandbox_create. Billed while running.
`sandbox_exec`	`sandbox`, `command`, `cwd`, `stdin`, `timeout_seconds`, `env`	Runs a shell command and returns its result.
`sandbox_read_file`	`sandbox`, `path`	Reads a text file, up to 256 KB.
`sandbox_write_file`	`sandbox`, `path`, `content`	Writes a text file, creating parent directories.
`sandbox_fork`	`sandbox`, `name` (optional)	Copies a sandbox: running processes, memory and disk.
`sandbox_stop`	`sandbox`	Hibernates it: memory and disk kept, compute billing stops.
`sandbox_start`	`sandbox`	Wakes a stopped sandbox where it left off.
`sandbox_delete`	`sandbox`	Deletes it and its disk. Cannot be undone.

sandbox_create

Parameter	Type	Notes
`name`	string	Lowercase letters, digits and dashes. Picked for you when empty.
`size`	string	`small`, `default`, `large` or `xlarge`. Left out, you get `small` (2 vCPU, 4 GB); the size named `default` is not the default.
`image`	string	A ready custom image of the workspace, by name or `img_` id. It sets the size, so leave `size` empty.
`browser`	boolean	Run Chrome, driven over CDP. Left out: the workspace default.
`desktop`	boolean	Run a Linux desktop. Left out: the workspace default. Not on the Free plan.
`git_repo`, `git_branch`, `pr_number`	string, string, integer	Labels for cost breakdowns. Nothing is cloned; use `sandbox_exec` for that.

sandbox_exec

Parameter	Type	Notes
`sandbox`	string	Required.
`command`	string	Required. Runs with `bash -lc` as root.
`cwd`	string	Working directory. Default `/workspace`.
`stdin`	string	Text fed to the command’s stdin. stdin is closed after it.
`timeout_seconds`	integer	Kill the command after this long. Default 600, max 3600.
`env`	object	Extra variables for this command, such as API keys.

It returns exit_code, stdout, stderr, duration_ms, and timed_out or truncated when they apply. Each stream is capped at 256 KB; past that, output is dropped and truncated is true. A timed-out command returns exit_code -1. For a long-running server, start it in the background (nohup ... &).

Paths

sandbox_read_file and sandbox_write_file take an absolute path, or a path relative to /workspace. sandbox_read_file returns the file in stdout, with the same fields as sandbox_exec.

Limits

sandbox_create has no environment or spend-cap input. For those, use zode new with --environment or --max-cost and give the agent the name.
The tools need a running sandbox for exec and files. A stopped one gives demo is stopped; start it first.
Plan limits apply as in the CLI: on Free, at most 2 sandboxes run at once, and a workspace with no card and no credit cannot make sandboxes.

Get started

Concepts

CI

CLI

TypeScript SDK

Platform

Add it to your agent

Agent skill

Tools

sandbox_create

sandbox_exec

Paths

Limits

Sign in first

Add it to your agent

Agent skill

Tools

sandbox_create

sandbox_exec

Paths

Limits