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.

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#