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

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

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: "npm install && npm run dev",})

The command runs from /workspace/home, so it assumes a project is already there. You can read, change, or remove it 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 { 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,  },})

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

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#