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.

Create a Box API key in the Upstash Console

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

.env

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 Box

box = Box.create(runtime="node")

The Python SDK ships both a synchronous Box (used here) and an asynchronous AsyncBox (box = await AsyncBox.create(...)).

By default, runtimes use Debian (glibc). For smaller Alpine-based images, use "node-alpine", "python-alpine", etc.

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.

You can also create a keep-alive box by setting keepAlive: true. Keep-alive boxes stay on between sessions instead of auto-pausing. See Keep Alive.

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

box = Box.create(
    runtime="node",
    init_command="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:

Claude
Codex

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

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 os
from upstash_box import Box, Agent

box = 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 commands
await box.exec.command("node --version")

// 👇 run agent
await box.agent.run({
  prompt: "create an index.txt saying 'hello world'",
})

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

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:

Agent Servers

One box per user with durable state. Personalized agents that remember context and improve over time.

Multi-Agent Orchestration

Fan out to multiple boxes running specialized agents in parallel, then combine their results.

Parallel Testing

Run the same inputs across isolated boxes and compare model output side by side.

Get Started

1. Get your API key

2. Install the SDK

3. Set API Key

4. Create a Box

Init command

5. Configure an Agent (optional)

6. Run Your First Task

7. Connect over SSH

Use Cases

Agent Servers

Multi-Agent Orchestration

Parallel Testing

Next Steps

How Boxes work

Agent

SDKs

​1. Get your API key

​2. Install the SDK

​3. Set API Key

​4. Create a Box

​Init command

​5. Configure an Agent (optional)

​6. Run Your First Task

​7. Connect over SSH

​Use Cases

Agent Servers

Multi-Agent Orchestration

Parallel Testing

​Next Steps

How Boxes work

Agent

​SDKs

1. Get your API key

2. Install the SDK

3. Set API Key

4. Create a Box

Init command

5. Configure an Agent (optional)

6. Run Your First Task

7. Connect over SSH

Use Cases

Next Steps

SDKs