Ephemeral Box - Upstash Documentation

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#

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

from upstash_box import EphemeralBoxbox = EphemeralBox.create(    runtime="node",  # "node" | "python" | "golang" | "ruby" | "rust"    ttl=3600,        # seconds, max 259200 (3 days), default 259200    name="my-ephemeral-worker",            # optional    network_policy={"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#

Instant creation — no polling loop; the response is the ready box
Auto-expiry — boxes are automatically deleted after TTL; expiresAt tracks this
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
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
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#

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

run = box.exec.command("echo hello")print(run.result)  # "hello"

Execute inline code#

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

result = box.exec.code(    code="import json; print(json.dumps({'sum': 1 + 2}))",    lang="python",)

File operations#

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

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

Clean up early#

Otherwise the box auto-deletes at expiresAt.

await box.delete()

box.delete()

Exported types#

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