File tools and artifacts ​
Sandbox files have two audiences: text files the agent can inspect or edit, and artifacts the application exports after the run.
Expose bounded text tools ​
const fileTools = createDockerSandboxTools({
sandbox: sandbox.runtime,
tools: ['list_files', 'read_file', 'write_file'],
readFile: { defaultLineCount: 300, maxLineCount: 1_000, maxBytes: 64_000 },
writeFile: { maxBytes: 256_000 },
})Paths are workspace-relative (for example notes/result.txt). Agent tool calls also accept an absolute path inside the sandbox workdir (for example /workspace/notes/result.txt with the default workdir); paths outside the workdir are rejected. Command cwd values follow the same rule. read_file returns one bounded page of UTF-8 text; binary artifacts should use trusted runtime methods.
File writes reject symlinks in any destination path component, including dangling links, with invalid_path. The runtime checks the path before it creates directories and again before it copies bytes. A failed inspection command returns docker_command_failed, and images must provide sh. The two checks are separate operations, so a process already running in the container can still race them by replacing a path component in between.
Use runtime methods from trusted code ​
await sandbox.runtime.writeTextFile({
path: 'input/request.json',
text: JSON.stringify(validatedRequest),
})
const firstPage = await sandbox.runtime.readTextFilePage({
path: 'logs/build.log',
startLine: 1,
lineCount: 250,
maxBytes: 32_000,
})
const entries = await sandbox.runtime.listFiles({ path: 'output' })
const summary = await sandbox.runtime.readTextFile({ path: 'output/summary.md' })Use writeFile({ path, data }) and readFile({ path }) for bytes.
Export artifacts deliberately ​
const artifact = await sandbox.runtime.readFile({ path: 'output/report.pdf' })
await objectStore.put({
tenantId: job.tenantId,
key: `reports/${job.id}.pdf`,
body: artifact,
contentType: 'application/pdf',
})Validate exact paths and media types, scan artifacts when required, and copy accepted output to tenant-scoped durable storage before destroying an ephemeral sandbox. Map application-owned artifact IDs to reviewed paths instead of exposing arbitrary path reads through an HTTP route.