> ## 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.

# 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.

<Note>Upstash Box is in developer preview — APIs and pricing may change.</Note>

### 1. Get your API key

Go to the [Upstash Console](https://console.upstash.com) and create an API key.

<Frame>
  <img src="https://mintcdn.com/upstash/qgZXOqj0wFP3A6Mb/img/box/create-api-key.png?fit=max&auto=format&n=qgZXOqj0wFP3A6Mb&q=85&s=d7ca4acdd1161efc9b4d0c1044343813" width="1131" height="844" data-path="img/box/create-api-key.png" />
</Frame>

### 2. Install the SDK

<CodeGroup>
  ```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
  ```
</CodeGroup>

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

<Tip>
  By default, runtimes use **Debian** (glibc). For smaller Alpine-based images, use `"node-alpine"`, `"python-alpine"`, etc.
</Tip>

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 and can run an `initCommand` at startup. See [Keep Alive](/box/overall/keep-alive).
</Tip>

***

### 5. Configure an Agent (optional)

To configure an agent for your box, pass the model you want to use and the provider API key:

<Tabs>
  <Tab title="Claude">
    ```typescript {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,
      },
    })
    ```
  </Tab>

  <Tab title="Codex">
    ```typescript {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,
      },
    })
    ```
  </Tab>
</Tabs>

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

### 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**.

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:

<CardGroup cols={3}>
  <Card title="Agent Servers" icon="server" href="/box/overall/how-it-works#1-agent-server">
    One box per user with durable state. Personalized agents that remember context and improve over time.
  </Card>

  <Card title="Multi-Agent Orchestration" icon="diagram-project" href="/box/overall/how-it-works#2-multi-agent-orchestration">
    Fan out to multiple boxes running specialized agents in parallel, then combine their results.
  </Card>

  <Card title="Parallel Testing" icon="flask-vial" href="/box/overall/how-it-works#3-parallel-testing--model-comparison">
    Run the same inputs across isolated boxes and compare model output side by side.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="How Boxes work" href="/box/overall/how-it-works">
    Learn the basics about using Upstash Box.
  </Card>

  <Card title="Agent" href="/box/overall/agent">
    Boxes have Claude Code, Codex or OpenCode built-in.
  </Card>
</CardGroup>