Files

client.files manages files inside a live sandbox. All paths resolve inside /workspace; relative paths are interpreted from there, and paths that escape the workspace through .. segments are rejected with path_outside_workspace.

Direct reads and writes are capped at 256 KB. For larger files, use downloadUrl to fetch content, or run a command inside the sandbox to produce the file and export it as an artifact.

Every method on a SandboxHandle is also available without the sandboxId argument, for example sandbox.files.read("notes.txt").

read

Read a file's content as a string.

read(
  sandboxId: `sbx_${string}`,
  path: string,
  input?: { encoding?: "utf8" | "base64" },
): Promise<string>

const content = await client.files.read(sandbox.id, "results.json");

Error codes: file_not_found, path_is_directory, file_too_large (over 256 KB — use downloadUrl), path_outside_workspace, invalid_file_encoding.

write

Write content to a file and get back its FileStat.

write(
  sandboxId: `sbx_${string}`,
  path: string,
  content: string,
  input?: {
    createParents?: boolean;
    encoding?: "utf8" | "base64";
    overwrite?: boolean;
  },
): Promise<FileStat>

await client.files.write(sandbox.id, "data/input.csv", csv, {
  createParents: true,
});

Error codes: file_too_large, file_already_exists, parent_directory_not_found, path_is_directory, path_outside_workspace.

delete

Delete a file or an empty directory. There's no recursive delete; a non-empty directory fails with directory_not_empty.

delete(sandboxId: `sbx_${string}`, path: string): Promise<void>

await client.files.delete(sandbox.id, "tmp/scratch.txt");

Error codes: file_not_found, directory_not_empty, path_outside_workspace.

list

List directory entries. Defaults to /workspace.

list(sandboxId: `sbx_${string}`, path?: string): Promise<ListFilesResponse>

const entries = await client.files.list(sandbox.id, "data");
for (const entry of entries.data) {
  console.log(entry.type, entry.path, entry.sizeBytes);
}

Error codes: file_not_found, path_not_directory, path_outside_workspace.

stat

Fetch metadata for a single file or directory.

stat(sandboxId: `sbx_${string}`, path: string): Promise<FileStat>

const stat = await client.files.stat(sandbox.id, "results.json");
console.log(stat.sizeBytes, stat.modifiedAt);

Error codes: file_not_found, path_outside_workspace.

mkdir

Create a directory.

mkdir(
  sandboxId: `sbx_${string}`,
  path: string,
  input?: { parents?: boolean },
): Promise<FileStat>

await client.files.mkdir(sandbox.id, "data/raw", { parents: true });

Error codes: file_already_exists, parent_directory_not_found, path_outside_workspace.

move

Move or rename a file or directory.

move(
  sandboxId: `sbx_${string}`,
  from: string,
  to: string,
  input?: { overwrite?: boolean },
): Promise<FileStat>

await client.files.move(sandbox.id, "draft.md", "final.md");

Error codes: file_not_found, file_already_exists, path_outside_workspace.

downloadUrl

Get a short-lived signed URL for downloading a file of any size. The URL is fetched with GET and authenticated with your API key (authMode: "api_key").

downloadUrl(
  sandboxId: `sbx_${string}`,
  path: string,
): Promise<{ url: string; method: "GET"; authMode: "api_key" }>

const { url } = await client.files.downloadUrl(sandbox.id, "build.tar.gz");

Error codes: file_not_found, path_is_directory, path_outside_workspace.

FileEntry and FileStat

FileStat is { path, type: "file" | "directory", sizeBytes, modifiedAt? }. FileEntry is a FileStat plus a required name for each directory entry.

Next steps

• Artifacts — durable exports from the workspace.
• Commands — generate files by running processes.
• Files concept — workspace rules in depth.