> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upstash Box Quickstart

Building with an AI coding agent?

Connect the Upstash MCP server and the Box skill to Claude Code, Cursor, Codex, and other agents.

[Open](https://upstash.com/docs/agent-resources/overview.md)

**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](https://console.upstash.com) and create an API key.

![Create a Box API key in the Upstash Console](https://mintcdn.com/upstash/qgZXOqj0wFP3A6Mb/img/box/create-api-key.png?fit=max\&auto=format\&n=qgZXOqj0wFP3A6Mb\&q=85\&s=d7ca4acdd1161efc9b4d0c1044343813)

### 2. Install the SDK

```bash npm theme={"system"}
npm install @upstash/box
```

```bash yarn theme={"system"}
yarn add @upstash/box
```

```bash pnpm theme={"system"}
pnpm add @upstash/box
```

```bash bun theme={"system"}
bun install @upstash/box
```

```bash pip theme={"system"}
pip install upstash-box
```

### 3. Set API Key

```bash title=".env" theme={"system"}
UPSTASH_BOX_API_KEY=box_xxxxxxxxxxxxxxxxxxxxxxxx
```

### 4. Create a Box

```typescript title="lib/box.ts" theme={"system"}
import { Box } from "@upstash/box"

const box = await Box.create({
  runtime: "node",
})
```

```python box.py theme={"system"}
from upstash_box import Box

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

> [!TIP]
>
> The Python SDK ships both a synchronous `Box` (used here) and an asynchronous
> `AsyncBox` (`box = await AsyncBox.create(...)`).

> [!TIP]
>
> 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.

> [!TIP]
>
> You can also create a keep-alive box by setting `keepAlive: true`. Keep-alive boxes stay on between sessions instead of auto-pausing and require a paid plan. See [Keep Alive](https://upstash.com/docs/box/overall/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.

```typescript box.ts theme={"system"}
const box = await Box.create({
  runtime: "node",
  initCommand: `node -e 'require("http").createServer((_, res) => res.end("Hello from Box!")).listen(3000)'`,
})
```

```python box.py theme={"system"}
box = Box.create(
    runtime="node",
    init_command="""node -e 'require("http").createServer((_, res) => res.end("Hello from Box!")).listen(3000)'""",
)
```

This example uses Node.js's built-in HTTP server, so it works in a fresh box without installing packages. The command runs from `/workspace/home`. For an existing app, prepare its project files and dependencies before setting its startup command.

You can read, change, or remove the command 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:

> [tab] Claude
>
> ```typescript box.ts {5-8} theme={"system"}
> 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,
>   },
> })
> ```
>
> ```python box.py {6-10} theme={"system"}
> 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"],
>     },
> )
> ```

> [tab] Codex
>
> ```typescript box.ts {5-8} theme={"system"}
> 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,
>   },
> })
> ```
>
> ```python box.py {6-10} theme={"system"}
> 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:

```typescript box.ts theme={"system"}
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'",
})
```

```python box.py theme={"system"}
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:

```bash theme={"system"}
ssh <box-id>@us-east-1.box.upstash.com
```

When SSH asks for a password, enter your **Box API key**. To log in without a password, [add an SSH key](https://upstash.com/docs/box/overall/shell#ssh-keys).

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:

> [card] [Agent Servers](https://upstash.com/docs/box/overall/use-cases#1-agent-servers)
>
> One box per user with durable state. Personalized agents that remember context and improve over time.

> [card] [Multi-Agent Orchestration](https://upstash.com/docs/box/overall/use-cases#2-multi-agent-orchestration)
>
> Fan out to multiple boxes running specialized agents in parallel, then combine their results.

> [card] [Parallel Testing](https://upstash.com/docs/box/overall/use-cases#3-parallel-testing-&-comparison)
>
> Run the same inputs across isolated boxes and compare model output side by side.

***

## Next Steps

> [card] [How Boxes work](https://upstash.com/docs/box/overall/how-it-works)
>
> Learn the basics about using Upstash Box.

> [card] [Agent](https://upstash.com/docs/box/overall/agent)
>
> Boxes have Claude Code, Codex, OpenCode, and Cursor built-in, plus custom agents.

## SDKs


## Related topics

- [Upstash Box Schedules](https://upstash.com/docs/box/overall/schedules.md)
- [Upstash Realtime Quickstart](https://upstash.com/docs/realtime/overall/quickstart.md)
- [Upstash Blob Quickstart](https://upstash.com/docs/blob/overall/quickstart.md)
- [Upstash Box Use Cases](https://upstash.com/docs/box/overall/use-cases.md)
- [Run Orca Workspaces in Upstash Box](https://upstash.com/docs/box/guides/orca-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.