Upstash Box

https://upstash.com/docs/box/
Admin
Upstash Box provides sandboxed cloud containers for running AI agents, executing shell commands,...
Tokens:102,418
Snippets:948
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run the development server

Source: https://upstash.com/docs/box/guides/copilotkit

Starts the Next.js development server. After running, open http://localhost:3000 and try the example prompts.

```bash
npm run dev
```

--------------------------------

### Create a Box with initCommand (TypeScript)

Source: https://upstash.com/docs/box/overall/quickstart

Create a box that runs a startup script each time it starts. The example starts a simple HTTP server on port 3000 using Node's built-in http module.

```typescript
const box = await Box.create({
  runtime: "node",
  initCommand: `node -e 'require("http").createServer((_, res) => res.end("Hello from Box!")).listen(3000)'`,
})
```

--------------------------------

### Install dependencies before a run (Python)

Source: https://upstash.com/docs/box/overall/shell

Python equivalent of the TypeScript example. Sets up a Node.js environment, clones a repository, installs dependencies, and runs an agent to fix failing tests. Requires ANTHROPIC_API_KEY and GITHUB_TOKEN environment variables.

```python
import os
from upstash_box import Box, Agent
box = 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="github.com/your-org/your-api")
box.exec.command("npm install")
box.agent.run(prompt="Run the test suite and fix any failing tests")
```

--------------------------------

### Example output from setup.py

Source: https://upstash.com/docs/box/guides/browser-use

Example output after the box id. Stories and scores will vary.

```markdown
## Top 3 AI Stories from Hacker News
1. **AI companies leak data to advertisers [pdf]** - 179 points
   - Link: https://jorgegarciaherrero.com/wp-content/interactivos/20260916-Prompt-like-a-butterfly-sting-like-a-tracker-(clean).pdf
   - Summary: The paper analyzes privacy practices of conversational AI services, finding that 6 out of 9 web services and 3 out of 8 Android apps leak conversation data to third parties. This includes sensitive information such as URLs, titles, prompts, and screenshots being shared alongside persistent user identifiers.
2. **Jeeves. Reasoning improves Jev-like decision models** - 54 points
   - Link: https://github.com/PostHog/jeeves
3. **Nvidia wants to put a watchdog chip next to every AI agent** - 197 points
   - Link: https://www.cnbc.com/2026/09/28/nvidia-releases.html
```

--------------------------------

### Configure lifecycle with snapshot: "after-setup"

Source: https://upstash.com/docs/box/guides/tanstack-setup

Configures the sandbox lifecycle to reuse a thread, snapshot after setup, keep the snapshot for 24 hours, and not destroy on completion. This skips the cold start by resuming from a snapshot.

```javascript
lifecycle: {
  reuse: "thread",
  snapshot: "after-setup",
  snapshotMaxAge: "24h",
  destroyOnComplete: false,
}
```

--------------------------------

### Run Eve dev server

Source: https://upstash.com/docs/box/guides/eve-setup

Starts the Eve development server. After setup, Eve's built-in tools (bash, read_file, write_file, glob, grep) run inside the sandbox.

```bash
npx eve dev
```

--------------------------------

### Install Hermes on Upstash Box

Source: https://upstash.com/docs/box/guides/hermes-setup

Downloads and installs Hermes inside the box. Follow the CLI prompts to complete the setup.

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

--------------------------------

### Install a custom agent CLI with sudo -n in setup

Source: https://upstash.com/docs/box/guides/tanstack-setup

Installs a custom agent CLI in the box's setup step using `sudo -n` because the box runs as non-root `boxuser` and `/usr/local/lib/node_modules` is root-owned; a plain `npm install -g` fails with `EACCES`. Running the CLI in the same step turns a silent broken install into a loud bootstrap failure.

```typescript
setup: ["sudo -n npm install -g @some/agent-cli --include=optional && some-agent --version"],
```

--------------------------------

### Install langchain-upstash-box

Source: https://upstash.com/docs/box/guides/langchain-deep-agents

Install the package using pip or uv.

```bash
pip install langchain-upstash-box
```

```bash
uv add langchain-upstash-box
```

--------------------------------

### Install @upstash/box with bun

Source: https://upstash.com/docs/box/overall/quickstart

Install the TypeScript/JavaScript SDK using bun.

```bash
bun install @upstash/box
```

--------------------------------

### setup.py - Create box, install Browser Use, run agent, and schedule daily

Source: https://upstash.com/docs/box/guides/browser-use

This script runs on your machine. It creates a box with a browser, installs Browser Use, runs the agent once, and schedules it.

