Runtime Cloud

runtime_sandboxes_manage

DestructiveIdempotent

stop: end it and its compute charges, keeping its disk (billed as paused storage) for restart. delete: stop it, delete its disk and paused memory, revoke its previews and ports, and remove it from lists for good (its snapshots stay). pause: keep memory and disk, stop compute charges. wake: continue a paused one (seconds: its new time limit, if it has one; no_capacity means retry); a paused one with autoWake also wakes by itself on the next exec, file, terminal or preview request. extend: seconds more for one with a time limit (one without needs none). retention: days (1 to 365) a paused or stopped one is kept; null, the default, keeps it while your account has credit. persist: policy {persistent, maxTotalCostMicros?} keeps it running until stopped, never idle-paused. restart: start a stopped one from its disk. switch-image: move it to image, keeping only /workspace (its home), volumes, env, name and previews; processes restart and everything else on its disk is lost (snapshot first to keep everything); undone if anything fails. update: change name, labels, env (values are never shown again), autoWake, wakeOnTimers, user, idlePauseSeconds (counted from the last activity), timeoutSeconds or onTimeout. resize: diskMiB alone grows a running one's disk live, nothing restarted; vcpu and/or memoryMiB change by a restart on its own server; the whole disk stays and every running program stops (a paused one's memory is discarded); no_capacity means its server has no room for the new size, and nothing changed. Waits until done.

Input Schema

