Quickstart

Upstash Box lets you give your AI agents a computer.

Every Upstash Box is a secure, isolated cloud container with an AI Agent built-in. Spin up as many as you want in parallel. Each one includes a full environment with a filesystem, shell, git, and a runtime. Your agent can read files, write code, and execute tasks inside it.

1. Get your API key#

Go to the Upstash Console and create an API key.

2. Install the SDK#

npm install @upstash/box

yarn add @upstash/box

pnpm add @upstash/box

bun install @upstash/box

pip install upstash-box

3. Set API Key#

UPSTASH_BOX_API_KEY=box_xxxxxxxxxxxxxxxxxxxxxxxx

4. Create a Box#

import { Box } from "@upstash/box"const box = await Box.create({  runtime: "node",})

from upstash_box import Boxbox = Box.create(runtime="node")

Your box is ready to use! You can already use it as a standalone, secure, isolated sandbox with full shell access, git, and filesystem operations.

Init command#

Pass initCommand to run a startup script each time the box starts. It runs once per container start, on create, on resume, and after a snapshot restore, so it is the place to start a server that should come back with the box.

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

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

This example uses Node.js’s built-in HTTP server, so it works in a fresh box without installing packages. The command runs from /workspace/home. For an existing app, prepare its project files and dependencies before setting its startup command.

You can read, change, or remove the command later with getInitCommand, setInitCommand, and deleteInitCommand (get_init_command, set_init_command, delete_init_command in Python), on any box including a paused one. A box restored from a snapshot does not inherit the snapshot’s init command, so pass it again on the restore.

5. Configure an Agent (optional)#

To configure an agent for your box, pass the model you want to use and the provider API key:

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

import osfrom upstash_box import Box, Agentbox = Box.create(    runtime="node",    agent={        "harness": Agent.CLAUDE_CODE,        "model": "anthropic/claude-opus-4-6",        "api_key": os.environ["ANTHROPIC_API_KEY"],    },)

import { Agent, Box } from "@upstash/box"const box = await Box.create({  runtime: "node",  agent: {    harness: Agent.Codex,    model: "openai/gpt-5.3-codex",    apiKey: process.env.OPENAI_API_KEY,  },})

import osfrom upstash_box import Box, Agentbox = Box.create(    runtime="node",    agent={        "harness": Agent.CODEX,        "model": "openai/gpt-5.3-codex",        "api_key": os.environ["OPENAI_API_KEY"],    },)

6. Run Your First Task#

Your box is ready to use! It’s a secure cloud environment to run agents, execute commands, or manage files. For example:

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,  },})// 👇 execute OS-level commandsawait box.exec.command("node --version")// 👇 run agentawait box.agent.run({  prompt: "create an index.txt saying 'hello world'",})

import osfrom upstash_box import Box, Agentbox = 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 commandsbox.exec.command("node --version")# 👇 run agentbox.agent.run(prompt="create an index.txt saying 'hello world'")

7. Connect over SSH#

You can also connect directly to a box shell with SSH:

ssh <box-id>@us-east-1.box.upstash.com

When SSH asks for a password, enter your Box API key.

You can copy the exact SSH command for a box from the SSH button on its details page in the Upstash Console.

Use Cases#

The idea behind Upstash Box is simple: give AI its own computer. Your agent gets a full, isolated cloud environment it can control. Run commands, write files, or execute code independent of any user device. Freeze a box anytime, and continue days or even weeks later with perfect resumability.

Great example use cases:

Next Steps#

SDKs#