```python
import os
from upstash_box import Box

box = Box.create(
    runtime="python",
    browser=True,
    env={"ANTHROPIC_API_KEY": os.environ["ANTHROPIC_API_KEY"]},
)
print(box.id)

def run(command):
    result = box.exec.command(command)
    if result.status != "completed":
        raise RuntimeError(result.result)

# Install Browser Use and copy the agent in
run("pip install browser-use")
box.files.write(path="agent.py", content=open("agent.py").read())

# Run it once and print the report
run("python3 agent.py")
for file in box.files.list("reports"):
    print(box.files.read(f"reports/{file.name}"))

# Run it every day at 08:00 UTC
box.schedule.exec(
    cron="0 8 * * *",
    command=["python3", "/workspace/home/agent.py"],
)
```

--------------------------------

### Install dependencies

Source: https://upstash.com/docs/box/guides/claude-managed-agents

Install @upstash/box, @anthropic-ai/sdk, and tsx.

```bash
npm install @upstash/box @anthropic-ai/sdk tsx
```

--------------------------------

### Install Pi and the extension

Source: https://upstash.com/docs/box/guides/pi-setup

Install the Pi coding agent globally and add the Upstash Box extension.

```bash
npm install -g @earendil-works/pi-coding-agentpi install npm:@upstash/box-pi
```

--------------------------------

### Install dependencies

Source: https://upstash.com/docs/box/guides/code-review-agent

Install the required Upstash Box and Zod packages.

```bash
npm install @upstash/box zod
```

--------------------------------

### Run setup.py

Source: https://upstash.com/docs/box/guides/browser-use

Executes the setup script to create the box and schedule the agent.

```bash
python setup.py
```

--------------------------------

### Run setup script

Source: https://upstash.com/docs/box/guides/claude-managed-agents

Executes setup.ts with environment variables from .env.

```bash
npx tsx --env-file=.env setup.ts
```

--------------------------------

### Multi-port application (Python)

Source: https://upstash.com/docs/box/overall/preview

Creates a Box with Node runtime, writes frontend and API files, installs Express, starts both services, and creates public URLs for ports 3000 and 8080. Outputs both URLs.

```python
from upstash_box import Box
box = Box.create(runtime="node")
# Start frontend on port 3000
box.files.write(
    path="/work/frontend.js",
    content="""const express = require('express')
const app = express()
app.get('/', (req, res) => res.send('Frontend'))
app.listen(3000)
  """,
)
# Start API on port 8080
box.files.write(
    path="/work/api.js",
    content="""const express = require('express')
const app = express()
app.get('/api/status', (req, res) => res.json({ status: 'ok' }))
app.listen(8080)
  """,
)
box.exec.command("npm install express")
box.exec.command("node /work/frontend.js & node /work/api.js &")
# Create a public URL for each service
frontend_public_url = box.get_public_url(3000)
api_public_url = box.get_public_url(8080)
print(f"Frontend: {frontend_public_url.url}")
print(f"API: {api_public_url.url}")
```

--------------------------------

### Configure and Start Gateway

Source: https://upstash.com/docs/box/guides/openclaw-setup

Set the gateway to bind to the LAN interface and start the process in the background.

```bash
openclaw config set gateway.bind lannohup openclaw gateway > gateway.log 2>&1 &
```

--------------------------------

### Create, list, and get a box (Python)

Source: https://upstash.com/docs/box/overall/how-it-works

Python equivalent of the TypeScript example: create a new box, list existing boxes, and get a box by ID later. Useful for dashboards, background workers, and apps that persist a box ID between requests.

```python
box = Box.create(runtime="node")
boxes = Box.list()
# 👇 later, or in another process
same_box = Box.get(box.id)
```

--------------------------------

### Run OpenClaw Onboarding

Source: https://upstash.com/docs/box/guides/openclaw-setup

Start the interactive onboarding wizard to configure provider selection, authentication, and gateway settings.

```bash
openclaw onboard --install-daemon
```

--------------------------------

### Reusable base environments (TypeScript)

Source: https://upstash.com/docs/box/overall/snapshots

Installs dependencies once, snapshots the environment, then spawns boxes from the snapshot to skip setup time. Uses @upstash/box and deletes the base box after snapshotting.

```typescript
import { Agent, Box } from "@upstash/box"
const base = await Box.create({ runtime: "node" })
await base.exec.command("npm install -g typescript eslint prettier")
const baseSnap = await base.snapshot({ name: "node-toolchain" })
await base.delete()
const boxes = await Promise.all(
  tasks.map(async (task) => {
    const box = await Box.fromSnapshot(baseSnap.id)
    await box.agent.run({ prompt: task })
    return box
  })
)
```

--------------------------------

### Share a secure public URL (Python)

Source: https://upstash.com/docs/box/overall/preview

Creates a Box with Python runtime, writes a Flask app, installs Flask and starts the server, then creates a public URL with basic authentication. Outputs the URL, username, and password to share with team members.

```python
import httpx
from upstash_box import Box
box = Box.create(runtime="python")
# Set up a Flask app
box.files.write(
    path="/work/app.py",
    content="""from flask import Flask
app = Flask(__name__)
@app.route('/')
def home():
    return 'Internal Dashboard'
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
  """,
)
box.exec.command("pip install flask && python /work/app.py &")
# Create authenticated public URL
public_url = box.get_public_url(8080, basic_auth=True)
print(f"Public URL: {public_url.url}")
print(f"Username: {public_url.username}")
print(f"Password: {public_url.password}")
# Share these credentials with your team
```

--------------------------------

### Install @upstash/box with npm

Source: https://upstash.com/docs/box/overall/quickstart

Install the TypeScript/JavaScript SDK using npm.

```bash
npm install @upstash/box
```

--------------------------------

### Answer a prompt from an installer (Python)

Source: https://upstash.com/docs/box/overall/live-sessions

Collects output, waits for the prompt 'Select a framework', then sends a newline to accept the default.

```python
import time
out = ""
def collect(data: bytes) -> None:
    global out
    out += data.decode()
session = box.exec.session(
    cmd="npm create vite@latest my-app",
    tty=True,
    on_stdout=collect,
)
deadline = time.monotonic() + 30
while "Select a framework" not in out and time.monotonic() < deadline:
    time.sleep(0.1)
session.write("\n")  # accept the default
session.wait()
```

--------------------------------

### Install OpenClaw CLI

Source: https://upstash.com/docs/box/guides/openclaw-setup

Install the OpenClaw CLI globally inside the box using npm.

```bash
sudo npm install -g openclaw
```

--------------------------------

### Install @upstash/box with yarn

Source: https://upstash.com/docs/box/overall/quickstart

Install the TypeScript/JavaScript SDK using yarn.

```bash
yarn add @upstash/box
```

--------------------------------

### Install CopilotKit and Upstash Box packages

Source: https://upstash.com/docs/box/guides/copilotkit

Install the tested package versions for CopilotKit, Upstash Box, and AG-UI client. If upgrading CopilotKit, match @ag-ui/client to its dependency version.

```bash
npm install @upstash/box@0.7.7 @copilotkit/react-core@1.75.1 @copilotkit/runtime@1.75.1 @ag-ui/client@0.0.59 rxjs@7.8.1
```

--------------------------------

### Install system tools with apt (Python)

Source: https://upstash.com/docs/box/overall/shell

Installs additional system tools using Debian's package manager inside the box.

```python
box.exec.command("sudo apt-get install <package>")
```

--------------------------------

### Install @upstash/box with pnpm

Source: https://upstash.com/docs/box/overall/quickstart

Install the TypeScript/JavaScript SDK using pnpm.

```bash
pnpm add @upstash/box
```

--------------------------------

### Start a session with argv (Python)

Source: https://upstash.com/docs/box/overall/live-sessions

Starts a session with an argv array, avoiding a shell for safety. Output arrives via on_stdout and on_stderr callbacks. wait() blocks until exit and returns the exit code.

```python
chunks = []
session = box.exec.session(
    argv=["npm", "test"],
    on_stdout=chunks.append,
    on_stderr=lambda data: print(data.decode(), end=""),
)
print(session.pid)        # in-box process id
code = session.wait()
print(code)               # exit code
```

--------------------------------

### Install Skills

Source: https://upstash.com/docs/box/guides/remote-development

Command to install the Upstash skills package.

```bash
npx skills add upstash/skills
```

--------------------------------

### Install @upstash/box, playwright-core, and zod

Source: https://upstash.com/docs/box/guides/web-scraping-playwright

Install the required packages. playwright-core is sufficient because you connect to the box's managed Chromium over CDP instead of launching a local browser, so no browser binaries are downloaded on your side.

```bash
npm install @upstash/box playwright-core zod
```

--------------------------------

### Install dependencies before a run (TypeScript)

Source: https://upstash.com/docs/box/overall/shell

Sets up a Node.js environment with Upstash Box, clones a repository, installs dependencies, and runs an agent to fix failing tests. Requires ANTHROPIC_API_KEY and GITHUB_TOKEN environment variables.

