Filesystem - Upstash Documentation

Every box has its own isolated filesystem. Upload, write, read, list, and download files inside the box.

API#

Upload files#

Push local files into the box. Each entry maps a local path to a destination inside the box workspace.

await box.files.upload([  { path: "./data/report.csv", destination: "/work/report.csv" },  { path: "./config.json", destination: "/work/config.json" },])

You can upload multiple files in a single call. All uploads run in parallel.

Write files#

Create or overwrite a file directly from a string. Useful when you want to inject configuration, scripts, or generated content without a local file.

await box.files.write({  path: "/work/script.js",  content: `console.log("hello from box")`,})

Read files#

Read the contents of a file as a string.

const content = await box.files.read("/work/output.json")console.log(JSON.parse(content))

Read part of a file#

Pass length to read a bounded byte range instead of the whole file, starting at offset (default 0). This keeps a large log or dataset out of memory when you only need a slice of it. The server rejects a length above 8 MiB.

// First 512 bytesconst head = await box.files.read("train.csv", { length: 512 })// 1 KB starting at byte 4096const chunk = await box.files.read("train.csv", { offset: 4096, length: 1024 })

Inspect a path#

Get metadata for a single path without reading it: the entry type, size, last modified time, inode, and an opaque version token.

Use version for optimistic concurrency. Read it before a slow operation, then compare it afterwards to detect whether the file changed underneath you. Compare it for equality only, and do not parse it.

const info = await box.files.stat("report.csv")console.log(info.type)     // "file" | "directory" | "symlink" | "other"console.log(info.size)     // 1024console.log(info.version)  // opaque freshness token

By default a symlink is reported as "symlink". Pass follow to resolve it and describe the target instead.

const target = await box.files.stat("latest", { follow: true })

Create directories#

Create a directory. Pass parents to create missing parent directories, the way mkdir -p does, and to succeed when the directory already exists.

await box.files.mkdir("output/reports", { parents: true })

Move and rename#

Move a path to a new location, which is also how you rename it.

await box.files.rename("draft.md", "final.md")

Delete files#

Remove a file. Removing a directory requires recursive, so a directory is never deleted by accident.

await box.files.remove("scratch.tmp")await box.files.remove("build", { recursive: true })

List files#

List the entries in a directory. Each entry includes the path, size, type, and last modified timestamp.

const files = await box.files.list("/work")console.log(files)// [//   { path: "/work/report.csv", size: 1024, type: "file", modifiedAt: "2026-02-23T..." },//   { path: "/work/output", size: 4096, type: "directory", modifiedAt: "2026-02-23T..." },// ]

Download files#

Pull files from the box back to your local machine. Call with no arguments to download the entire workspace, or pass a folder to download a specific file or directory.

await box.files.download()await box.files.download({ folder: "/work/output" })

Examples#

Feed data to an agent#

Upload input files, run the agent, then read back the structured result.

import { Agent, Box } from "@upstash/box"import { z } from "zod"const box = await Box.create({  runtime: "node",  agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },})await box.files.upload([  { path: "./resumes/candidate.pdf", destination: "/work/resume.pdf" },])const run = await box.agent.run({  prompt: "Read /work/resume.pdf. Extract the candidate's name, email, and skills.",  responseSchema: z.object({    name: z.string(),    email: z.string(),    skills: z.array(z.string()),  }),})console.log(run.result)// { name: "Jane Doe", email: "jane@example.com", skills: ["TypeScript", "PostgreSQL"] }await box.delete()

Inject config before a run#

Write environment-specific configuration into the box, then let the agent use it.

import { Agent, Box } from "@upstash/box"const box = await Box.create({  runtime: "node",  agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },  git: { token: process.env.GITHUB_TOKEN },})await box.git.clone({ repo: "github.com/your-org/your-api" })await box.files.write({  path: "/work/your-api/.env.test",  content: `DATABASE_URL=postgres://localhost:5432/test\nREDIS_URL=redis://localhost:6379`,})await box.agent.run({  prompt: "Run the integration test suite using the config in .env.test",})

Collect outputs from parallel boxes#

Fan out work across multiple boxes, then download each result locally.

import { Agent, Box } from "@upstash/box"const prompts = [  "Analyze /work/data.csv and write a summary to /work/summary.md",  "Generate charts from /work/data.csv and save PNGs to /work/charts/",  "Find anomalies in /work/data.csv and write a report to /work/anomalies.md",]const results = await Promise.all(  prompts.map(async (prompt) => {    const box = await Box.create({      runtime: "node",      agent: { harness: Agent.ClaudeCode, model: "anthropic/claude-opus-4-6", apiKey: process.env.ANTHROPIC_API_KEY },    })    await box.files.upload([      { path: "./data.csv", destination: "/work/data.csv" },    ])    await box.agent.run({ prompt })    await box.files.download({ folder: "/work" })    await box.delete()  }))