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 file to a destination inside the box. Relative destinations resolve against the box’s current directory, /workspace/home by default.

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

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

All files in a call are sent in a single request. Each file can be up to 100 MB, and a request up to about 1 GB in total. Each path must be a file, not a directory.

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: "script.js",  content: `console.log("hello from box")`,})

box.files.write(    path="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("output.json")console.log(JSON.parse(content))

import jsoncontent = box.files.read("output.json")print(json.loads(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 })

# First 512 byteshead = box.files.read("train.csv", length=512)# 1 KB starting at byte 4096chunk = 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

info = box.files.stat("report.csv")print(info.type)     # "file" | "directory" | "symlink" | "other"print(info.size)     # 1024print(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 })

target = 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 })

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")

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 })

box.files.remove("scratch.tmp")box.files.remove("build", recursive=True)

List files#

List the entries in a directory. Each entry includes the name, path, size, whether it is a directory, and the last modified timestamp.

const files = await box.files.list()console.log(files)// [//   { name: "report.csv", path: "/workspace/home/report.csv", size: 1024, is_dir: false, mod_time: "2026-02-23T..." },//   { name: "output", path: "/workspace/home/output", size: 4096, is_dir: true, mod_time: "2026-02-23T..." },// ]

files = box.files.list()print(files)# [#   FileEntry(name="report.csv", path="/workspace/home/report.csv", size=1024, is_dir=False, mod_time="2026-02-23T..."),#   FileEntry(name="output", path="/workspace/home/output", size=4096, is_dir=True, mod_time="2026-02-23T..."),# ]

Download files#

Pull files from a box directory back to your local machine. Pass a folder to download that directory into ./<folder name>, or call with no arguments to download the current directory (./workspace for the default /workspace/home).

Downloads are not recursive: only the files directly inside the directory are downloaded, and subdirectories are skipped. folder must be a directory, not a single file. To fetch one file, use files.read.

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

box.files.download()box.files.download(folder="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: "resume.pdf" },])const run = await box.agent.run({  prompt: "Read 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()

import osfrom pydantic import BaseModelfrom upstash_box import Box, Agentclass Candidate(BaseModel):    name: str    email: str    skills: list[str]box = Box.create(    runtime="node",    agent={"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]},)box.files.upload([    {"path": "./resumes/candidate.pdf", "destination": "resume.pdf"},])run = box.agent.run(    prompt="Read resume.pdf. Extract the candidate's name, email, and skills.",    response_schema=Candidate,)print(run.result)# Candidate(name="Jane Doe", email="jane@example.com", skills=["TypeScript", "PostgreSQL"])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: "https://github.com/your-org/your-api" })await box.cd("your-api")await box.files.write({  path: ".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",})

import osfrom upstash_box import Box, Agentbox = Box.create(    runtime="node",    agent={"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]},    git={"token": os.environ["GITHUB_TOKEN"]},)box.git.clone(repo="https://github.com/your-org/your-api")box.cd("your-api")box.files.write(    path=".env.test",    content="DATABASE_URL=postgres://localhost:5432/test\nREDIS_URL=redis://localhost:6379",)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. Each box writes to its own output folder, so the downloads land in separate local folders.

import { Agent, Box } from "@upstash/box"const tasks = [  { out: "summary", prompt: "Analyze data.csv and write a summary to summary/summary.md" },  { out: "charts", prompt: "Generate charts from data.csv and save PNGs to charts/" },  { out: "anomalies", prompt: "Find anomalies in data.csv and write a report to anomalies/report.md" },]await Promise.all(  tasks.map(async ({ out, 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: "data.csv" },    ])    await box.agent.run({ prompt })    // Downloads the files in the box's `out` folder into ./<out>    await box.files.download({ folder: out })    await box.delete()  }))

import asyncioimport osfrom upstash_box import AsyncBox, Agenttasks = [    ("summary", "Analyze data.csv and write a summary to summary/summary.md"),    ("charts", "Generate charts from data.csv and save PNGs to charts/"),    ("anomalies", "Find anomalies in data.csv and write a report to anomalies/report.md"),]async def run_one(out: str, prompt: str) -> None:    box = await AsyncBox.create(        runtime="node",        agent={"harness": Agent.CLAUDE_CODE, "model": "anthropic/claude-opus-4-6", "api_key": os.environ["ANTHROPIC_API_KEY"]},    )    await box.files.upload([{"path": "./data.csv", "destination": "data.csv"}])    await box.agent.run(prompt=prompt)    # Downloads the files in the box's `out` folder into ./<out>    await box.files.download(folder=out)    await box.delete()async def main() -> None:    # fan out across boxes in parallel    await asyncio.gather(*(run_one(out, prompt) for out, prompt in tasks))asyncio.run(main())