Name	Required	Description
`id`	Yes
`env`	No	update: environment for every later command; a value sets a variable, null removes it.
`days`	No	retention: days to keep a paused sandbox, or null to keep it while your account has credit.
`keep`	No	switch-image: optional, only "workspace", the only thing a switch keeps; older clients send it.
`name`	No	update: a new name, unique in the account.
`user`	No	update: who later commands and terminals run as when they name no one.
`vcpu`	No	resize: the new vCPUs, 1 to 16 (without credit 2).
`wait`	No	Wait until the change is done (default).
`image`	No	switch-image: the image to move to: id, name, name:tag or name@version.
`action`	Yes
`labels`	No	Your own key/value tags, at most 32. Filter lists with label=key:value.
`policy`	No
`diskMiB`	No	resize: the new disk in MiB, only larger, at most 409600 (without credit 10240); asked alone of a running sandbox it grows live, otherwise at the restart.
`restart`	No	resize: optional; false grows a running sandbox's disk live or refuses, never restarting (diskMiB alone).
`seconds`	No	extend: move its time limit this many seconds later. wake: its new time limit, for a sandbox that has one.
`autoWake`	No	update: whether a request wakes it when paused.
`memoryMiB`	No	resize: the new memory in MiB, 128 to 65536 (without credit 4096).
`onTimeout`	No	update: what its time limit's end does.
`wakeOnTimers`	No	update: whether a process's timer wakes it from an idle pause.
`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	update: a new time limit from now, 60 to 86400 seconds, sooner or later than before; 0 removes it.
`idlePauseSeconds`	No	update: pause after this many idle seconds, 60 to 86400 (a shorter time raised to 60); 0 never.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 31, 2026

addedInput schema / properties / wakeOnTimers

Added value: +{
+  "description": "update: whether a process's timer wakes it from an idle pause.",
+  "type": "boolean"
+}

Changed1 schema field changedOct 25, 2026

addedInput schema / properties / user

Added value: +{
+  "description": "update: who later commands and terminals run as when they name no one.",
+  "enum": [
+    "sandbox",
+    "root"
+  ],
+  "type": "string"
+}

Changed3 schema fields changedOct 22, 2026

changedInput schema / properties / diskMiB / description

Previous value: -"resize: the new disk in MiB, only larger, at most 409600 (without credit 10240); the filesystem grows at the restart."New value: +"resize: the new disk in MiB, only larger, at most 409600 (without credit 10240); asked alone of a running sandbox it grows live, otherwise at the restart."

removedInput schema / properties / restart / const
```
Removed value: -true
```

changedInput schema / properties / restart / description

Previous value: -"resize: optional, only true; a resize always restarts. Older clients send it."New value: +"resize: optional; false grows a running sandbox's disk live or refuses, never restarting (diskMiB alone)."

Changed1 schema field changedOct 20, 2026

changedInput schema / properties / idlePauseSeconds / description

Previous value: -"update: pause after this many idle seconds, 10 to 86400; 0 never."New value: +"update: pause after this many idle seconds, 60 to 86400 (a shorter time raised to 60); 0 never."

Changed5 schema fields changedOct 18, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "stop",
-  "pause",
-  "wake",
-  "extend",
-  "retention",
-  "persist",
-  "restart",
-  "update",
-  "delete",
-  "switch-image"
-]New value: +[
+  "stop",
+  "pause",
+  "wake",
+  "extend",
+  "retention",
+  "persist",
+  "restart",
+  "update",
+  "delete",
+  "switch-image",
+  "resize"
+]

addedInput schema / properties / diskMiB

Added value: +{
+  "description": "resize: the new disk in MiB, only larger, at most 409600 (without credit 10240); the filesystem grows at the restart.",
+  "maximum": 409600,
+  "minimum": 3072,
+  "type": "integer"
+}

addedInput schema / properties / memoryMiB

Added value: +{
+  "description": "resize: the new memory in MiB, 128 to 65536 (without credit 4096).",
+  "maximum": 65536,
+  "minimum": 128,
+  "type": "integer"
+}

addedInput schema / properties / restart

Added value: +{
+  "const": true,
+  "description": "resize: optional, only true; a resize always restarts. Older clients send it.",
+  "type": "boolean"
+}

addedInput schema / properties / vcpu

Added value: +{
+  "description": "resize: the new vCPUs, 1 to 16 (without credit 2).",
+  "maximum": 16,
+  "minimum": 1,
+  "type": "integer"
+}

Changed2 schema fields changedOct 17, 2026

addedInput schema / properties / onTimeout

Added value: +{
+  "description": "update: what its time limit's end does.",
+  "enum": [
+    "pause",
+    "stop",
+    "delete"
+  ],
+  "type": "string"
+}

addedInput schema / properties / timeoutSeconds

Added value: +{
+  "description": "update: a new time limit from now, 60 to 86400 seconds, sooner or later than before; 0 removes it.",
+  "maximum": 86400,
+  "minimum": 0,
+  "type": "integer"
+}

AddedOct 7, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only declare destructive/idempotent hints, but the description adds cost behavior (compute charges stop, paused storage billing), irreversible data loss for delete and switch-image, the 'snapshot first' mitigation, rollback on failure, live-vs-restart disk growth, and no_capacity outcomes. 'Waits until done' is disclosed too.

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

Conciseness3/5

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

It is front-loaded with the most-used actions and every clause carries information, but it reads as one dense run-on block with no line breaks and repeats several schema parameter descriptions (seconds, days, diskMiB, keep). Structure, not length, is the weakness.

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

Completeness5/5

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

For an 11-action, 22-parameter mutation tool with nested policy and no output schema, the description covers destructive outcomes, cost implications, failure modes, and waiting behavior. An agent has what it needs to act safely.

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 86%, so the baseline is 3; the description adds value by tying parameters to actions and by clarifying interactions the schema states piecemeal (diskMiB alone growing live, restart=false refusing instead of restarting, seconds meaning extend vs. wake's time limit, keep only 'workspace'). Some parameter text is duplicated from the schema rather than adding new meaning.

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

Purpose4/5

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

The description enumerates concrete verbs and resources per action (stop, delete, pause, wake, extend, retention, persist, restart, switch-image, update, resize), so an agent knows this is the sandbox lifecycle-management tool. It does not name sibling tools (e.g. runtime_sandboxes_exec, runtime_sandboxes_create) to sharpen that boundary, keeping it short of a 5.

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

Usage Guidelines5/5

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

Each action's consequence is stated in a way that directly selects between alternatives: stop keeps the disk for restart, pause keeps memory and disk, delete removes disk and paused memory for good, retention sets keep-days, persist prevents idle pausing. The agent can choose an action without guessing.

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_manage

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources