Read a File

Read a file out of a sandbox directly from your client, no exec, no cat. Reads take the agent-visible absolute path (the path as it appears inside the sandbox, e.g. /workspace/output.json), which must resolve beneath one of the sandbox's configured mounts.

Read a file

Returns the file's raw bytes. Decode them to text yourself when you need a string.

const raw = await sandbox.readFile("/workspace/output.json");
const text = new TextDecoder().decode(raw);
console.log(JSON.parse(text));

const raw = await sandbox.readFile("/workspace/output.json");
const text = new TextDecoder().decode(raw);
console.log(JSON.parse(text));

Because it returns bytes, binary files work too, write them straight to disk:

import { writeFile } from "node:fs/promises";

const png = await sandbox.readFile("/workspace/chart.png");
await writeFile("chart.png", png);

import { writeFile } from "node:fs/promises";

const png = await sandbox.readFile("/workspace/chart.png");
await writeFile("chart.png", png);

Read from an offset

Pass a byte offset to skip that many leading bytes and read from there to the end of the file. It defaults to 0 (the whole file), and is handy for resuming an interrupted download or tailing a file that's still growing. An offset equal to the file size returns an empty result; one past the end is rejected with a 400.

Polling from an advancing offset is how you stream a file as it's written — for example, live-rendering HTML or Markdown as an LLM emits it into the sandbox. Read only the new bytes each time and render as they arrive; see File streaming for the full pattern.

// Skip the first 1 KiB, read the rest.
const tail = await sandbox.readFile("/workspace/app.log", { offset: 1024 });

// Skip the first 1 KiB, read the rest.
const tail = await sandbox.readFile("/workspace/app.log", { offset: 1024 });

To discover what's available first, list a directory.

Next: Write a File