```typescript
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: "github.com/your-org/your-api" })
await box.exec.command("npm install")
await box.agent.run({
  prompt: "Run the test suite and fix any failing tests",
})
```

--------------------------------

### Install system tools with apt (TypeScript)

Source: https://upstash.com/docs/box/overall/shell

Installs additional system tools using Debian's package manager inside the box.

```typescript
await box.exec.command("sudo apt-get install <package>")
```

--------------------------------

### Install TanStack AI packages

Source: https://upstash.com/docs/box/guides/tanstack-setup

Install the core TanStack AI packages, sandbox utilities, the Upstash Box provider, and the Claude Code harness adapter.

```bash
npm install @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-upstash-box @tanstack/ai-claude-code
```

--------------------------------

### Start an agent with the Upstash Box plugin

Source: https://upstash.com/docs/box/guides/herdr-setup

Starts an agent in a new box from the focused pane's Git worktree. The command only confirms in the terminal; the new pane opens in Herdr.

```bash
herdr plugin action invoke start-agent --plugin upstash.box
```

--------------------------------

### start

Source: https://upstash.com/docs/box/overall/browser/recordings

Starts capturing a recording for the box. One active recording per box. Stops when stop() is called, when maxDurationSeconds is reached (default and maximum 600 seconds), or automatically after 3 minutes with no on-screen activity.

```APIDOC
## start

### Description
Starts capturing a recording for the box. One active recording per box. Stops when stop() is called, when maxDurationSeconds is reached (default and maximum 600 seconds), or automatically after 3 minutes with no on-screen activity.

### Method
start

### Parameters
- **maxDurationSeconds** (number) - Optional - Maximum recording duration in seconds. Default and maximum is 600.

### Request Example
```typescript
const recording = await box.browser.recordings.start({
  maxDurationSeconds: 120,
})
```

### Response
Returns a recording handle with a `stop()` method.

### Response Example
```typescript
const saved = await recording.stop()
console.log(saved.durationMs, saved.playlistUrl)
console.log(saved.markers) // tab switches
```
```

--------------------------------

### Install dependencies for Upstash Box and OpenAI

Source: https://upstash.com/docs/box/guides/openai-agents-api

Installs the required packages: @upstash/box, openai, and tsx.

```bash
npm install @upstash/box openai tsx
```

--------------------------------

### SSH connect example with box ID

Source: https://upstash.com/docs/box/overall/shell

Example SSH command using a specific box ID. Use your Box API key as the password.

```bash
ssh current-wasp-05510@us-east-1.box.upstash.com
```

--------------------------------

### Install @upstash/agentkit-eve and @upstash/box

Source: https://upstash.com/docs/box/guides/eve-setup

Installs the Upstash Box sandbox provider and its optional peer dependency. @upstash/box version 0.7.1 or later is required.

```bash
npm install @upstash/agentkit-eve @upstash/box
```

--------------------------------

### Create, list, and get a box (TypeScript)

Source: https://upstash.com/docs/box/overall/how-it-works

Shows the core lifecycle entrypoints: create a new box, list existing boxes, and get a box by ID later. Useful for dashboards, background workers, and apps that persist a box ID between requests.

```typescript
const box = await Box.create({ runtime: "node" })
const boxes = await Box.list()
// 👇 later, or in another serverless function
const sameBox = await Box.get(box.id)
```

--------------------------------

### Bind start-agent to a keybinding

Source: https://upstash.com/docs/box/guides/herdr-setup

Example Herdr keybinding configuration to bind the start-agent command to prefix+shift+u.

```toml
[[keys.command]]
key = "prefix+shift+u"
command = "herdr plugin action invoke start-agent --plugin upstash.box"
```

--------------------------------

### Start Next.js dev server in background (Python)

Source: https://upstash.com/docs/box/guides/nextjs-setup

Starts the dev server in the background using nohup, so the command returns while Next.js runs on port 3000. Commands run from the box's home directory (/workspace/home).

```python
box.exec.command("cd my-next-app && nohup npm run dev > dev.log 2>&1 &")
```

--------------------------------

### Start a session with cmd (Python)

Source: https://upstash.com/docs/box/overall/live-sessions

Starts a session with a shell command string, running through bash -lc. Use for pipes, globs, or &&. Note that argv does not expand variables or treat ; as a separator.

```python
session = box.exec.session(cmd="cat *.log | grep ERROR")
```

--------------------------------

### Create a keep-alive box with init command in Python

Source: https://upstash.com/docs/box/overall/keep-alive

