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.

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

@upstash/box

TypeScript SDK for Upstash Box.

box (Python)

Python SDK for Upstash Box.

Box CLI

Create and manage boxes from your terminal.