Skip to main content
The files API runs on the sandbox data plane and gives you direct access to the filesystem inside a Firecracker microVM. You can list directories, inspect file metadata, read and write file contents, move paths, and remove files — all without running a shell command. All file endpoints use the sandbox-specific data plane base URL:
Authenticate every request with a capability token in the X-Sandbox-Token header. See Tokens to learn how to mint one. Paths can be absolute (e.g. /workspace/app.js) or relative to the default user’s home directory. The path parameter is required on every endpoint that operates on a specific path.

​
GET /files

Lists the contents of a directory. Returns metadata for each entry but not the file contents themselves — use GET /files/content to download a file.
Query parameters
​
string
required
Absolute path or a path relative to the default user’s home directory.
Response — 200 OK
​
FileInfo[]
required
Directory entries.
Error codes: 400 malformed request · 401 unauthenticated · 404 path not found

​
GET /files/stat

Reads the metadata of a single file or directory without returning its contents.
Query parameters
​
string
required
Absolute path or relative to the default user’s home.
Response — 200 OK Returns a single FileInfo object with the same fields as the entries in GET /files: path, name, kind, size, mode, modified_at, and optionally target. Error codes: 400 malformed request · 401 unauthenticated · 404 path not found

​
POST /files/directories

Creates a directory. By default this also creates all intermediate parent directories (mkdir -p semantics). The call is idempotent: if the directory already exists, it returns 204 without error.
Request body
​
string
required
The directory path to create.
​
boolean
Create intermediate parent directories as needed. Defaults to true.
​
string
Unix permission bits in octal, for example 0755. Applied to the created directory.
Response — 204 No Content Error codes: 400 malformed request · 401 unauthenticated

​
GET /files/content

Downloads the raw bytes of a file. The response body is the file content with Content-Type: application/octet-stream. Response headers include X-File-Mode (permission bits) and X-File-Modified-At (ISO 8601 last-modified time).
Query parameters
​
string
required
Absolute path or relative to the default user’s home.
Response — 200 OK Raw file bytes with Content-Type: application/octet-stream. Response headers Error codes: 400 malformed request · 401 unauthenticated · 404 file not found

​
PUT /files/content

Uploads a file to the given path. The file is written atomically — the old contents are not visible to other processes during the write. If the path does not exist it is created; if it does, it is overwritten.
Query parameters
​
string
required
Destination path inside the sandbox.
​
string
Unix permission bits in octal, for example 0644. Applied to the written file. Omit to use the default mode.
Request body Raw file bytes with Content-Type: application/octet-stream. Response — 204 No Content Error codes: 400 malformed request · 401 unauthenticated

​
POST /files/move

Moves or renames a file or directory. The source must exist. By default the destination must not exist; set overwrite to true to replace it.
Request body
​
string
required
The path to move from.
​
string
required
The path to move to.
​
boolean
Replace the destination if it already exists. Defaults to false. When false and the destination exists, the call returns 409 Conflict.
Response — 204 No Content Error codes: 400 malformed request · 401 unauthenticated · 404 source not found · 409 destination exists and overwrite is false

​
DELETE /files

Removes a file or directory. Pass recursive=true to remove a non-empty directory and all its contents.
Query parameters
​
string
required
Absolute path or relative to the default user’s home.
​
boolean
Remove a directory and all its contents. Defaults to false. When false and the path is a non-empty directory, the call returns 400.
Response — 204 No Content Error codes: 400 malformed request or non-empty directory without recursive=true · 401 unauthenticated · 404 path not found