Sandbox API

The Sandbox API gives your code or AI agent an isolated cloud Linux machine on demand. Create a sandbox, run shell commands, read and write files, then stop or delete it, all over REST with the same x-api-key and credit balance you use for image, video and audio generation.

Not the same as Sandbox (test) keys. API keys created with is_test: true are called "sandbox keys" and return mock results for generation endpoints (see API Reference). The Sandbox API described here creates real cloud machines. A test key can call the Sandbox API endpoints, but it returns a mock result and creates nothing.

Sizes and pricing

Pass profile when creating a sandbox. Billing is per second while the sandbox is running, charged from your credits.

ProfileResourcesPrice
small2 vCPU, 4 GB RAM$0.036 / hour
default4 vCPU, 8 GB RAM$0.072 / hour
large8 vCPU, 16 GB RAM$0.144 / hour
  • The hourly rate is locked when the sandbox is created.
  • Stopped sandboxes are free. Files are kept while stopped.
  • You need at least a $1 balance to create or resume a sandbox.

Quick start

export MUAPI_KEY="your-api-key"

# 1. Create a sandbox
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.muapi.ai/api/v1/sandboxes \
  -H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"profile": "default", "name": "my-app", "ttl_seconds": 7200}'
# -> {"id": "…", "name": "my-app", "state": "running", "profile": "default", …}

export ID="<id from the response>"

# 2. Expose a service on port 8080 through a protected HTTPS URL
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/host \
  -H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
  -d '{"port": 8080}'
# -> {"port": 8080, "url": "https://<host>/?_token=<secret>", "hostname": "<host>"}

# 3. Run a command
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/commands \
  -H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
  -d '{"command": "python3 --version", "timeout_seconds": 30}'

# 4. Write and read a file
curl -X PUT https://api.muapi.ai/api/v1/sandboxes/$ID/files \
  -H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
  -d '{"path": "/home/user/hello.py", "content": "print(\"hi\")"}'

curl "https://api.muapi.ai/api/v1/sandboxes/$ID/files?path=/home/user/hello.py" \
  -H "x-api-key: $MUAPI_KEY"

# 5. Stop it (billing pauses)
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/stop \
  -H "x-api-key: $MUAPI_KEY"

Python

import os, requests

BASE = "https://api.muapi.ai/api/v1/sandboxes"
H = {"x-api-key": os.environ["MUAPI_KEY"]}

sb = requests.post(BASE, headers=H, json={"profile": "small"}).json()
sid = sb["id"]

out = requests.post(f"{BASE}/{sid}/commands", headers=H,
                    json={"command": "echo hello && uname -a"}).json()
print(out)

requests.post(f"{BASE}/{sid}/stop", headers=H)

Endpoints

MethodPathDescription
POST/api/v1/sandboxesCreate a sandbox. Body includes profile; optionally name, template and ttl_seconds.
GET/api/v1/sandboxesList your sandboxes
GET/api/v1/sandboxes/capabilitiesList enabled template aliases and sandbox capabilities
GET/api/v1/sandboxes/{id}Get one sandbox
POST/api/v1/sandboxes/{id}/hostExpose a sandbox port through a protected HTTPS URL
POST/api/v1/sandboxes/{id}/commandsRun a shell command
GET/api/v1/sandboxes/{id}/commands/{process_id}Status and output of a detached command
PUT/api/v1/sandboxes/{id}/filesWrite a file
GET/api/v1/sandboxes/{id}/files?path=Read a file
POST/api/v1/sandboxes/{id}/stopStop (billing pauses)
POST/api/v1/sandboxes/{id}/resumeResume a stopped sandbox
POST/api/v1/sandboxes/{id}/renewExtend the auto-stop lease and mark the sandbox active
DELETE/api/v1/sandboxes/{id}Delete a sandbox and its files

Create settings and safe retries

POST /sandboxes accepts these optional fields:

FieldTypeDefaultNotes
namestring—Stable name up to 120 characters. Unique per account.
templatestring—Server-configured template alias. Raw upstream snapshot names are never accepted.
ttl_secondsinteger86400Auto-stop lease from 1 second to 30 days.

