Skip to main content
Upstash Box lets you give your AI agents a computer. Every box is a secure, isolated cloud container with an AI agent like Claude Code or Codex built-in. Spin up as many as you want in parallel. Each one includes a full environment with a filesystem, git, and a runtime. Your agent can read files, write code, and execute tasks inside it.

​
1. Get your API key

Navigate to the Upstash Console and create a new Box API key.

​
2. Install the SDK

npm install @upstash/box

​
3. Set Environment Variables

Add your Upstash Box API key:
.env
UPSTASH_BOX_API_KEY=abx_xxxxxxxxxxxxxxxxxxxxxxxx

​
4. Create a Box

lib/box.ts
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 { Box, ClaudeCode } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  agent: {
    model: ClaudeCode.Sonnet_4_5,
    apiKey: process.env.ANTHROPIC_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 { Box, ClaudeCode } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
  agent: {
    model: ClaudeCode.Sonnet_4_5,
    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'",
})

​
Next Steps

How a box works

Full TypeScript SDK reference and examples

Agent

Agent