A keep-alive box can run an init command, a startup script that runs once each time the container starts. This example sets an init command to install dependencies and start the dev server.

```Python
box = Box.create(
    runtime="node",
    keep_alive=True,
    init_command="npm install && npm run dev",
)
```

--------------------------------

### Create a keep-alive box with init command in TypeScript

Source: https://upstash.com/docs/box/overall/keep-alive

A keep-alive box can run an init command, a startup script that runs once each time the container starts. This example sets an init command to install dependencies and start the dev server.

```TypeScript
const box = await Box.create({
  runtime: "node",
  keepAlive: true,
  initCommand: "npm install && npm run dev",
})
```

--------------------------------

### Hold a command open

Source: https://upstash.com/docs/box/overall/shell

Start a live session to interact with a command via stdin, terminal, or signals.

```APIDOC
## Hold a command open

### Description
Start a live session to interact with a command via stdin, terminal, or signals.

### Method
`box.exec.session({ argv })`

### Parameters
- **argv** (array of strings) - Required - The command and its arguments.

### Methods on session
- **write(data)** - Write data to the session's stdin.
- **endStdin()** - Signal end of input.
- **wait(timeout?)** - Wait for the session to finish.

### Example (TypeScript)
```typescript
const session = await box.exec.session({ argv: ["sort"] })
session.write("banana\napple\n")
session.endStdin()
await session.wait()
```

### Example (Python)
```python
session = box.exec.session(argv=["sort"])
session.write("banana\napple\n")
session.end_stdin()
session.wait(30)
```
```

--------------------------------

### Set up the Upstash Box plugin

Source: https://upstash.com/docs/box/guides/herdr-setup

Runs the setup action for the upstash.box plugin. Prompts for an Upstash Box API key, checks it, then asks for the agent and provider credential. Keys are typed without echo.

```bash
herdr plugin action invoke setup --plugin upstash.box
```

--------------------------------

### Create and test a temporary public URL (Python)

Source: https://upstash.com/docs/box/overall/preview

Creates a Box instance, starts an HTTP server, gets a public URL, runs an HTTP GET test, and cleans up. Uses upstash_box. Note: getPreviewUrl, listPreviews, and deletePreview are deprecated aliases for getPublicURL, listPublicURLs, and deletePublicURL.

```python
import httpx
from upstash_box import Box
box = Box.create(runtime="node")
# Start test server
box.exec.command("npx http-server /work -p 3000 &")
# Create a public URL for testing
public_url = box.get_public_url(3000)
# Run your tests against the public URL
response = httpx.get(public_url.url)
print(response.status_code)  # 200
# Clean up
box.delete_public_url(3000)
box.delete()
```

--------------------------------

### Create a Box with initCommand (Python)

Source: https://upstash.com/docs/box/overall/quickstart

Create a box with a startup script using the Python SDK. The command runs from /workspace/home.

```python
box = Box.create(
    runtime="node",
    init_command="""node -e 'require("http").createServer((_, res) => res.end("Hello from Box!")).listen(3000)'""",
)
```

--------------------------------

### Multi-port application (TypeScript)

Source: https://upstash.com/docs/box/overall/preview

Creates a Box with Node runtime, writes frontend and API files, installs Express, starts both services, and creates public URLs for ports 3000 and 8080. Outputs both URLs.

```typescript
import { Agent, Box } from "@upstash/box"
const box = await Box.create({ runtime: "node" })
// Start frontend on port 3000
await box.files.write({
  path: "/work/frontend.js",
  content: `const express = require('express')
const app = express()
app.get('/', (req, res) => res.send('Frontend'))
app.listen(3000)
  `,
})
// Start API on port 8080
await box.files.write({
  path: "/work/api.js",
  content: `const express = require('express')
const app = express()
app.get('/api/status', (req, res) => res.json({ status: 'ok' }))
app.listen(8080)
  `,
})
await box.exec.command("npm install express")
await box.exec.command("node /work/frontend.js & node /work/api.js &")
// Create a public URL for each service
const frontendPublicUrl = await box.getPublicURL(3000)
const apiPublicUrl = await box.getPublicURL(8080)
console.log(`Frontend: ${frontendPublicUrl.url}`)
console.log(`API: ${apiPublicUrl.url}`)
```

--------------------------------

### Answer a prompt from an installer (TypeScript)

Source: https://upstash.com/docs/box/overall/live-sessions

Collects output, waits for the prompt 'Select a framework', then sends a newline to accept the default.

