Create a Session

A session is an isolated runtime environment. Create one with the language and version you need. The session is ready to accept commands within a few seconds of creation.

Language examples

Select the runtime you need. All examples use the same HTTP endpoint; only the language and languageVersion fields differ.

curl -X POST https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID \
  -H "x-api-key: API_KEY" -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22","timeoutSeconds":300}'

curl -X POST https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID \
  -H "x-api-key: API_KEY" -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22","timeoutSeconds":300}'

Named cells (persistent storage)

Add a cellName to persist the workspace across sessions. The next session with the same cellName will find all files written by this one.

curl -X POST https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID \
  -H "x-api-key: API_KEY" -H "Content-Type: application/json" \
  -d '{
    "language": "node",
    "languageVersion": "22",
    "cellName": "my-workspace",
    "timeoutSeconds": 1800
  }'

curl -X POST https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID \
  -H "x-api-key: API_KEY" -H "Content-Type: application/json" \
  -d '{
    "language": "node",
    "languageVersion": "22",
    "cellName": "my-workspace",
    "timeoutSeconds": 1800
  }'

initialExec

Supply an initialExec to run a command the moment the session agent connects (within 500ms of boot). Useful for installing dependencies before the session is available to callers.

{
  "language": "node",
  "languageVersion": "22",
  "timeoutSeconds": 600,
  "initialExec": {
    "cmd": ["npm", "install"],
    "timeoutMs": 120000
  }
}

{
  "language": "node",
  "languageVersion": "22",
  "timeoutSeconds": 600,
  "initialExec": {
    "cmd": ["npm", "install"],
    "timeoutMs": 120000
  }
}

Response

A successful creation returns 201 with a sessionId, a short-lived gateway token (valid 60 seconds), a wsUrl for direct WebSocket connections, and timeoutAt. If the externalId matched an existing session, the response is 200 and includes "resumed": true.