Guides

Cells (sandbox execution)

Provision an isolated execution environment, run commands with streaming output, write files, start long-running services, and expose a public HTTPS URL.

A Cell is a short-lived or persistent Linux container tied to your project. You create one session per workload, interact with it over the REST API, and tear it down when done. All endpoints live under https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID and accept your project API key.

Note
All examples use plain curl. The generated TypeScript and Python SDKs cover the same surface; see the SDKs overview for installation instructions.

1. Create a session

Send a POST to the project endpoint with the language and a timeout. The container starts immediately; for micro size the warm pool typically delivers it in under a second.

bash
curl -X POST https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22","timeoutSeconds":300}'
curl -X POST https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22","timeoutSeconds":300}'

The response contains the sessionId you use in every subsequent call:

json
{
  "success": true,
  "sessionId": "68123abc4ef5678901234567",
  "expiresAt": "2026-10-01T08:15:00.000Z",
  "language": "node",
  "languageVersion": "22",
  "publicUrl": null
}
{
  "success": true,
  "sessionId": "68123abc4ef5678901234567",
  "expiresAt": "2026-10-01T08:15:00.000Z",
  "language": "node",
  "languageVersion": "22",
  "publicUrl": null
}

Supported languages and their runtime identifiers:

  • node / javascript - Node.js (versions 20, 22)
  • python - Python (version 3.12)
  • go - Go (version 1.23)
  • rust - Rust (version 1.82)
  • php - PHP (version 8.3)
  • java - Java (version 21)
  • ruby - Ruby (version 3.3)
  • csharp - C# / .NET (version 8.0)
  • bash - Bash (version 5)

To use multiple runtimes in one session, pass a languages array instead of language and languageVersion. Up to 4 runtimes per session.

2. Run a command (exec with streaming)

The /exec endpoint returns a Server-Sent Events stream. Each line of stdout arrives as data: stdout:<line>, stderr as data: stderr:<line>. A final data: exit:<code> event closes the stream. Keepalive comment lines (: keepalive) appear every 10 seconds and should be ignored.

bash
curl -N -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/exec \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":["node","-e","console.log(6*7)"]}'
curl -N -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/exec \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":["node","-e","console.log(6*7)"]}'
text
data: stdout:42

data: exit:0
data: stdout:42

data: exit:0
Tip
Pass -N to curl to disable output buffering so you see each SSE event as it arrives. In application code, consume the stream with the native EventSource API or an SSE client library.

3. Write files

Write one or more files in a single request. Supply each file as a path and content pair. Content is a plain string by default; set "encoding": "base64" to send binary files.

bash
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/files \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "/workspace/index.js",
        "content": "const http = require("http");\nhttp.createServer((req,res)=>res.end("hello")).listen(3000);"
      }
    ]
  }'
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/files \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "/workspace/index.js",
        "content": "const http = require("http");\nhttp.createServer((req,res)=>res.end("hello")).listen(3000);"
      }
    ]
  }'

4. Start a service and expose a port

Start a long-running process with the /services endpoint, then use /expose to make a port reachable over HTTPS. The response gives you a stable public URL that routes to the container port.

bash
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/services \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"web","cmd":["node","/workspace/index.js"]}'
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/services \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"web","cmd":["node","/workspace/index.js"]}'
bash
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/expose \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port":3000}'
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID/expose \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port":3000}'
json
{
  "success": true,
  "publicUrl": "https://68123abc4ef5678901234567-3000.cells.mudbase.dev"
}
{
  "success": true,
  "publicUrl": "https://68123abc4ef5678901234567-3000.cells.mudbase.dev"
}

Tail the service's log output at /services/web/logs/stream using the same SSE pattern as exec.

5. Delete the session

When you are done, send a DELETE to clean up the container and stop billing. Sessions with a named-cell volume (persistent storage) keep the volume until you explicitly delete it.

bash
curl -X DELETE \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID \
  -H "X-API-Key: YOUR_API_KEY"
curl -X DELETE \
  https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID/sessions/SESSION_ID \
  -H "X-API-Key: YOUR_API_KEY"

Session sizes

Pass "sizeId": "small" (or another tier) when creating a session. The default is micro. Billing is metered per second based on the size multiplier.

  • micro: 1 vCPU, 1 GB RAM. Benefits from the warm pool for sub-second starts.
  • small: 1 vCPU, 2 GB RAM. Reference billing rate.
  • standard: 2 vCPU, 4 GB RAM. 2x the billing rate of small.
  • large: 4 vCPU, 8 GB RAM. 4x the billing rate of small.
  • max: 8 vCPU, 16 GB RAM. 8x the billing rate of small.

Checkpoints and restore

Snapshot a running session with POST .../checkpoint. This captures the full container filesystem and process memory. Restore from a checkpoint with POST .../restore to resume from that exact state in a new session. Poll the restore job status at /restores/RESTORE_ID until the status field reads complete.

Usage and billing

Query current-month usage at GET /api/sandboxes/projects/PROJECT_ID/billing/usage. Returns metered small-hours consumed so far, broken down by session size.

Note
The full API reference for all 24 Cells operations (create, exec, files, services, networking, checkpoints, billing) is available in the API Reference. The standalone Cells OpenAPI spec and generated TypeScript and Python SDKs are in the mudbase-docs repository.

Next

NEXT →Background JobsNEXT →FunctionsNEXT →Full API Reference
Chat with us