Upstash Box
Run durable or ephemeral cloud containers on Upstash Box. Size presets, native network policies, filesystem snapshots, and bearer-protected previews.
upstash() runs each sandbox on Upstash Box, a cloud container that keeps its files between sessions.
Install
npm install @opencoredev/sandbox-sdk @upstash/boxpnpm add @opencoredev/sandbox-sdk @upstash/boxyarn add @opencoredev/sandbox-sdk @upstash/boxbun add @opencoredev/sandbox-sdk @upstash/boxThe adapter needs @upstash/box 0.7.9 or later within 0.7, on Node.js 22 or Bun. Set UPSTASH_BOX_API_KEY on your server, and keep it out of browser bundles.
Quickstart
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(upstash());
const result = await box.run("uname -a");
console.log(result.stdout);
This creates a small box with Upstash’s default runtime. await using deletes it when the block ends.
What it supports
| Feature | Support | Notes |
|---|---|---|
| Commands and streaming | Yes | Live output when you iterate |
| Files | Yes | |
| Background processes | Yes | |
| Preview URLs | Yes | Bearer header by default, or public |
| Pause and resume | Partial | Durable boxes only; running processes end |
| Snapshots | Yes | Full file system. expiresInMs fails with unsupported |
| Machine size | Partial | Presets only |
| Network policy | Yes | "none" or a host allow list |
Hard lifetime (timeoutMs) |
No | Ephemeral boxes have a TTL backstop |
Idle timeout (idleTimeoutMs) |
No | Upstash pauses idle durable boxes itself |
| Keys | Best-effort | Read from metadata inside each box |
| Terminal | No |
The capability matrix compares these with every other provider.
Run commands
Await box.run for the result, or iterate it to stream output as it arrives.
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(upstash());
const result = await box.run("ls -la", { cwd: "/workspace", timeoutMs: 30_000 });
console.log(result.exitCode, result.stdout);
for await (const chunk of box.run("for i in 1 2 3; do echo $i; sleep 1; done")) {
process.stdout.write(chunk.text);
}
A command timeout kills the command’s process tree.
Files
Relative paths resolve against /workspace.
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(upstash());
await box.files.write("notes/todo.txt", "ship the docs\n");
console.log(await box.files.read("notes/todo.txt"));
console.log(await box.files.list("notes"));
await box.files.write("secrets/token", "abc123", { mode: 0o600 });
Upstash’s file API has no mode, so for { mode } the SDK runs chmod right after the write.
Background processes and previews
No ports to declare. Previews need a bearer token by default, so send preview.headers with every request. Pass upstash({ public: true }) for public previews.
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(upstash());
await box.start("python3 -m http.server 3000", { name: "web", ready: { port: 3000 } });
const preview = await box.preview(3000, { waitMs: 10_000 });
const response = await fetch(preview.url, { headers: preview.headers });
console.log(response.status);
Reuse one provider instance to keep preview credentials stable. Another instance, or a native getPublicURL() call, rotates them.
Pause, resume, and snapshots
On a durable box, pause() and resume() keep files but end running processes. The SDK marks them failed with exit code 137 on resume. snapshot() captures the full file system.
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(upstash(), { key: "user:123" });
await box.pause();
await box.resume();
const { id } = await box.snapshot();
await using copy = await createSandbox(upstash(), { from: id });
Snapshots outlive their source box; delete them through the native SDK. They have no expiry, so snapshot({ expiresInMs }) fails with unsupported. expiresInMs: 0 is accepted.
A durable box pauses itself when idle. Pass keepAlive: true to keep it running instead.
An ephemeral box is ready as soon as it’s created, can’t pause, and is deleted after its TTL. The provider drops the pause capability, so pause() isn’t on its type.
import { createSandbox, hasCapability } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(upstash({ ephemeral: true, ttlSeconds: 1800 }));
if (hasCapability(box, "pause")) await box.pause();
Size, network, and lifetime
| Preset | vCPUs | Memory | Storage |
|---|---|---|---|
small |
2 | 4 GB | 5 GB |
medium |
4 | 8 GB | 10 GB |
large |
8 | 16 GB | 20 GB |
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(upstash(), {
size: "medium",
network: { allow: ["registry.npmjs.org"] },
});
To give the box credentials it can use but never read, set attachHeaders. Upstash’s egress proxy adds the headers to matching outbound HTTPS requests, so the values stay out of the box’s env and files. It works in both modes.
import { createSandbox } from "@opencoredev/sandbox-sdk";
import { upstash } from "@opencoredev/sandbox-sdk/upstash";
await using box = await createSandbox(
upstash({
attachHeaders: { "api.stripe.com": { Authorization: `Bearer ${process.env.STRIPE_KEY}` } },
}),
);
await box.run("curl -s https://api.stripe.com/v1/balance");
Exact sizes fail with unsupported. Allow-list entries are plain DNS host names, and an empty list blocks all outbound traffic. idleTimeoutMs and timeoutMs fail with unsupported. An ephemeral box’s ttlSeconds is a backstop for leaks, not a deadline: Upstash removes it some time after it expires.
Configuration
| Option | Type | Default | Env var |
|---|---|---|---|
apiKey |
string |
UPSTASH_BOX_API_KEY |
|
baseUrl |
string |
https://us-east-1.box.upstash.com |
UPSTASH_BOX_BASE_URL |
runtime |
Runtime, such as "node" |
Upstash’s default | |
requestTimeoutMs |
number |
600_000 |
|
enableTelemetry |
boolean |
true |
UPSTASH_DISABLE_TELEMETRY |
public |
boolean |
false |
|
ephemeral |
boolean |
false |
|
ttlSeconds |
number |
3600, at most 259200 |
|
keepAlive |
boolean |
false |
|
browser |
boolean |
false |
|
attachHeaders |
Record<string, Record<string, string>> |
ttlSeconds applies only with ephemeral: true, and keepAlive and browser only without it. browser: true provisions a headless Chromium you reach through box.native.browser. requestTimeoutMs bounds native requests, not the box’s lifetime. The default runtime needs passwordless sudo -n to make /workspace writable. box.native is the Upstash SDK’s Box object.
Limitations
- Keys are best-effort, and listing may wake paused boxes.
- No custom idle deadlines, hard lifetimes, or exact sizes.
- No terminal through Sandbox SDK. The native SDK has live sessions.
- Losing a foreground session connection ends its command.
How it works
- Keys and labels live in
/tmp/.sandbox-sdk/upstash.jsoninside the box. One nativesandbox-sdklabel marks SDK boxes, so labels don’t use Upstash’s limited label slots. - A durable mode provider and an ephemeral one each see only their own boxes.
- Binary files move in 4 MiB chunks because native writes cap at 10 MiB. Large writes are staged and swapped in once complete.