Runtime Cloud

runtime_sandboxes_create

Idempotent

Create a Linux sandbox (Ubuntu with python3, node, bun, git, gcc and sudo). The free usage is spent first, then prepaid credit, with nothing to choose. Defaults: 2 vCPU / 4096 MiB / 4096 MiB disk, no time limit: it runs while it works and pauses after 300 idle seconds. Waits up to 60 seconds and returns its state; run commands once it is running. Without credit: 4 running sandboxes at once (a paused one holds no slot), each up to 2 vCPU / 4 GiB, 8 vCPU / 16 GiB in all, at most 5 sandboxes kept and 50 made a day; once the account holds credit, its sandboxes have paid limits and still spend the free usage first.

Input Schema

Name	Required	Description	Default
`cpu`	No		shared
`env`	No	Environment variables for every command, terminal and SSH session in it (up to 32). Values are never shown again.
`name`	No	Your handle for it.
`user`	No	root: its commands and terminals run as root unless one names user sandbox. Default sandbox.
`vcpu`	No	At most 16 (2 without credit).
`wait`	No
`image`	No	Start from this ready image: id, name, name:tag or name@version. Waits for its ready check.
`labels`	No	Up to 32 key: value tags to filter by.
`region`	No
`diskMiB`	No	At least 3072; at most 409600, 400 GiB (10240 without credit).
`funding`	No	Accepted and ignored: free usage first, then credit.
`network`	No	Rules from the first start: {internet, allow?, deny?, connect?}, as runtime_sandboxes_network_set.
`secrets`	No	The egress secrets it may use, by name (at most 64): only these of the secrets that reach it; [] none; omit for all. Fixed for its life.
`volumes`	No	Up to 4 volumes: [{volumeId, path, mode?: rw or snapshot}].
`autoWake`	No	A request to a paused sandbox wakes it.
`pausable`	No	Ignored since 5 October 2026: every sandbox can pause.
`snapshot`	No	Start as a copy of a ready snapshot, on the snapshot's host; not with image. A memory snapshot's copy is its size; a disk snapshot's is the size asked, its disk at least the saved one.
`memoryMiB`	No	At most 65536, 64 GiB (4096 without credit).
`onTimeout`	No		pause
`tailscale`	No	Paid: join your tailnet once running: {authKeySecret (a job secret's name), hostname?, tags?}.
`onLeaseEnd`	No	onTimeout's older name.
`persistent`	No	Paid: never pause it for idleness or a time limit.
`getOrCreate`	No	With name: return the sandbox holding that name (woken if paused) instead of name_taken.
`wakeOnTimers`	No	A process's timer (a sleep, a timeout) wakes it from an idle pause.
`maxCostMicros`	No	Deprecated, still accepted: use maxTotalCostMicros.
`cpuFloorMillis`	No	Guaranteed CPU, thousandths of a vCPU.
`idempotencyKey`	No	Optional: left out, one is made and returned as idempotencyKey. Send it back only to retry this exact call after a temporary error.
`timeoutSeconds`	No	A time limit, 60 to 86400 s (24 h); 0, the default, is none: it runs while it works.
`idlePauseSeconds`	No	Pause after this many idle seconds (no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes). Default 300; 0 never; otherwise 60 to 86400, a shorter time raised to 60.
`maxTotalCostMicros`	No	The most it may cost over its whole life.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 31, 2026

addedInput schema / properties / wakeOnTimers

Added value: +{
+  "default": true,
+  "description": "A process's timer (a sleep, a timeout) wakes it from an idle pause.",
+  "type": "boolean"
+}

Changed1 schema field changedOct 25, 2026

addedInput schema / properties / user

Added value: +{
+  "description": "root: its commands and terminals run as root unless one names user sandbox. Default sandbox.",
+  "enum": [
+    "sandbox",
+    "root"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 20, 2026

changedInput schema / properties / idlePauseSeconds / description

Previous value: -"Pause after this many idle seconds (no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes). Default 60; 0 never; otherwise 10 to 86400."New value: +"Pause after this many idle seconds (no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes). Default 300; 0 never; otherwise 60 to 86400, a shorter time raised to 60."

Changed1 schema field changedOct 19, 2026

addedInput schema / properties / secrets

Added value: +{
+  "description": "The egress secrets it may use, by name (at most 64): only these of the secrets that reach it; [] none; omit for all. Fixed for its life.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedOct 14, 2026

changedInput schema / properties / funding / description

Previous value: -"Accepted and ignored: included usage first, then credit."New value: +"Accepted and ignored: free usage first, then credit."

AddedOct 7, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the generic write/open-world/idempotent profile, while the description adds substantive behavior: billing order (free usage then credit, 'nothing to choose'), idle-pause at 300 seconds, quota caps for uncredited accounts, and that a paused sandbox holds no slot. Nothing here conflicts with the annotations, and the funding/pausable no-op notes explain surprising parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, image contents, and defaults before the quota caveats, and every sentence carries information. The final quota sentence is dense and hard to parse on one read ('8 vCPU / 16 GiB in all, at most 5 sandboxes kept and 50 made a day'), which costs it the top score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 30-parameter, nested-object creation tool with no output schema, the description covers the essentials an agent needs before calling: defaults, wait behavior, what is returned ('returns its state', plus idempotencyKey), and quota limits. Remaining gaps (region, image resolution, volumes) are largely handled by schema descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 87%, so the baseline is 3, but the description adds real meaning the schema lacks: the effective default shape (2 vCPU / 4096 MiB / 4096 MiB disk), no time limit by default, and the credit-dependent ceilings on vcpu/memory/disk and sandbox counts. Region, cpu, volumes, and tailscale are still left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with concrete content: 'Create a Linux sandbox (Ubuntu with python3, node, bun, git, gcc and sudo)'. That clearly distinguishes it from creation-adjacent siblings such as runtime_sandboxes_fork, runtime_sandboxes_list, or runtime_sandboxes_manage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tells the agent the creation lifecycle: it waits up to 60 seconds, returns its state, and 'run commands once it is running' points at the exec sibling. No explicit when-not or direct alternative (fork, snapshot) is named, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Runtime Cloud tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

runtime_sandboxes_create

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources