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: trueare 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.
| Profile | Resources | Price |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / hour |
default | 4 vCPU, 8 GB RAM | $0.072 / hour |
large | 8 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
| Method | Path | Description |
|---|---|---|
POST | /api/v1/sandboxes | Create a sandbox. Body includes profile; optionally name, template and ttl_seconds. |
GET | /api/v1/sandboxes | List your sandboxes |
GET | /api/v1/sandboxes/capabilities | List enabled template aliases and sandbox capabilities |
GET | /api/v1/sandboxes/{id} | Get one sandbox |
POST | /api/v1/sandboxes/{id}/host | Expose a sandbox port through a protected HTTPS URL |
POST | /api/v1/sandboxes/{id}/commands | Run a shell command |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Status and output of a detached command |
PUT | /api/v1/sandboxes/{id}/files | Write a file |
GET | /api/v1/sandboxes/{id}/files?path= | Read a file |
POST | /api/v1/sandboxes/{id}/stop | Stop (billing pauses) |
POST | /api/v1/sandboxes/{id}/resume | Resume a stopped sandbox |
POST | /api/v1/sandboxes/{id}/renew | Extend 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:
| Field | Type | Default | Notes |
|---|---|---|---|
name | string | — | Stable name up to 120 characters. Unique per account. |
template | string | — | Server-configured template alias. Raw upstream snapshot names are never accepted. |
ttl_seconds | integer | 86400 | Auto-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
| Field | Type | Default | Notes |
|---|---|---|---|
command | string | required | Shell command, up to 20,000 characters |
timeout_seconds | integer | 30 | 1 to 600 |
detached | boolean | false | Run in the background; poll with the process_id returned |
cwd | string | . | 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
runningwithin 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": "..."}}.
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_PROFILE | Unknown profile |
| 400 | INVALID_TEMPLATE | Template alias is not enabled by the service operator |
| 409 | SANDBOX_NAME_REUSED | Name or idempotency key was reused with different create settings |
| 422 | IDEMPOTENCY_KEY_REQUIRED | A named sandbox create is missing the Idempotency-Key header |
| 402 | INSUFFICIENT_CREDITS | Balance below the $1 minimum to create or resume |
| 422 | INVALID_INPUT | A field is missing or out of range (task-style endpoints) |
| 502 | SANDBOX_UPSTREAM_ERROR | Temporary 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.