Files

The files API lets you write source code or data into a running session and read files back out. Files are written relative to the session root. Binary files are supported via base64 encoding.

Write files

POST up to 200 files in a single request. About 9 MB of file content per write, either encoding; split larger files across multiple writes. Paths are relative to the session root and must not contain traversal sequences (../). Parent directories are created automatically.

curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/files \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "hello.py",
        "content": "print(\"hello from Cells\")",
        "encoding": "utf8"
      },
      {
        "path": "data/config.json",
        "content": "{\"debug\": true}",
        "encoding": "utf8"
      }
    ]
  }'

curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/files \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "hello.py",
        "content": "print(\"hello from Cells\")",
        "encoding": "utf8"
      },
      {
        "path": "data/config.json",
        "content": "{\"debug\": true}",
        "encoding": "utf8"
      }
    ]
  }'

Read a file

GET a single file by path. Maximum file size is 10 MB. Binary files are returned with "encoding": "base64".

curl "https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/files?path=hello.py" \
  -H "x-api-key: API_KEY"

curl "https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/files?path=hello.py" \
  -H "x-api-key: API_KEY"

{
  "success": true,
  "path": "hello.py",
  "content": "print(\"hello from Cells\")",
  "encoding": "utf8",
  "sha256": "a1b2c3...",
  "size": 26
}

{
  "success": true,
  "path": "hello.py",
  "content": "print(\"hello from Cells\")",
  "encoding": "utf8",
  "sha256": "a1b2c3...",
  "size": 26
}

Binary files

Set "encoding": "base64" when writing binary content. The server decodes the base64 string before writing, so the file on disk is the raw binary.

{
  "files": [
    {
      "path": "image.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAA...",
      "encoding": "base64"
    }
  ]
}

{
  "files": [
    {
      "path": "image.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAA...",
      "encoding": "base64"
    }
  ]
}

List files

There is no dedicated list-files endpoint. Use the exec endpoint to run ls, find, or any other shell command and capture the output.

{
  "cmd": ["ls", "-la", "/workspace"]
}

{
  "cmd": ["ls", "-la", "/workspace"]
}

Rate limits

Write calls are limited to 120 requests per minute per organization. Read calls are limited to 60 requests per minute per organization. Each read triggers a remote exec call with up to a 30-second timeout.