Ephemeral Box

EphemeralBox is a lightweight, short-lived sandbox that provides exec, file, schedule, and snapshot operations. It’s designed for quick, disposable compute tasks where a full Box (with agent, git, public URLs, etc.) is unnecessary.

---

Creation

box.ts

import { EphemeralBox } from "@upstash/box"

const box = await EphemeralBox.create({
  runtime: "node",  // "node" | "python" | "golang" | "ruby" | "rust"
  ttl: 3600,        // seconds, max 259200 (3 days), default 259200
  name: "my-ephemeral-worker",          // optional
  networkPolicy: { mode: "allow-all" }, // optional
})

Key difference from Box.create(): Ephemeral boxes are ready immediately — no polling. The API returns with status: "idle" and the box is usable right away.

The request sends { ephemeral: true, ttl?, runtime?, name?, labels?, size?, env_vars?, attach_headers?, network_policy? } to POST /v2/box.

---

Available API

Feature	Box	EphemeralBox
exec.command()	Yes	Yes
exec.code()	Yes	Yes
exec.stream()	Yes	Yes
exec.streamCode()	Yes	Yes
exec.session()	Yes	Yes
files.read/write/list/upload/download	Yes	Yes
files.stat/mkdir/rename/remove	Yes	Yes
schedule.exec/list/get/update/pause/resume/delete	Yes	Yes
schedule.agent()	Yes	No (no agent)
cd() / cwd	Yes	Yes
getStatus()	Yes	Yes
delete()	Yes	Yes
networkPolicy (read)	Yes	Yes
updateNetworkPolicy()	Yes	No
expiresAt	No	Yes
agent.run() / agent.stream()	Yes	No
git.*	Yes	No
getPublicURL() / listPublicURLs() / deletePublicURL()	Yes	No
snapshot() / listSnapshots() / deleteSnapshot() / fromSnapshot()	Yes	Yes
pause() / resume()	Yes	No
configureModel()	Yes	No
logs() / listRuns()	Yes	No

---

Properties

• id — box identifier (e.g. "sweet-shark-26021")
• expiresAt — Unix timestamp (seconds) when the box auto-deletes

---

How it differs from Box

1. Instant creation — no polling loop; the response is the ready box
2. Auto-expiry — boxes are automatically deleted after TTL; expiresAt tracks this
3. Reduced surface — exec, files, schedules, and snapshots; no agent, git, public URLs, or pause()/resume(). An idle ephemeral box can still be auto-paused before its TTL (after 1 hour on the free plan, 6 hours on paid plans), and new exec or file calls resume it
4. Simpler config — EphemeralBoxConfig has apiKey, baseUrl, name, labels, runtime, size, ttl, env, attachHeaders, networkPolicy, timeout, debug, and enableTelemetry (TypeScript only). There is no agent, git, skills, mcpServers, keepAlive, or initCommand
5. Composition over inheritance — EphemeralBox wraps an internal Box and exposes only the relevant subset, so agent/git/etc. are not accessible even at runtime

---

Examples

Run a shell command

box.ts

const run = await box.exec.command("echo hello")
console.log(run.result) // "hello"

Execute inline code

box.ts

const result = await box.exec.code({
  code: 'console.log(JSON.stringify({ sum: 1 + 2 }))',
  lang: "js",
})

File operations

box.ts

await box.files.write({ path: "data.json", content: '{"key":"value"}' })
const content = await box.files.read("data.json")

Clean up early

Otherwise the box auto-deletes at expiresAt.

box.ts

await box.delete()

---

Exported types

• EphemeralBox — the class
• EphemeralBoxConfig — config for EphemeralBox.create()
• EphemeralBoxData — extends BoxData with ephemeral: boolean and expires_at: number