Metalboxes

A sandbox is a Linux microVM for one program. Your code creates it with the API, runs commands in it, reads and writes its files, and deletes it. Each sandbox has its own kernel, disk and network, so code in one sandbox cannot reach another sandbox.

Use a sandbox for code that you do not trust, such as code that an AI agent writes, and for a test or a build that must start clean.

Quick startCopy Anchor Link

1. Open API keys in the console.
2. Create a key with the Inference permission.
3. Run each step below in a terminal. Each step is one request with curl.

Create a sandboxCopy Anchor Link

export MUNITO_API_KEY="munitoai_..."

curl -sS --fail-with-body https://api.munito.ai/sandboxes/v1/sandboxes \
  -H "Authorization: Bearer $MUNITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": "small", "timeout": 600}'

The answer is the sandbox:

{
  "id": "sbx_01k8f6x7g3d2b9v5n4m1q0w8e6",
  "object": "sandbox",
  "status": "running",
  "template": "base",
  "size": "small",
  "vcpus": 1,
  "memory_mib": 1024,
  "disk_gib": 10,
  "reserved": false,
  "internet": true,
  "metadata": {},
  "created_at": 1793016000,
  "started_at": 1793016000,
  "expires_at": 1793016600,
  "ended_at": null,
  "end_reason": null,
  "command": null
}

Keep its id for the next steps:

export SANDBOX="sbx_01k8f6x7g3d2b9v5n4m1q0w8e6"

Run a commandCopy Anchor Link

curl -sS --fail-with-body "https://api.munito.ai/sandboxes/v1/sandboxes/$SANDBOX/exec" \
  -H "Authorization: Bearer $MUNITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 -c \"print(6 * 7)\""}'

{
  "exit_code": 0,
  "stdout": "42\n",
  "stderr": "",
  "duration_ms": 35,
  "timed_out": false,
  "truncated": false
}

A string runs in bash -lc. A list, such as ["python3", "-V"], is the argument vector itself. Set "stream": true to get NDJSON events while the command writes: stdout and stderr events, then one exit event.

To start a sandbox and run one command in one request, set command in the create. The sandbox runs it in /workspace with its env, for at most 60 seconds, and the answer has the result in command:

curl -sS --fail-with-body https://api.munito.ai/sandboxes/v1/sandboxes \
  -H "Authorization: Bearer $MUNITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": "small", "command": "python3 -c \"print(6 * 7)\""}'

command is null when the command could not run, and for a retry with the same Idempotency-Key. The sandbox runs in each case, until its timeout or a delete.

Write, read and list filesCopy Anchor Link

curl -sS --fail-with-body -X PUT \
  "https://api.munito.ai/sandboxes/v1/sandboxes/$SANDBOX/files/content?path=/workspace/hello.py" \
  -H "Authorization: Bearer $MUNITO_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary 'print("Hello from the sandbox")'

curl -sS --fail-with-body \
  "https://api.munito.ai/sandboxes/v1/sandboxes/$SANDBOX/files/content?path=/workspace/hello.py" \
  -H "Authorization: Bearer $MUNITO_API_KEY"

curl -sS --fail-with-body \
  "https://api.munito.ai/sandboxes/v1/sandboxes/$SANDBOX/files?path=/workspace" \
  -H "Authorization: Bearer $MUNITO_API_KEY"

A write creates the parent folders, and replaces a file that exists.

Delete the sandboxCopy Anchor Link

curl -sS --fail-with-body -X DELETE "https://api.munito.ai/sandboxes/v1/sandboxes/$SANDBOX" \
  -H "Authorization: Bearer $MUNITO_API_KEY"

The sandbox stops at once, and its files are deleted. You can still read the sandbox: its status is stopped and its end_reason is deleted.

TemplatesCopy Anchor Link

Set template in the create. A template is the root file system that each new sandbox of it starts with.

pip install installs into the system Python in both templates.

DockerCopy Anchor Link

In an ubuntu sandbox, Docker runs when the sandbox starts:

curl -sS --fail-with-body https://api.munito.ai/sandboxes/v1/sandboxes \
  -H "Authorization: Bearer $MUNITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "ubuntu", "size": "large", "command": "docker run --rm hello-world"}'

Use the default size or a larger one, because images take memory and disk. Docker Hub limits the image pulls of a user that is not logged in, so run docker login in the sandbox when you pull many images.

The base template has no Docker. Install it and start its daemon in the sandbox, one command at a time:

apt-get update && apt-get install -y docker.io
setsid dockerd --iptables=false --bridge=none >/var/log/dockerd.log 2>&1 < /dev/null &
docker run --rm --network none hello-world

The daemon keeps running after its command ends, so later commands can use it. These containers have no bridge network: use --network host for internet access, or --network none.

Agent harnessesCopy Anchor Link

Claude Code (claude), Codex (codex) and OpenCode (opencode) are installed in ubuntu. Give each one its key in env, or use them with the open models of Munito AI: see Claude Code, Codex and OpenCode.

Sizes and pricesCopy Anchor Link

A size has a ceiling and a floor. The ceiling is the vCPUs and the memory that the sandbox sees. The floor is the smallest share that the sandbox pays for. Each second, a sandbox pays for the higher of its floor and its real use, for the CPU and for the memory.

• A sandbox without size gets the default size.
• For another size, set vcpus and memory_mib in place of size. The floor of a custom size is a quarter of its ceiling.
• A preset starts from a snapshot of its template in less than a second. A custom size boots its template, which takes some seconds.
• For a larger root disk, set disk_gib, such as {"size": "large", "disk_gib": 40}. The root file system grows to that size when the sandbox starts.
• Set "reserved": true to pay for the ceiling all the time. The floor is then the ceiling.
• The Metalboxes page of the console shows the vCPU-hours, the GiB-hours and the spend of the month.

LimitsCopy Anchor Link

A sandbox has outbound internet access only. It cannot reach your other sandboxes or private addresses, and it cannot send mail over SMTP. Set "internet": false for a sandbox with no network. Inbound connections are not available yet.

Lifecycle and timeoutsCopy Anchor Link

A sandbox stops at the first of these events:

• Its timeout ends. expires_at gives the time, and end_reason is timeout.
• You delete it. end_reason is deleted.
• An error stops it. end_reason is error.

The timeout counts from the create, or from the last change. To keep a sandbox longer, send a new timeout in seconds to POST /sandboxes/{sandbox_id}/timeout. A command does not change the timeout.

When a sandbox stops, its processes and its files are gone. The API keeps its record, so GET /sandboxes/{sandbox_id} and GET /sandboxes still show it.

API referenceCopy Anchor Link

An organization with Metalboxes on sees the reference page of each operation in the console docs.