Files and the workspace

Every sandbox has a workspace: the working filesystem area at /workspace inside the live sandbox. The file APIs let you read, write, list, move, and delete files there while the sandbox is alive. The workspace disappears when the sandbox is destroyed, so export anything durable as an artifact.

Workspace confinement

All file APIs are confined to /workspace. Every path you pass must resolve inside it; paths that escape — including through symlinks — are rejected with path_outside_workspace. Sandboxes never receive host or provider credentials, and the file APIs can't reach anything outside the workspace.

Reading and writing files

Direct reads and writes work on file content up to 256 KB. Larger files use download URLs instead.

• GET /v1/sandboxes/{id}/files/read with query path returns { content, encoding, sizeBytes, path }. Files over 256 KB return file_too_large — request a download URL instead.
• PUT /v1/sandboxes/{id}/files with body path and content writes a file, up to 256 KB. Optional fields: overwrite (default true) and createParents (default false). With createParents false, writing into a missing directory returns parent_directory_not_found.
• POST /v1/sandboxes/{id}/files/download-url with body { path } returns { url, method: "GET", expiresAt } — a short-lived URL that streams the file at any size.

Encodings

Reads and writes accept an encoding of utf8 (default) or base64. Use base64 for binary content. An unsupported value returns invalid_file_encoding.

Listing and inspecting

Two read endpoints describe the workspace without transferring file content.

• GET /v1/sandboxes/{id}/files lists a directory (query path, default /workspace) and returns { data: FileEntry[] }.
• GET /v1/sandboxes/{id}/files/stat returns metadata for one path.

Entries have path, type (file or directory), sizeBytes, and optionally name and modifiedAt.

Directory operations

The write endpoints cover directory creation, moves, and deletion.

• POST /v1/sandboxes/{id}/files/mkdir creates a directory (body path, optional parents, default false). Without parents, a missing parent returns parent_directory_not_found.
• POST /v1/sandboxes/{id}/files/move moves or renames (body from, to, optional overwrite, default false). With overwrite false, an existing destination returns file_already_exists.
• DELETE /v1/sandboxes/{id}/files with query path deletes a file or an empty directory and returns { deleted: true }.

[!NOTE] There is no recursive delete. Deleting a non-empty directory returns directory_not_empty. Remove the contents first, or run a command such as rm -rf inside the sandbox.

File error codes

These error codes are specific to the file APIs:

Next steps

• Artifacts — keep files beyond the sandbox lifetime.
• Commands — run processes that produce and consume workspace files.
• SDK quickstart
• Files API reference