If name is set, send an Idempotency-Key header. Repeating the same name, key and create settings returns the same sandbox. Reusing a name or key with different settings returns 409. GET /sandboxes/capabilities lists template aliases enabled for your account. A template alias such as suparagent is available only when the service operator has configured it.

The suparagent alias starts from a service-prepared app snapshot. Pass "template": "suparagent" only when GET /sandboxes/capabilities lists it.

Host a port

POST /api/v1/sandboxes/{id}/host takes {"port": 8080} and returns a stable, protected HTTPS URL for that port. The sandbox must be running. Repeating the request is safe, including after a resume.

The returned url contains a bearer token in its _token query parameter. Anyone who has the full URL can access the hosted service, so keep it secret and avoid logging or sharing it. Port hosting is available only through this REST route; task-style prediction results do not store or return this credential-bearing URL.

Use POST /api/v1/sandboxes/{id}/renew with {"ttl_seconds": 7200} to extend the auto-stop lease and mark the sandbox active. POST /resume accepts optional profile and ttl_seconds fields for a stopped sandbox.

Run a command

POST /api/v1/sandboxes/{id}/commands

FieldTypeDefaultNotes
commandstringrequiredShell command, up to 20,000 characters
timeout_secondsinteger301 to 600
detachedbooleanfalseRun in the background; poll with the process_id returned
cwdstring.Working directory. It must already exist (for example mkdir -p /home/user/workspace first)

For long jobs, set detached: true, then poll GET /api/v1/sandboxes/{id}/commands/{process_id}.

Files

PUT /files takes {"path": "...", "content": "..."} with plain-text content (up to 2,000,000 characters). GET /files?path=... returns {"path": "...", "content": "..."}.

Lifecycle and billing

  • A new sandbox is running within a couple of seconds and has Python 3 preinstalled.
  • Stop is not instant. Billing stops at the moment you request it, but resuming immediately may return a conflict for a few seconds. The stop call waits for the sandbox to finish archiving before it returns, so stop then resume is safe.
  • Files persist across stop and resume.
  • A sandbox is stopped automatically when your balance can't cover usage, or after 15 minutes without activity.
  • A stopped sandbox is deleted after 14 days. Download anything you need before then.
  • Each account can have up to 3 sandboxes at once.
  • Commands and file access run as a normal user inside an isolated machine. You are responsible for what you run in it.

Playground and task-style endpoints

Create, get, command, file, stop, resume and delete are also available in the Playground and as task-style endpoints, POST /api/v1/sandbox-<operation>, where <operation> is one of create, get, run-command, command-status, write-file, read-file, stop, resume, delete. These take the same fields as the REST routes plus sandbox_id where relevant, and return a request_id you read from GET /api/v1/predictions/{request_id}/result, like any other Muapi model. Port hosting and lease renewal are REST-only. Compute is billed by running time only; these requests themselves cost $0.

Errors

Errors use {"error": {"code": "...", "message": "..."}}.

StatusCodeMeaning
400INVALID_PROFILEUnknown profile
400INVALID_TEMPLATETemplate alias is not enabled by the service operator
409SANDBOX_NAME_REUSEDName or idempotency key was reused with different create settings
422IDEMPOTENCY_KEY_REQUIREDA named sandbox create is missing the Idempotency-Key header
402INSUFFICIENT_CREDITSBalance below the $1 minimum to create or resume
422INVALID_INPUTA field is missing or out of range (task-style endpoints)
502SANDBOX_UPSTREAM_ERRORTemporary backend error, retry

Use cases

  • Coding agents: clone a repo, install packages, run tests and fix failures on a real machine.
  • Code execution: run generated or untrusted code away from your own infrastructure.
  • Media pipelines: run ffmpeg or custom scripts on outputs from Muapi image, video and audio models.
  • Hosted open-source apps: run apps in the cloud with the user's own Muapi key.

See the Sandbox API landing page for an overview.