Skip to main content
Glama
Purgatory (p7y)
by csakaszamok

create_sandbox

Provision an isolated Docker sandbox with its own daemon, configurable CPU/memory limits, templates, and SSH access; use it to run coding agents and deploy compose stacks.

Instructions

Create sandbox HTTP POST /sandboxes

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "create_sandbox"
  }
}

Input Schema

NameRequiredDescriptionDefault
cpusNoCPU limit (cores). Default SANDBOX_CPUS; users up to SANDBOX_MAX_CPUS, the admin up to the host.
nameNoOmit for a generated one (six letters and digits, k3x9q2): the name in the answer says which. GET /sandbox-name suggests one first.
ownerNoAdmin only: who the sandbox belongs to, someone who can sign in here. Omit for the caller.
memoryNoMemory limit (512m, 4g). Default SANDBOX_MEMORY; users up to SANDBOX_MAX_MEMORY, the admin up to the host.
runtimeNoHow the sandbox runs (GET /runtimes). Omit for DEFAULT_RUNTIME (auto: sysbox where installed, else dind); kata where allowed (opt-in).
ssh_keysNoExtra SSH public keys for this sandbox only (your keys from /ssh-keys always get in)
templateNoWhat runs inside (GET /templates). Omit for DEFAULT_TEMPLATE (starter).
idle_timeoutNoStop the sandbox after this long without HTTP traffic; the next request wakes it. Days are kept as hours (1d = 24h). 0 or off = never. Omit for template idle_timeout (default 30m).
deep_sleep_afterNoTake the sandbox down (containers + network freed, data kept) after it has been stopped this long; the next request rebuilds it. "off" disables. Omit for template deep_sleep_after (default 7d).
create_inner_stackNoWhether to deploy the template's starter stack, as it is (it cannot be changed; deploy your own apps afterwards)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.21.0
    • changedInput schema / properties / runtime / description
      Previous value: -"How the sandbox runs (GET /runtimes). Omit for DEFAULT_RUNTIME (auto: sysbox where installed, else dind)."New value: +"How the sandbox runs (GET /runtimes). Omit for DEFAULT_RUNTIME (auto: sysbox where installed, else dind); kata where allowed (opt-in)."
  2. Changed1 schema field changedv0.20.1
    • addedInput schema / properties / owner
      Added value: +{
      +  "description": "Admin only: who the sandbox belongs to, someone who can sign in here. Omit for the caller.",
      +  "type": "string"
      +}
  3. Changed2 schema fields changedv0.18.0
    • removedInput schema / properties / compose
      Removed value: -{
      -  "description": "Use this compose text instead of the template's compose.yaml (the template's before_script and defaults still apply). GET /templates/:name gives the template's text to start from. At most 256 KB.",
      -  "type": "string"
      -}
    • changedInput schema / properties / create_inner_stack / description
      Previous value: -"Whether to deploy the inner docker-compose stack defined in the template"New value: +"Whether to deploy the template's starter stack, as it is (it cannot be changed; deploy your own apps afterwards)"
  4. Changed2 schema fields changedv0.13.1
    • addedInput schema / properties / name / description
      Added value: +"Omit for a generated one (six letters and digits, k3x9q2): the name in the answer says which. GET /sandbox-name suggests one first."
    • removedInput schema / required
      Removed value: -[
      -  "name"
      -]
  5. Changed2 schema fields changedv0.11.3
    • changedInput schema / properties / idle_timeout / description
      Previous value: -"Stop the sandbox after this long without HTTP traffic; the next request wakes it. 0 or off = never. Omit for template idle_timeout (default 30m)."New value: +"Stop the sandbox after this long without HTTP traffic; the next request wakes it. Days are kept as hours (1d = 24h). 0 or off = never. Omit for template idle_timeout (default 30m)."
    • changedInput schema / properties / idle_timeout / pattern
      Previous value: -"^([1-9][0-9]*(s|m|h)|0|off)$"New value: +"^([1-9][0-9]*(s|m|h|d)|0|off)$"
  6. First observedv0.7.1

TDQS

C2.5/5.0
Behavior2/5

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

With no annotations supplied, the description carries the full behavioral burden, yet it never says this is a mutating, resource-consuming operation that provisions containers and may incur limits, nor anything about errors, idempotency, or cost. Some behavioral detail (defaults, caps, admin-only owner) lives in the schema descriptions, but the description itself adds nothing about consequences.

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 short and the verb-led title is front-loaded, but the second line ("HTTP POST /sandboxes") is transport detail that earns little place for an agent choosing and calling the tool, and the brevity here reads as under-specification rather than discipline.

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

Completeness2/5

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

For a 10-parameter provisioning tool with no annotations and no output schema, the description explains almost nothing: not what a sandbox is, that creation starts running a template stack, or that the response reports the generated name. The rich schema covers parameters but not the tool's overall contract.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter already carries meaning, examples, defaults, and limits. The description contributes nothing about parameters, but the baseline of 3 is appropriate when the schema does all the work.

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

Purpose3/5

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

"Create sandbox" names a specific verb and resource, so an agent knows this provisions a sandbox rather than acting on one. However, it draws no line against related provisioning tools such as create_sandbox_folder or add_sandbox_mount, and the only additional content is the raw HTTP endpoint, which adds no discriminating detail.

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

Usage Guidelines2/5

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

The description gives no guidance on when to call this rather than a sibling, no prerequisites, and no note that every parameter is optional and defaulted. The HTTP POST line is endpoint trivia, not usage guidance, so an agent must infer everything from the schema.

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