```typescript
let out = ""
const session = await box.exec.session({
  cmd: "npm create vite@latest my-app",
  tty: true,
  onStdout: (data) => (out += Buffer.from(data).toString()),
})
const deadline = Date.now() + 30000
while (!out.includes("Select a framework") && Date.now() < deadline) {
  await new Promise((r) => setTimeout(r, 100))
}
session.write("\n") // accept the default
await session.wait()
```

--------------------------------

### Share a secure public URL (TypeScript)

Source: https://upstash.com/docs/box/overall/preview

Creates a Box with Python runtime, writes a Flask app, installs Flask and starts the server, then creates a public URL with basic authentication. Outputs the URL, username, and password to share with team members.

```typescript
import { Agent, Box } from "@upstash/box"
const box = await Box.create({ runtime: "python" })
// Set up a Flask app
await box.files.write({
  path: "/work/app.py",
  content: `from flask import Flask
app = Flask(__name__)
@app.route('/')
def home():
    return 'Internal Dashboard'
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
  `,
})
await box.exec.command("pip install flask && python /work/app.py &")
// Create authenticated public URL
const publicUrl = await box.getPublicURL(8080, { basicAuth: true })
console.log(`Public URL: ${publicUrl.url}`)
console.log(`Username: ${publicUrl.username}`)
console.log(`Password: ${publicUrl.password}`)
// Share these credentials with your team
```

--------------------------------

### Create and test a temporary public URL (TypeScript)

Source: https://upstash.com/docs/box/overall/preview

Creates a Box instance, starts an HTTP server, gets a public URL, runs a fetch test, and cleans up. Uses @upstash/box. Note: getPreviewUrl, listPreviews, and deletePreview are deprecated aliases for getPublicURL, listPublicURLs, and deletePublicURL.

```typescript
import { Agent, Box } from "@upstash/box"
const box = await Box.create({ runtime: "node" })
// Start test server
await box.exec.command("npx http-server /work -p 3000 &")
// Create a public URL for testing
const publicUrl = await box.getPublicURL(3000)
// Run your tests against the public URL
const response = await fetch(publicUrl.url)
console.log(response.status) // 200
// Clean up
await box.deletePublicURL(3000)
await box.delete()
```

--------------------------------

### OpenCode agent configuration (Python)

Source: https://upstash.com/docs/box/overall/agent

Python example creating a Box with OpenCode as the agent, using the OPENCODE_API_KEY environment variable.

```python
import os
from upstash_box import Box, Agent
box = Box.create(
    runtime="node",
    agent={
        "harness": Agent.OPEN_CODE,
        "model": "opencode/claude-sonnet-4-6",
        "api_key": os.environ["OPENCODE_API_KEY"],
    },
)
```

--------------------------------

### Scaffold an Eve project with npx eve@latest init

Source: https://upstash.com/docs/box/guides/eve-setup

Initializes a new Eve project. The first command creates a basic agent, while the second starts with a Next.js web channel. Requires eve 0.65.0 or later.

```bash
npx eve@latest init my-agent
# or, to start with a Next.js app:
npx eve@latest init my-agent --channel-web-nextjs
```

--------------------------------

### Create directory (Python)

Source: https://upstash.com/docs/box/overall/files

Creates a directory. Pass parents to create missing parent directories, the way mkdir -p does, and to succeed when the directory already exists.

```python
box.files.mkdir("output/reports", parents=True)
```

--------------------------------

### Install upstash-box Python package

Source: https://upstash.com/docs/box/guides/browser-use

Install the Upstash Box SDK via pip.

```bash
pip install upstash-box
```

--------------------------------

### Configure environment variables

Source: https://upstash.com/docs/box/guides/code-review-agent

Set the necessary API keys and tokens in your .env file.

```text
UPSTASH_BOX_API_KEY=box_xxxxxxxxxxxxxxxxxxxxxxxxANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxGITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Run a build and extract artifacts (Python)

Source: https://upstash.com/docs/box/overall/shell

Python equivalent of the TypeScript example. Uploads source files, runs a build command, downloads the dist folder, and deletes the box.

```python
from upstash_box import Box
box = Box.create(runtime="node")
box.files.upload([
    {"path": "./src", "destination": "/work/src"},
    {"path": "./package.json", "destination": "/work/package.json"},
])
box.exec.command("cd /work && npm install && npm run build")
box.files.download(folder="/work/dist")
box.delete()
```

--------------------------------

### Install T3 Code

Source: https://upstash.com/docs/box/guides/t3-code-setup

Install the T3 Code CLI globally within the box environment.

```bash
sudo npm install -g t3
```

--------------------------------

### Reusable base environments (Python)

Source: https://upstash.com/docs/box/overall/snapshots

Python equivalent of the reusable base environment example. Uses AsyncBox and asyncio to spawn boxes from the snapshot in parallel.

```python
import asyncio
from upstash_box import AsyncBox
async def main() -> None:
    base = await AsyncBox.create(runtime="node")
    await base.exec.command("npm install -g typescript eslint prettier")
    base_snap = await base.snapshot(name="node-toolchain")
    await base.delete()
    async def run_task(task: str) -> AsyncBox:
        box = await AsyncBox.from_snapshot(base_snap.id)
        await box.agent.run(prompt=task)
        return box
    # spawn boxes from the snapshot in parallel
    await asyncio.gather(*(run_task(t) for t in tasks))
