Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt

Use this file to discover all available pages before exploring further.

Read and write files inside a sandbox via sandbox.files. Operations route directly to the data plane (boxd-{id}.sandbox.superserve.ai) using a per-sandbox access token. The SDK manages the token transparently, including rotation after resume().

​
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]))
Parameters:
OptionTypeDescription
pathstring / strAbsolute destination path.
contentFileInput / str | bytesFile contents. See accepted types below.
timeoutMs / timeoutnumber / floatOptional request timeout.
signalAbortSignalTypeScript only - abort the request.
Accepted content types: 
type FileInput = string | Uint8Array | ArrayBuffer | Blob
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")

​
readText / read_text

Read a file and decode as UTF-8. 
const text: string = await sandbox.files.readText("/app/config.json")

​
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

​
Path rules

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

​
Errors

Commonly raised:
  • NotFoundError - file does not exist (on read)
  • 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.