Sandbox tools
Create and manage sandboxes, local or in the cloud.
Create and manage sandboxes, local or in the cloud.
| Tool | Description |
|---|---|
sandbox_list | List sandboxes: local, direct and cloud (Fleet) ones by default, each row with location (local, cloud or direct). |
sandbox_create | Create a sandbox from any image. |
sandbox_get | Get details for a sandbox. |
sandbox_start | Start (resume) a sandbox. |
sandbox_stop | Stop (suspend) a sandbox. |
sandbox_restart | Restart a sandbox. |
sandbox_suspend | Suspend a sandbox. |
sandbox_delete | Delete a sandbox. |
sandbox_view | Get a browser link to the sandbox desktop in the cua-spacesd HTML5 viewer (video, audio, input, clipboard, files). |
sandbox_vnc | Deprecated: use sandbox_view. |
sandbox_open_browser | Launch Chromium with a fresh throwaway profile inside an existing sandbox (an image with cua-spacesd and Chromium, see images_list), bind it and optionally open a URL. |
Served by cua mcp; see MCP tools for every tool.
sandbox_list#List sandboxes: local, direct and cloud (Fleet) ones by default, each row with location (local, cloud or direct). Pass location to list only one kind. If the cloud cannot be listed, the local rows come back with a warning.
Permission: sandbox:list.
| Parameter | Type | Default | Description |
|---|---|---|---|
location | "local" | "cloud" | "direct" | Only sandboxes in this location: local, cloud or direct (default: all). |
sandbox_create#Create a sandbox from any image. on says where (local, the default unless the user configured another with cua config set default.on; or cloud), kind what (auto, container, vm) and runtime which engine (auto, or gvisor, runc, qemu, lume locally; gvisor, kubevirt in the cloud); an impossible combination fails and lists the valid values. To browse the web, pass browser=true (and optionally url): it starts the canonical Linux image, registers it as a Space, launches Chromium with a throwaway profile inside it and returns the space, session, target_id and tab_id to pass to call_tool with the in-sandbox browser tools (browser_navigate, get_browser_state, browser_click, browser_type). Pass command, env and services to run a server in it, for example an MCP server: services {"mcp": 8765}. Without browser=true it does not register a Space: to reach its MCP server with list_tools/call_tool (service="mcp"), use create_space instead (same arguments), or add this one with add_space (address local:<name>).
Permission: sandbox:create.
| Parameter | Type | Default | Description |
|---|---|---|---|
browser | boolean | Start a browser in it, ready for the cua-driver browser tools (default image: the canonical Linux image). | |
command | string[] | Entrypoint override (argv), for example ["python", "-m", "my_mcp"]. | |
env | object | Environment variables (string values). | |
image | string | Image reference, any registry (overrides os_type). | |
kind | "auto" | "container" | "vm" | What kind of machine: auto (default; from the image), container or vm. | |
name | string | Sandbox name. | |
on | string | Where it runs: local or cloud (default: the user's default location, else local). | |
os_type | string | linux (default) or macos. | |
pool | string | Use this dedicated cloud pool (Fleets advanced; implies on=cloud). | |
runtime | string | Which engine: auto (default) or one the location offers for the kind (local: gvisor, runc, qemu, lume; cloud: gvisor, kubevirt). | |
services | object | Named services: name to guest port, for example {"mcp": 8765}; each is probed for readiness. | |
url | string | With browser=true: open this URL first. |
sandbox_get#Get details for a sandbox.
Permission: sandbox:get.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_start#Start (resume) a sandbox.
Permission: sandbox:start.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_stop#Stop (suspend) a sandbox.
Permission: sandbox:stop.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_restart#Restart a sandbox.
Permission: sandbox:restart.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_suspend#Suspend a sandbox.
Permission: sandbox:suspend.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_delete#Delete a sandbox.
Permission: sandbox:delete.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_view#Get a browser link to the sandbox desktop in the cua-spacesd HTML5 viewer (video, audio, input, clipboard, files). The link expires after an hour.
Permission: sandbox:view.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_vnc#Deprecated: use sandbox_view. Returns the same viewer link.
Permission: sandbox:view.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
Example arguments
{"name":"<name>"}sandbox_open_browser#Launch Chromium with a fresh throwaway profile inside an existing sandbox (an image with cua-spacesd and Chromium, see images_list), bind it and optionally open a URL. Returns the space, session, target_id and tab_id for call_tool with the in-sandbox browser tools. sandbox_create with browser=true already does this.
Permission: sandbox:browser.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Sandbox ref (local:<name>, cloud:<name>, direct:<host:port>) or a name unique across locations. |
session | string | cua-driver session label to use on every later browser call (default: browse). | |
url | string | Open this URL first. |
Example arguments
{"name":"<name>"}