asyncio.run(main())
```

--------------------------------

### Install the Upstash Box plugin

Source: https://upstash.com/docs/box/guides/herdr-setup

Installs the upstash/herdr-upstash-box plugin. Requires Herdr 0.8.0 or newer and Node.js 22 or newer.

```bash
herdr plugin install upstash/herdr-upstash-box
```

--------------------------------

### Start T3 Code Server and Retrieve Pairing URL

Source: https://upstash.com/docs/box/guides/t3-code-setup

Launch the T3 Code server in the background and display the pairing URL from the log file.

```bash
setsid nohup t3 serve --host 0.0.0.0 --port 3773 --base-dir /workspace/home/.t3 > /tmp/t3.log 2>&1 < /dev/null &sleep 5 && grep "Pairing URL" /tmp/t3.log
```

```text
Pairing URL: http://172.18.0.11:3773/pair#token=LTTPGQ8SAX39
```

--------------------------------

### Migrate from defineSandbox with upstash() to UpstashSandbox.environment()

Source: https://upstash.com/docs/box/guides/eve-setup

Shows the before and after of migrating from the deprecated `defineSandbox({ backend: upstash(...) })` to the new provider-based `UpstashSandbox.environment()` API. The `bootstrap` method becomes `prepare`, and `onSession`'s `use({ networkPolicy })` becomes `environment.open({ networkPolicy })`.

```typescript
// before
export default defineSandbox({
  backend: upstash({ runtime: "node" }),
  async bootstrap({ use }) {
    const sandbox = await use({ networkPolicy: "allow-all" });
    await sandbox.run({ command: "sudo -n apt-get install -y jq" });
  },
  async onSession({ use }) {
    await use();
  },
});
```

```typescript
// after
export const environment = UpstashSandbox.environment({
  runtime: "node",
  async prepare(sandbox) {
    await sandbox.setNetworkPolicy("allow-all");
    await sandbox.run({ command: "sudo -n apt-get install -y jq" });
  },
});
export default defineSandbox(() => environment.open());
```

--------------------------------

### Install Upstash Plugin

Source: https://upstash.com/docs/box/guides/remote-development

Use this command to install the Upstash plugin in Claude Code or Codex to add the MCP server and skills.

```bash
/plugin marketplace add upstash/skills/plugin install upstash@upstash
```

--------------------------------

### OpenCode agent configuration (TypeScript)

Source: https://upstash.com/docs/box/overall/agent

TypeScript example creating a Box with OpenCode as the agent, using the OPENCODE_API_KEY environment variable.

```typescript
import { Agent, Box } from "@upstash/box"
const box = await Box.create({
  runtime: "node",
  agent: {
    harness: Agent.OpenCode,
    model: "opencode/claude-sonnet-4-6",
    apiKey: process.env.OPENCODE_API_KEY!,
  },
})
```

--------------------------------

### Agent options with run() (Python)

Source: https://upstash.com/docs/box/overall/agent

Python example passing provider-specific options to box.agent.run(), using snake_case keys like max_turns.

```python
run = box.agent.run(
    prompt="Refactor the auth flow and keep changes minimal",
    options={
        "effort": "medium",
        "max_turns": 12,
    },
)
```

--------------------------------

### tab.create

Source: https://upstash.com/docs/box/overall/browser/tabs

Opens a new tab, navigates it to a URL, and waits for the specified lifecycle state. The first call also boots Chromium if not running.

```APIDOC
## tab.create

### Description
Opens a new tab, navigates it to a URL, and waits for the specified lifecycle state. The first call also boots Chromium if not running.

### Method
create

### Endpoint
box.browser.tab.create(url, options)

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to navigate to.

