Files - Superserve

Read and write files in a sandbox’s filesystem with sandbox.files.

`write`

Write a file at an absolute path. Parent directories are created automatically.

// String content
await sandbox.files.write("/app/config.json", '{"key": "value"}')

// Binary content
await sandbox.files.write("/app/image.png", buffer)

// From Uint8Array
await sandbox.files.write("/app/data.bin", new Uint8Array([1, 2, 3]))

# String content (UTF-8 encoded)
sandbox.files.write("/app/config.json", '{"key": "value"}')

# Binary content
with open("local-image.png", "rb") as f:
    sandbox.files.write("/app/image.png", f.read())

Parameters:

Option	Type	Description
`path`	`string` / `str`	Absolute destination path.
`content`	`FileInput` / `str \| bytes`	File contents. See accepted types below.
`timeoutMs` / `timeout`	`number` / `float`	Optional request timeout.
`signal`	`AbortSignal`	TypeScript only - abort the request.

Accepted content types:

type FileInput = string | Uint8Array | ArrayBuffer | Blob

# str  - encoded as UTF-8
# bytes - written as-is

Cancellation (TypeScript):

const controller = new AbortController()
setTimeout(() => controller.abort(), 5000)

await sandbox.files.write("/app/large.bin", buffer, {
  signal: controller.signal,
})

`read`

Read a file as raw bytes.

const bytes: Uint8Array = await sandbox.files.read("/app/image.png")

data: bytes = sandbox.files.read("/app/image.png")

`readText` / `read_text`

Read a file and decode as UTF-8.

const text: string = await sandbox.files.readText("/app/config.json")

text: str = sandbox.files.read_text("/app/config.json")

`downloadDir` / `download_dir`

Download a directory as a ZIP archive. Returns the raw zip bytes — entries are prefixed with the directory’s base name (e.g. output/log.txt), and symlinks are skipped.

import { writeFileSync } from "node:fs"

const zip: Uint8Array = await sandbox.files.downloadDir("/app/output")
writeFileSync("output.zip", zip)

zip_bytes: bytes = sandbox.files.download_dir("/app/output")
with open("output.zip", "wb") as f:
    f.write(zip_bytes)

Parameters:

Option	Type	Description
`path`	`string` / `str`	Absolute directory path to archive.
`timeoutMs` / `timeout`	`number` / `float`	Optional request timeout. Large directories can exceed the 30s default.
`signal`	`AbortSignal`	TypeScript only - abort the request.

The server decides file-vs-directory: if path points at a regular file, its bytes are streamed back as-is (not zipped) — use read for files.

Round-trip example

const original = "hello, world!\n"

await sandbox.files.write("/tmp/greeting.txt", original)
const roundTripped = await sandbox.files.readText("/tmp/greeting.txt")

console.log(roundTripped === original)  // true

original = "hello, world!\n"

sandbox.files.write("/tmp/greeting.txt", original)
round_tripped = sandbox.files.read_text("/tmp/greeting.txt")

print(round_tripped == original)  # True

Path rules

Paths must start with /
Paths must not contain .. segments
Parent directories are created automatically on write

Errors

Commonly raised:

NotFoundError - file or directory does not exist (on read / downloadDir)
ValidationError - invalid path (relative, contains .., or malformed)
AuthenticationError - access token invalid or sandbox was deleted
TimeoutError / SandboxTimeoutError - the optional timeout elapsed

See Errors for the full hierarchy.

​write

​read

​readText / read_text

​downloadDir / download_dir

​Round-trip example

​Path rules

​Errors