Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion box/overall/how-it-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
title: "Box Basics"
---

Every Upstash Box is a **durable execution environment** for AI workloads. Each box is an isolated container with its own filesystem, shell, network stack, and optional coding agent. You send prompts or commands, the box executes them, and you get back structured results without managing infrastructure.

Check warning on line 5 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L5

Did you really mean 'Upstash'?

Boxes are billed per active CPU time (not idle time), state persists across runs, and you can choose from Node, Python, Go or other runtimes. Unlike other sandboxing services, our boxes do not have a maximum session duration, you can resume them days or even weeks later.

Check warning on line 7 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L7

Did you really mean 'runtimes'?

Check warning on line 7 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L7

Did you really mean 'sandboxing'?

---

Expand All @@ -20,7 +20,7 @@

Each user gets a dedicated Box running its own agent. The agent observes every request and response in a non-blocking way. It builds up a personalized understanding of what that user needs. Over time, it contributes back to a shared **Knowledge Base**, so insights from one tenant can improve results for everyone.

Because boxes are serverless, idle tenants only cost a very low storage rate. When a user returns, their box wakes instantly with all prior state intact (installed packages, file history, learned preferences) and picks up exactly where it left off.

Check warning on line 23 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L23

Did you really mean 'serverless'?

### 2. Multi-Agent Orchestration

Expand Down Expand Up @@ -68,7 +68,7 @@
<img src="/img/box/model-comparison.png" />
</Frame>

For example, at Context7 we use Box to benchmark LLMs for context extraction over documentation. We spin up boxes in parallel, each running a different model against the same documentation files and prompts. We then evaluate hallucination percentage, accuracy score, and context quality to find the best model:

Check warning on line 71 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L71

Did you really mean 'LLMs'?

```tsx
const models = ["claude/opus_4_6", "openai/gpt-5.4-codex", "google/gemini-3-pro"]
Expand All @@ -92,7 +92,7 @@
const bestModel = evaluation.sort((a, b) => a.hallucinationPct - b.hallucinationPct)[0]
```

Each box is fully isolated, so one model's behavior never leaks into another's results.

Check warning on line 95 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L95

Did you really mean 'another's'?

---

Expand All @@ -103,7 +103,7 @@
| Module | Description |
| -------------- | ------------------------------------------------------------ |
| **Agent** | Run a coding agent (Claude Code or Codex) |
| **Git** | Clone repos, inspect diffs, and open pull requests |

Check warning on line 106 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L106

Did you really mean 'repos'?
| **Shell** | Execute OS-level commands directly |
| **Filesystem** | Upload, write, read, list, and download files inside the box |
| **Snapshots** | Capture box state and restore new boxes from it |
Expand All @@ -120,7 +120,7 @@

### 1. Created

When you create a box, Upstash provisions a new isolated container with its own filesystem, shell, and network stack. You can start from a fresh box or restore from a snapshot. Once provisioning finishes, the box is ready to receive commands.

Check warning on line 123 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L123

Did you really mean 'Upstash'?

### 2. Running

Expand Down Expand Up @@ -177,6 +177,31 @@

This is the core lifecycle entrypoint for dashboards, background workers, and apps that persist a box ID or name between requests.

### Box size

Boxes have configurable resource sizes, set at creation time via the `size` option. Defaults to `"small"`.

| Size | CPU | Memory |
| -------- | ------- | ------ |
| `small` | 2 cores | 4 GB |
| `medium` | 4 cores | 8 GB |
| `large` | 8 cores | 16 GB |

```ts
const box = await Box.create({
size: "large",
agent: { provider: Agent.ClaudeCode, model: ClaudeCode.Sonnet_4_5 },
})

console.log(box.size) // "large"
```

Also supported in `Box.fromSnapshot()`:

```ts
const box = await Box.fromSnapshot("snap_abc123", { size: "medium" })
```

### Check status and inspect activity

```tsx
Expand Down Expand Up @@ -231,14 +256,14 @@
<img src="/img/box/routing.png" />
</Frame>

Your app makes SDK calls to the Upstash API gateway, which authenticates the request and routes it to the correct box. Each box has a unique ID, and all communication between your app and the box is encrypted in transit.

Check warning on line 259 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L259

Did you really mean 'Upstash'?

Inside a box, the agent, shell, filesystem, and git all share the same isolated environment. The agent can install packages, write files, spawn processes, and make outbound HTTP requests, but only within its own container boundary. It cannot access the host, other boxes, or any Upstash-internal infrastructure.

| Boundary | Guarantee |
| -------------- | --------------------------------------------------------------------------------------- |
| **Filesystem** | Each box has its own filesystem. No shared volumes between boxes. |
| **Processes** | Process trees are fully isolated. One box cannot signal or inspect another's processes. |

Check warning on line 266 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L266

Did you really mean 'another's'?
| **Network** | Boxes can make outbound requests (HTTP, DNS) but cannot reach other boxes. |

---
Expand All @@ -247,7 +272,7 @@

Every box has full outbound network access by default. HTTP, HTTPS, DNS, WebSockets, and raw TCP are all available. Agents can call external APIs, download packages, pull container images, and interact with any public endpoint.

Boxes run on AWS infrastructure with **22.5 Gbps** network bandwidth per host. This means large file transfers, dataset downloads, and parallel API calls are fast by default.

Check warning on line 275 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L275

Did you really mean 'Gbps'?

Because boxes run on fast AWS infrastructure, they have single-digit ms to major cloud services (S3, GitHub, etc.).

Expand All @@ -271,7 +296,7 @@
| --- | --- |
| `allow-all` | Default. No restrictions on outbound traffic. |
| `deny-all` | Block all outbound network access. |
| `custom` | Allow or deny specific domains and CIDRs. |

Check warning on line 299 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L299

Did you really mean 'CIDRs'?

In `custom` mode you can combine `allowedDomains`, `allowedCidrs`, and `deniedCidrs`:

Expand Down Expand Up @@ -310,13 +335,13 @@
| **Memory** | Included at no extra cost |
| **Storage** | $0.10 per GB-month for **all** persisted storage, including disks and snapshots |

Boxes are currently available in one size with 2 vCPU, 2GB of memory and 10GB disk space.
Pricing scales with box size: `medium` costs 2x and `large` costs 4x the `small` rate.

---

## Agent

Every Upstash Box comes with built-in coding agent harnesses. You don't need to bring your own agent framework or wire up tool calls. The box already knows how to give an agent access to its shell, filesystem, and git, and how to stream output back to you.

Check warning on line 344 in box/overall/how-it-works.mdx

View check run for this annotation

Mintlify / Mintlify Validation (upstash) - vale-spellcheck

box/overall/how-it-works.mdx#L344

Did you really mean 'Upstash'?

We currently support Claude Code and Codex as native agents inside of a box. You choose a model when creating a box.

Expand Down