#### Options
- **waitUntil** (string) - Optional - When navigation counts as done. One of `"load"` (default), `"domcontentloaded"`, or `"networkidle"`.
- **timeout** (number) - Optional - Navigation timeout in milliseconds. Defaults to `30000`. Pass `0` to disable it.

### Request Example
```typescript
const tab = await box.browser.tab.create("https://upstash.com", {
  waitUntil: "domcontentloaded",
  timeout: 30_000,
})
```

### Response
#### Success Response
- **tab** (Tab) - The created tab handle with properties `id`, `url`, and `title`.

#### Response Example
```typescript
console.log(tab.id, tab.url, tab.title)
```
```

--------------------------------

### Install Upstash Box and AI SDK packages

Source: https://upstash.com/docs/box/guides/ai-sdk-setup

Install the required npm packages for using Upstash Box with the Vercel AI SDK and Anthropic provider.

```bash
npm install @upstash/box @ai-sdk/anthropic @ai-sdk/react ai zod
```

--------------------------------

### Hold a command open (Python)

Source: https://upstash.com/docs/box/overall/shell

Start a live session to write to stdin, drive interactive programs, or signal a process while it runs.

```python
session = box.exec.session(argv=["sort"])
session.write("banana\napple\n")
session.end_stdin()
session.wait(30)
```

--------------------------------

### Start a session with cmd (TypeScript)

Source: https://upstash.com/docs/box/overall/live-sessions

Starts a session with a shell command string, running through bash -lc. Use for pipes, globs, or &&. Note that argv does not expand variables or treat ; as a separator.

```typescript
const session = await box.exec.session({ cmd: "cat *.log | grep ERROR" })
```

--------------------------------

### Navigate with goto (Python)

Source: https://upstash.com/docs/box/overall/browser/tabs

Python equivalent of navigating with goto.

```python
page = tab.goto("https://upstash.com/docs")
print(page.title, page.url)
```

--------------------------------

### Start a session with argv (TypeScript)

Source: https://upstash.com/docs/box/overall/live-sessions

Starts a session with an argv array, avoiding a shell for safety. Output arrives via onStdout and onStderr callbacks. wait() blocks until exit and returns the exit code.

```typescript
let out = ""
const session = await box.exec.session({
  argv: ["npm", "test"],
  onStdout: (data) => (out += Buffer.from(data).toString()),
  onStderr: (data) => console.error(Buffer.from(data).toString()),
})
console.log(session.pid)     // in-box process id
const code = await session.wait()
console.log(code)            // exit code
```

--------------------------------

### Start a recording (Python)

Source: https://upstash.com/docs/box/overall/browser/recordings

Starts a recording with a maximum duration of 120 seconds. The recording stops when stop() is called, when max_duration_seconds is reached (default and maximum: 600 seconds), or automatically after 3 minutes with no on-screen activity.

```python
# Start capturing (one active recording per box)
recording = box.browser.recordings.start(max_duration_seconds=120)
tab.goto("https://upstash.com/docs")
tab.act("open the quickstart guide")
# Finalize the video and upload it
saved = recording.stop()
print(saved.duration_ms, saved.playlist_url)
print(saved.markers)  # tab switches
```

--------------------------------

### Create a box and run a command and agent (Python)

Source: https://upstash.com/docs/box/overall/quickstart

Creates a box with the Node runtime and Claude Code harness, executes an OS-level command, and runs an agent that creates a file. Requires an ANTHROPIC_API_KEY environment variable.

```python
import os
from upstash_box import Box, Agent
box = Box.create(
    runtime="node",
    agent={
        "harness": Agent.CLAUDE_CODE,
        "model": "anthropic/claude-opus-4-6",
        "api_key": os.environ["ANTHROPIC_API_KEY"],
    },
)
# 👇 execute OS-level commands
box.exec.command("node --version")
# 👇 run agent
box.agent.run(prompt="create an index.txt saying 'hello world'")
```

--------------------------------

### Start a recording (TypeScript)

Source: https://upstash.com/docs/box/overall/browser/recordings

Starts a recording with a maximum duration of 120 seconds. The recording stops when stop() is called, when maxDurationSeconds is reached (default and maximum: 600 seconds), or automatically after 3 minutes with no on-screen activity.

```typescript
// Start capturing (one active recording per box)
const recording = await box.browser.recordings.start({
  maxDurationSeconds: 120,
})
await tab.goto("https://upstash.com/docs")
await tab.act("open the quickstart guide")
// Finalize the video and upload it
const saved = await recording.stop()
console.log(saved.durationMs, saved.playlistUrl)
console.log(saved.markers) // tab switches
```
Tokens:
Raw