Quickstart

Create a session, run a command, and read the output. Under 3 minutes with just a project API key from the Cells console.

Note
Prerequisites: A Mudbase project and an API key. Get one at cells.mudbase.dev.

Step 1: Create a session

Send a POST to create a new isolated runtime environment. Pick any supported language. The response includes a sessionId you use for all subsequent calls.

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:

Response
{
  "success": true,
  "sessionId": "68123abc4ef5678901234567",
  "wsUrl": "wss://ws.sandbox.mudbase.dev/sessions/68123abc4ef5678901234567",
  "token": "eyJ...",
  "expiresAt": "2026-09-30T08:11:00.000Z",
  "language": "node",
  "languageVersion": "22",
  "timeoutAt": "2026-09-30T08:15:00.000Z",
  "publicUrl": null
}
{
  "success": true,
  "sessionId": "68123abc4ef5678901234567",
  "wsUrl": "wss://ws.sandbox.mudbase.dev/sessions/68123abc4ef5678901234567",
  "token": "eyJ...",
  "expiresAt": "2026-09-30T08:11:00.000Z",
  "language": "node",
  "languageVersion": "22",
  "timeoutAt": "2026-09-30T08:15:00.000Z",
  "publicUrl": null
}

Step 2: Run a command

Execute a command inside the session. The response streams as Server-Sent Events (SSE). Each line is a JSON event with type of stdout, stderr, or exit.

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)"]}'

The raw SSE stream:

SSE stream
event: stdout
data: {"data":"42\n"}

event: exit
data: {"code":0,"error":""}
event: stdout
data: {"data":"42\n"}

event: exit
data: {"code":0,"error":""}
Note
Each event: stdout line carries one chunk of output. The final event: exit line has the exit code. Close the HTTP connection to cancel a running command early.

Step 3: Close the session

Sessions expire automatically at timeoutAt (default 5 minutes), but it is good practice to close them explicitly when you are done.

curl
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"
Tip
That is the core loop: create a session, run commands, read output, close. Everything else (files, services, persistent cells, checkpoints) builds on this foundation.

Next

NEXT →Create a sessionAll languages, sizeId, cellName, alwaysOn, and initialExec.NEXT →Run commandsStreaming SSE, environment variables, timeoutMs, and exit codes.NEXT →FilesBatch write, read, and list files inside a session.NEXT →Services and preview URLsStart a web server, expose a port, wait for readiness.