---
title: "Sandbox SDK file operations"
canonical: https://trickest.com/docs/developer-tools/sandbox-sdk/files
description: "Read and write sandbox files, handle partial uploads, and collect results before cleanup."
---

# Sandbox SDK file operations

Use **`@trickest/sandbox`** to place input files in a sandbox and download its results. The example takes a running `Sandbox` handle from the [quickstart](/docs/developer-tools/sandbox-sdk).

## Write inputs and collect a result

`writeFile(path, content)` accepts text or bytes. `writeFiles(files)` uploads several files and supports permission bits through `mode`. Relative paths use `/trickest/sandbox` by default.

```typescript
import { writeFile } from "node:fs/promises";
import type { Sandbox } from "@trickest/sandbox";

export async function createAndDownloadReport(sandbox: Sandbox): Promise<void> {
  await sandbox.writeFiles([
    { path: "input.txt", content: "A report from the sandbox\n" },
    {
      path: "copy-report.sh",
      content: "#!/bin/sh\ncp input.txt report.txt\n",
      mode: 0o755,
    },
  ]);
  const result = await sandbox.runCommand("./copy-report.sh");
  if (result.exitCode !== 0) throw new Error(await result.stderr());

  const report = await sandbox.readFileToBuffer({ path: "report.txt" });
  if (report === null) throw new Error("Report is missing");
  await writeFile("./downloaded-report.txt", report);
}
```

`readFileToBuffer()` returns `Uint8Array` bytes. Decode text with `new TextDecoder().decode(bytes)`. The SDK converts a 404 response to `null`; if a file unexpectedly disappears, also check that you retrieved the intended sandbox.

To use another directory, set `extractDir` on writes and the matching `cwd` on commands or reads. Changing the write location does not change subsequent commands' default working directory.

## Handle upload limits and partial writes

The SDK rejects individual files larger than **8 MiB** and splits large batches
into sequential uploads. If a later upload fails, earlier files remain written;
there is no rollback.

For an HTTP upload failure, `SandboxApiError.details` includes the failed chunk index and the number of files already written. Network failures may not include those details. Inspect the destination before retrying, especially when replacing existing files.

## Keep downloads small

`readFileToBuffer()` buffers the entire response in the calling process. Although the type declaration accepts `maxBytes`, its implementation does not enforce that option. It also has no `readFileResponse()` method. Do not rely on either interface to bound downloads.

Generate bounded result files or split large outputs into smaller files before downloading. A length check after download cannot prevent the allocation that already happened.

Download results before [deleting the sandbox](/docs/developer-tools/sandbox-sdk/lifecycle). Reusing an environment also reuses the files and tools left there. Keep unrelated trust domains in separate sandboxes.

---
_Markdown source of https://trickest.com/docs/developer-tools/sandbox-sdk/files._