Upstash Box

Upstash provides durable cloud containers with files, processes, public or authenticated URLs, snapshots, and native agents.

Installation

Terminal

bun add @opencoredev/sandbox-sdk ai zod @upstash/box

Authentication

Set UPSTASH_BOX_API_KEY, or pass apiKey to upstash().

Run a command

upstash.ts

import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";

await using sandbox = await createSandbox({ provider: upstash() });
const result = await sandbox.run("node --version");
console.log(result.stdout);

Run an AI SDK agent

This provider works with AI SDK ToolLoopAgent through the normalized sandbox session. Pass the language model from your existing AI SDK provider or AI Gateway setup.

sandbox-agent.ts

import { ToolLoopAgent, type LanguageModel } from "ai";import { createSandbox } from "@opencoredev/sandbox-sdk";import {  createSandboxToolApproval,  createSandboxTools,  toAISandboxSession,} from "@opencoredev/sandbox-sdk/ai";import { upstash } from "@opencoredev/sandbox-sdk/upstash";export async function runSandboxAgent(model: LanguageModel) {  await using sandbox = await createSandbox({    provider: upstash({ runtime: "node" }),  });  const aiSandbox = toAISandboxSession(sandbox);  const agent = new ToolLoopAgent({    model,    instructions: `Work only in the provided sandbox.\n\n${aiSandbox.description}`,    tools: createSandboxTools(),    toolApproval: createSandboxToolApproval(),  });  return await agent.generate({    prompt: "Inspect the repository, run its tests, and summarize the result.",    experimental_sandbox: aiSandbox,  });}

See the AI SDK guide for approval flows, direct session access, and HarnessAgent alternatives.

Files and processes

workspace.ts

await sandbox.files.write("index.mjs", `console.log("ready")`);
const process = await sandbox.processes.start("node index.mjs");

for await (const event of process.output()) {
  console.log(event.data);
}

Upstash supports persistent files and background processes with combined output. Normalized stdin and cancellation are not available in @upstash/box 0.5.

Ports are public by default. Pass public: false to return bearer-token URLs and keep the token inside preview.request(). Creating and deleting snapshots is normalized; restoring one creates a new Box and remains on sandbox.raw.

snapshot.ts

const snapshot = await sandbox.snapshots.create({ name: "prepared" });
await sandbox.snapshots.delete(snapshot);

Options

Option	Type	Default	Behavior
`apiKey`	`string`	`UPSTASH_BOX_API_KEY`	Authenticates Box requests.
`runtime`	`string`	`node`	Selects the Box runtime.
`size`	`small \| medium \| large`	`small`	Selects CPU and memory.
`name`	`string`	Generated	Sets a human-readable name.
`keepAlive`	`boolean`	`false`	Keeps compute active while idle.
`public`	`boolean`	`true`	Controls public or bearer-token URLs.
`networkPolicy`	`NetworkPolicy`	`allow-all`	Controls outbound network access.

Behavior

Files and sandbox identity persist when managed sessions pause and resume.
sandbox.stop() permanently deletes the Box.
Commands expose one combined output stream.
Native agents, Git, skills, MCP, schedules, forks, images, and network controls pass through upstash() and remain typed on sandbox.raw.