# Agent capabilities
Source: https://docs.opencomputer.dev/agents/capabilities

Choose between tools, MCP servers, skills, subagents, and outbound connections

Capabilities give an agent something beyond its instructions and model. Choose
the narrowest capability that fits the job.

| Capability        | Use it for                                             | Where the work happens                    | How it is attached                              |
| ----------------- | ------------------------------------------------------ | ----------------------------------------- | ----------------------------------------------- |
| Code-defined tool | One typed operation you implement                      | Your TypeScript `run()` function          | `useTool(tool)`                                 |
| MCP server        | A service that already publishes a collection of tools | The remote MCP server                     | `useMcpServer(server)`                          |
| Skill             | A reusable procedure, checklist, or supporting files   | The agent follows the loaded instructions | Place it under `skills/`                        |
| Subagent          | Delegating a focused task to another project agent     | The delegated agent                       | `useSubagent(agentId)`                          |
| HTTP connection   | A constrained authenticated outbound request           | OpenComputer sends the declared request   | Call `defineConnection().fetch()` inside a tool |

`useModel()` selects the model for a render, but it does not add an executable
capability.

## Tool or MCP server?

Use a [code-defined tool](/agents/tools) when you own the operation, want a
small schema, or need application-specific validation. Use an
[MCP server](/agents/mcp) when another service already hosts the tools.

Both ultimately give the model callable tools. A code-defined tool exposes the
single operation you register; an MCP server exposes the tools it advertises.

## Tool or skill?

A tool performs an operation and returns structured data. A
[skill](/agents/skills) teaches the agent how to approach a category of work.
Many agents use both: the skill describes the workflow while tools perform the
individual actions.

## Tool or subagent?

Use a tool for a bounded operation such as fetching an order. Use a
[subagent](/agents/subagents) when the task benefits from its own instructions,
model selection, capabilities, and working context.

## Connections are not managed accounts

`defineConnection()` declares a secret-backed HTTP destination. It is not an
OAuth account selector and does not itself give the model a tool. Call it from
a code-defined tool, or attach it to an MCP definition when that server accepts
the corresponding header-based authorization.

See [Secrets and outbound requests](/agents/secrets) for the complete security
model.


# Deployments and environments
Source: https://docs.opencomputer.dev/agents/deployments

Understand development, production, immutable deployments, and aliases

A deployment is an immutable build of one agent. An alias gives a stable name
to the deployment clients should run.

Every project starts with two working environments:

| Environment | Alias         | How it changes                         |
| ----------- | ------------- | -------------------------------------- |
| Development | `development` | `npm run dev` publishes source changes |
| Production  | `production`  | An explicit deploy advances it         |

Sessions keep the deployment they started with. Publishing another version
does not change the code underneath an existing session.

## Deploy to production

From the project directory:

```bash theme={null}
npm run deploy -- --alias production
```

The CLI builds the current source, creates an immutable deployment, and moves
the `production` alias to it. Development remains available for further work.

## Select an agent and environment

Clients identify an agent with `agent-id@alias`:

```text theme={null}
support@development
support@production
```

The project dashboard's environment selector changes which deployment you are
inspecting. The playground has a separate agent selector when a project
contains more than one agent.

## Review history

Open the project's **Deployments** page to inspect immutable versions, their
aliases, and creation times. Use the deployment ID when correlating a session
with [logs](/agents/logs) or the [debug inspector](/agents/playground).


# Cloud development
Source: https://docs.opencomputer.dev/agents/development

Sync agent code to Development while your application runs locally

OpenComputer's development loop keeps agent execution in the cloud while your
source files and optional React application stay on your machine.

```bash theme={null}
npm run dev
```

The command performs four jobs:

1. Links the source directory to a cloud project.
2. Builds and publishes every configured agent to `development`.
3. Watches `opencomputer/` and publishes changes automatically.
4. Starts Vite when the project includes the React application.

It also prints the project dashboard URL so you can test the same development
deployment in the [agent playground](/agents/playground).

## Select a project

On the first run, select an existing project or create one. The choice is saved
locally and reused by later commands.

```bash theme={null}
npx opencomputer link
```

Use an explicit project in scripts or other non-interactive environments:

```bash theme={null}
npx opencomputer dev --project <project-id-or-slug>
npx opencomputer dev --create-project "Support agents"
```

## Work with the React application

When a React application is present, the same `npm run dev` process starts both
cloud synchronization and Vite. Keep it running while using the application;
the development bridge exists only for the lifetime of that process.

New sessions use the latest synchronized development deployment. Existing
sessions keep the deployment they started with, so create a new session when
testing a source change.

## Synchronize development secrets

Put agent credentials in `opencomputer/.env.local`. OpenComputer considers only
names referenced by `useSecret()` and infers their allowed destinations from
`defineConnection()` declarations.

```dotenv theme={null}
GITHUB_TOKEN=github_pat_...
```

The CLI asks before the first upload and then watches for changes. Unreferenced
variables are skipped, and removing a local value does not delete its cloud
counterpart. See [Secrets and outbound requests](/agents/secrets).

## Development and production stay separate

Saving source advances only `development`. Production remains on its current
immutable deployment until you explicitly deploy it. See
[Deployments and environments](/agents/deployments).


# Exa research session
Source: https://docs.opencomputer.dev/agents/examples/exa-research-session

A web-research agent with live Exa results and durable follow-up questions

The Exa research starter is a small React application backed by an
OpenComputer agent. Ask a question in the browser and the agent searches the
live web with Exa, compares relevant results, and streams a concise answer with
source links.

Follow-up questions reuse the same session, so the agent keeps the research
conversation and can refine an earlier answer without starting over.

## How it works

1. The React application sends a question to an OpenComputer session.
2. The agent uses its `exa_search` tool when the question needs current web
   research.
3. The declared Exa connection sends the request with the write-only
   `EXA_API_KEY` without adding it to agent source or browser code.
4. The agent reads the results and streams an answer with clickable source
   URLs back to the application.

The starter also includes an agent-specific skill that guides the research
workflow and uses `@opencomputer/react` to stream messages and continue the
same session.

## Start with the example

<Card title="Exa research starter" icon="github" href="https://github.com/diggerhq/opencomputer-example-exa">
  Clone the complete React and OpenComputer project from GitHub.
</Card>

The repository README covers installation, setting the Exa secret, running the
combined cloud-agent and React development process, and deploying the finished
application.


# Agent hooks
Source: https://docs.opencomputer.dev/agents/hooks

Compose agent capabilities with reactive hooks

An agent function returns instructions. Hooks give that agent the model,
tools, services, and context it needs to follow those instructions.

```tsx theme={null}
import { useInput, useModel, useTool } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  useModel("anthropic/claude-sonnet-4.6");

  if (input.text?.includes("latest")) {
    useTool("web-search");
  }

  return "Answer directly. Use current sources when web search is available.";
}
```

## How hooks work

OpenComputer renders the exported function before each model step. Every hook
called during that render contributes to the next step's configuration. Hooks
describe capabilities; they do not call the model or run a tool themselves.

Unlike React component hooks, OpenComputer resource hooks can be conditional.
The example above exposes `web-search` only when the current input asks for
recent information.

Hooks can only run while OpenComputer is rendering an agent. Keep network
requests and other asynchronous work inside [tools](/agents/tools), not in the
agent function.

## Built-in hooks

| Hook                     | What it does                                                 | Guide                                |
| ------------------------ | ------------------------------------------------------------ | ------------------------------------ |
| `useInput()`             | Reads the current input source, text, and structured payload | [Inputs](/agents/inputs)             |
| `useCurrentInput()`      | Alias for `useInput()`                                       | [Inputs](/agents/inputs)             |
| `useModel(model)`        | Selects the model used for the next step                     | [Models](/agents/models)             |
| `useTool(tool)`          | Exposes a named or code-defined tool                         | [Tools](/agents/tools)               |
| `useMcpServer(server)`   | Exposes tools from a managed HTTPS MCP server                | [MCP servers](/agents/mcp)           |
| `useSubagent(agent)`     | Makes another project agent available for delegation         | [Subagents](/agents/subagents)       |
| `useSessionData<T>(key)` | Reads a durable value associated with the session            | [Session data](/agents/session-data) |

[Skills](/agents/skills) are also agent capabilities, but they are discovered
from the agent's `skills/` directory rather than attached with a hook.

## Compose your own hooks

Hooks are ordinary synchronous functions. Group related capabilities in a
custom hook when several agents use the same setup:

```tsx theme={null}
import { useTool } from "@opencomputer/agent";

function useGitHubResearch() {
  useTool("github-search");
  return "Check GitHub before making claims about repositories or issues.";
}

export default function Agent() {
  const githubInstructions = useGitHubResearch();
  return `Research the request carefully. ${githubInstructions}`;
}
```

Custom hooks keep agent functions readable and make capability bundles
reusable. Prefix them with `use` so their purpose is obvious.

## Next steps

* [Read and route inputs](/agents/inputs)
* [Choose a model](/agents/models)
* [Give the agent tools](/agents/tools)
* [Connect an MCP server](/agents/mcp)
* [Add reusable skills](/agents/skills)


# Inputs
Source: https://docs.opencomputer.dev/agents/inputs

Read text, structured payloads, and input sources with useInput

`useInput()` reads the input that caused the current agent render. Use it to
include the current request in the instructions or change behavior based on
where the request came from.

```tsx theme={null}
import { useInput } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  return input.text
    ? `Help the user with this request: ${input.text}`
    : "Help the user with their request.";
}
```

`useCurrentInput()` is an alias for `useInput()`.

## Input shape

```ts theme={null}
interface AgentInput {
  readonly source: InputSource;
  readonly text?: string;
  readonly payload?: DataValue;
}
```

| Field     | Meaning                                               |
| --------- | ----------------------------------------------------- |
| `source`  | How the work entered the session                      |
| `text`    | Optional human-readable message                       |
| `payload` | Optional structured JSON value supplied by the source |

`DataValue` means any JSON-compatible value: `null`, a boolean, number,
string, array, or object. Both `text` and `payload` are optional, so check them
before use.

## Adapt to the source

The current direct and delegated flows can share one agent definition:

```tsx theme={null}
import { useInput } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();

  return input.source === "subagent"
    ? "Complete the delegated task and return a concise result."
    : `Help with: ${input.text ?? "the current request"}`;
}
```

## Read structured payloads

Narrow or validate a payload before reading application-specific fields:

```tsx theme={null}
import { useInput } from "@opencomputer/agent";

type ResearchRequest = {
  topic?: string;
  depth?: "brief" | "deep";
};

export default function Agent() {
  const input = useInput();
  const request = (input.payload ?? {}) as ResearchRequest;

  if (request.topic) {
    return `Research ${request.topic} at ${request.depth ?? "brief"} depth.`;
  }

  return "Ask for a research topic before starting.";
}
```

Validate untrusted payloads in a tool before performing side effects.

## Input is not a prompt UI

`useInput()` only reads admitted input. It does not pause the session to ask a
person a question. The durable conversation and later messages are managed by
the [session](/agents/sessions).

Input payload also differs from [session data](/agents/session-data): a payload
belongs to the current input, while session data can persist across renders.


# Logs
Source: https://docs.opencomputer.dev/agents/logs

Inspect agent output and outbound-request activity from the OpenComputer CLI

OpenComputer collects agent output together with outbound-request events. Logs
are indexed by project, environment, agent, and session so you can
inspect failures from the project or CLI.

## Read the current agent's logs

From an initialized project:

```bash theme={null}
npx opencomputer logs
```

The CLI uses the local project binding and current agent automatically. Follow
new entries while developing:

```bash theme={null}
npx opencomputer logs --follow
```

## Filter logs

```bash theme={null}
npx opencomputer logs --agent hello-world --environment development
npx opencomputer logs --session <session-id>
npx opencomputer logs --limit 200
```

Use JSON Lines for scripts and log processors:

```bash theme={null}
npx opencomputer logs --follow --json
```

Each entry includes a stable cursor, timestamp, level, source, message, and
the applicable agent or session identifiers.

## Secret safety

Outbound-request logs describe the connection, method, destination path, status,
and timing. They do not contain injected secret values or secret-bearing
headers. Request headers that could override managed credentials are discarded
before the outbound request is sent.


# MCP servers
Source: https://docs.opencomputer.dev/agents/mcp

Attach managed HTTPS MCP servers with useMcpServer

MCP (Model Context Protocol) connects an agent to tools hosted by an external
service. Declare the server once with `defineMcpServer()`, then attach it to an
agent render with `useMcpServer()`.

## Connect a server

```tsx theme={null}
import {
  defineMcpServer,
  useMcpServer,
  useModel,
} from "@opencomputer/agent";

const docs = defineMcpServer({
  id: "company-docs",
  url: "https://mcp.example.com/server",
});

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  useMcpServer(docs);
  return "Answer questions using the company documentation when relevant.";
}
```

Managed MCP URLs must use HTTPS. OpenComputer connects to the server and makes
its tools available to the managed agent loop; agent code does not open or
close the connection itself.

## Definition fields

| Field        | Required | Purpose                                                    |
| ------------ | -------- | ---------------------------------------------------------- |
| `id`         | yes      | Stable ID for the server in the deployment                 |
| `url`        | yes      | HTTPS MCP endpoint                                         |
| `connection` | no       | Secret-backed HTTP connection used to authorize the server |

`useMcpServer()` accepts either a definition or an existing server ID.

## Attach authorization

Reference a secret-backed HTTP connection when the server requires
authorization:

```tsx theme={null}
import {
  bearer,
  defineConnection,
  defineMcpServer,
  useSecret,
  useMcpServer,
} from "@opencomputer/agent";

const github = defineConnection({
  id: "github-mcp-auth",
  origin: "https://api.githubcopilot.com",
  headers: {
    Authorization: bearer(useSecret("GITHUB_PAT")),
  },
});
const githubMcp = defineMcpServer({
  id: "github",
  url: "https://api.githubcopilot.com/mcp/",
  connection: github,
});

export default function Agent() {
  useMcpServer(githubMcp);
  return "Use GitHub tools to investigate repository questions.";
}
```

The declaration contains only a secret reference. Set the secret with
`opencomputer secrets set GITHUB_PAT`; its value is injected only into requests
to the declared origin. See [Secrets and outbound requests](/agents/secrets).

## Attach MCP conditionally

An agent can expose a server only when the current request needs it:

```tsx theme={null}
import { useInput, useMcpServer } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  if (input.text?.toLowerCase().includes("documentation")) {
    useMcpServer(docs);
  }
  return "Use company docs when that capability is available.";
}
```

Conditional attachment reduces the number of tools the model must choose from
on unrelated requests.

## MCP versus code-defined tools

Use [code-defined tools](/agents/tools) when you own the operation or need
custom validation and control. Use MCP when a service already publishes the
tools you need or when several agents should consume the same remote tool set.


# Models
Source: https://docs.opencomputer.dev/agents/models

Select a managed model with useModel

`useModel()` selects the model that powers the next agent step. OpenComputer
handles provider authentication and response streaming.

```tsx theme={null}
import { useModel } from "@opencomputer/agent";

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  return "You are a helpful assistant. Be concise and practical.";
}
```

`useModel()` is a declaration. It returns nothing and does not make a model
request itself.

## Model identifiers

Use a `provider/model` string:

```tsx theme={null}
useModel("anthropic/claude-sonnet-4.6");
```

The object form is equivalent:

```tsx theme={null}
useModel({
  provider: "anthropic",
  model: "claude-sonnet-4.6",
});
```

Keep model selection in agent code so development and immutable deployments
record the behavior together. Provider credentials are not added to source
bundles or client applications.

## Select a model conditionally

Because the agent re-renders for each model step, selection can respond to the
current input:

```tsx theme={null}
import { useInput, useModel } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  const needsDeepReview = input.text?.includes("deep review") ?? false;

  useModel(
    needsDeepReview
      ? "anthropic/claude-sonnet-4.6"
      : "anthropic/claude-haiku-4.5",
  );

  return needsDeepReview
    ? "Review the request carefully and explain important tradeoffs."
    : "Answer directly and briefly.";
}
```

Select one model for the next step and keep the choice predictable: model
changes affect cost, latency, context limits, and output behavior.

## Keep credentials out of agent code

Do not place provider API keys in `agent.ts`, tools, prompts, or the React
application. OpenComputer authenticates the selected provider without adding
the credential to agent code.

For credentials used by your own HTTP tools instead of model inference, use
[Secrets and outbound requests](/agents/secrets).


# Serverless Agents
Source: https://docs.opencomputer.dev/agents/overview

Define reactive agents in TypeScript and run them in the OpenComputer cloud

OpenComputer is a managed runtime for agents defined as code. A project can
contain several agents and optionally a React application that talks to them. You write
the behavior; OpenComputer manages development deployments, model execution,
tools, durable sessions, streaming, and production versions.

```tsx theme={null}
import { useInput, useModel } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  useModel("anthropic/claude-sonnet-4.6");

  return input.text
    ? `Help the user with this request: ${input.text}`
    : "You are a helpful assistant.";
}
```

The exported function is a reactive description of the agent. OpenComputer
renders it for the current input and uses its return value as instructions for
the managed agent loop. Hooks attach the model, tools, MCP servers, and
subagents needed for that render.

<CardGroup>
  <Card title="Projects" icon="folder" href="/agents/projects">
    Group multiple agents and a client application in one repository.
  </Card>

  <Card title="Reactive agents" icon="code" href="/agents/reactive-agents">
    Build agent behavior with a function and conditional hooks.
  </Card>

  <Card title="Cloud development" icon="cloud" href="/agents/development">
    Sync source directly to a managed development environment.
  </Card>

  <Card title="Sessions" icon="comments" href="/agents/sessions">
    Stream responses and inspect durable conversations.
  </Card>

  <Card title="Capabilities" icon="shapes" href="/agents/capabilities">
    Choose between tools, MCP servers, skills, and subagents.
  </Card>

  <Card title="Secrets" icon="key" href="/agents/secrets">
    Declare secret-backed connections without exposing credentials to agents.
  </Card>

  <Card title="Logs" icon="terminal" href="/agents/logs">
    Follow agent and outbound-request activity from the CLI.
  </Card>
</CardGroup>

## Start a project

```bash theme={null}
npm create @opencomputer/start@latest my-agent
cd my-agent
npm install
npx opencomputer login
npm run dev
```

The initializer asks whether to include a React SPA. The first `npm run dev`
lets you create a cloud project or select an existing one, prints its dashboard
URL, and syncs every configured agent to `development`. When a SPA exists, the
same command also starts it locally.

<Note>
  There is no local agent server. An optional React app runs locally, while
  agent code runs in OpenComputer's managed development cloud.
</Note>

## What is available today

* TypeScript projects containing one or more agents
* reactive instructions, model selection, tools, subagents, MCP
  servers, input metadata, and session data reads
* cloud development with file watching and automatic synchronization
* an optional React client using `@opencomputer/react` for streaming and
  multi-turn session reuse
* dashboard and CLI playground sessions
* immutable deployments promoted through aliases such as `production`
* project-level secrets with optional agent overrides and constrained outbound requests
* indexed runtime and egress logs available from the CLI

Agent behavior belongs in the repository under `opencomputer/`. The dashboard
is primarily for selecting environments, testing agents, and inspecting what
was deployed.


# Playground and debugging
Source: https://docs.opencomputer.dev/agents/playground

Test deployments and inspect what the agent received for each turn

The agent playground is the fastest way to test a cloud deployment without
building a client. Open a project, choose an environment and agent, then create
a session.

## Select the correct target

The project header selects `development` or `production`. Projects with
multiple agents have a separate agent selector in the playground. A session
keeps the deployment selected when it starts.

Create a new session after changing the target when you want an isolated test.
Resume an existing session when you want to verify multi-turn behavior.

## Use the debug inspector

The inspector shows the information needed to explain a turn:

* deployment and session identifiers
* rendered agent instructions
* selected model
* tools and MCP capabilities available to that render
* tool activity and errors

OpenComputer's private platform instructions and credentials are intentionally
not shown. The inspector describes your deployed agent configuration, not the
internal execution implementation.

## Follow runtime logs

Use the CLI when a failure needs more detail:

```bash theme={null}
npx opencomputer logs --follow
npx opencomputer logs --session <session-id>
```

See [Logs](/agents/logs) for filters and JSON output.


# Projects and agents
Source: https://docs.opencomputer.dev/agents/projects

Organize multiple cloud agents and a React application

A project is the cloud boundary for related agents, environments, deployments,
and sessions. A source repository contains the project's agent definitions and
the application that interacts with them.

## Project structure

The starter is intentionally small:

```text theme={null}
my-agent/
├── opencomputer/
│   ├── .env.example
│   ├── project.ts
│   └── agents/
│       └── hello-world/
│           ├── agent.ts
│           ├── tools/       # optional
│           └── skills/      # optional
├── src/
│   ├── App.tsx
│   └── main.tsx
├── package.json
└── vite.config.ts
```

* `opencomputer/project.ts` declares project metadata and agent IDs.
* `opencomputer/agents/<id>/agent.ts` defines one agent.
* `opencomputer/.env.local` optionally holds ignored development secrets.
* `src/` is a normal React application.
* `.opencomputer/` is ignored local state created by the CLI.

Add source files only when the project uses them. The starter does not generate
placeholder capability directories.

## Create or select the cloud project

The source scaffold and cloud project are separate. `npm create` writes local
source. Link it to a cloud project with:

```bash theme={null}
npx opencomputer link
```

The command asks whether to create a project or select an existing one. If you
skip it, the first project-scoped command shows the same prompt.

For non-interactive use:

```bash theme={null}
npx opencomputer dev --project <project-id-or-slug>
npx opencomputer dev --create-project "Support agents"
```

Later commands reuse `.opencomputer/project.json`. Run `opencomputer link`
again when you intentionally want this source directory to target another
project.

## Add another agent

Create a new agent module:

```text theme={null}
opencomputer/agents/researcher/agent.ts
```

```tsx theme={null}
import { useModel } from "@opencomputer/agent";

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  return "Research the request, verify claims, and cite useful sources.";
}
```

Then list it in `opencomputer/project.ts`:

```tsx theme={null}
export default {
  name: "Customer workspace",
  agents: ["hello-world", "researcher"],
};
```

The running development process synchronizes both agents. In the dashboard,
the project-level environment selector switches between `development` and
`production`; the playground has a separate agent selector.

## Inspect the project

The current project dashboard provides:

* **Agent playground** for creating and resuming test sessions
* **Deployments** for immutable version history and active aliases
* **Sessions** created through the dashboard, React client, or API
* **Secrets** for write-only project and agent credentials

Project and agent behavior remains code-owned. The dashboard is for selection,
inspection, and testing. Use `opencomputer logs` to diagnose agent and
outbound-request failures.


# Quickstart
Source: https://docs.opencomputer.dev/agents/quickstart

Create an agent project and sync it to Development (Cloud)

## Prerequisites

* Node.js 22 or newer
* an OpenComputer account

## 1. Create the app

```bash theme={null}
npm create @opencomputer/start@latest my-agent
cd my-agent
npm install
```

Use `.` instead of `my-agent` to initialize an empty current directory.
The initializer asks whether to create agent code only or include a React SPA.

## 2. Log in

```bash theme={null}
npx opencomputer login
```

The CLI opens the OpenComputer device-login flow and stores the login locally.
The production API at `https://app.opencomputer.dev` is used by default.

## 3. Start cloud development

```bash theme={null}
npm run dev
```

On the first run, choose an existing cloud project or create a new one. The
process prints the project dashboard URL, watches `opencomputer/`, and syncs
changes to `development`. If you included the SPA, the same command starts
Vite; open its URL and send a message.

<Warning>
  Keep `npm run dev` running while using the React app. The authenticated
  development bridge exists only for the lifetime of that process.
</Warning>

## 4. Change the agent

Edit `opencomputer/agents/hello-world/agent.ts`:

```tsx theme={null}
import { useInput, useModel } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  useModel("anthropic/claude-sonnet-4.6");

  return `Be concise and practical. Current request: ${input.text ?? "none"}`;
}
```

Saving the file publishes a new development deployment. Start a new playground
or client session to test it; an existing session keeps the deployment it
started with.

See [Cloud development](/agents/development) for project selection, automatic
secret synchronization, and the full development lifecycle.

## 5. Deploy to production

```bash theme={null}
npm run deploy -- --alias production
```

The command builds an immutable deployment and advances the `production`
alias. Development remains available for subsequent edits.

See [Deployments and environments](/agents/deployments) for aliases and
version history.

<CardGroup>
  <Card title="Projects" icon="folder" href="/agents/projects">
    Add more agents and understand project bindings.
  </Card>

  <Card title="Reactive agents" icon="code" href="/agents/reactive-agents">
    Add models, tools, MCP servers, and subagents.
  </Card>
</CardGroup>


# React integration
Source: https://docs.opencomputer.dev/agents/react

Stream agent sessions from a React application with useAgent

Projects created with the React option use `@opencomputer/react`. The package
owns session creation, multi-turn reuse, and streamed assistant messages.

```tsx theme={null}
import { useAgent } from "@opencomputer/react";

export default function Chat() {
  const { messages, send, sessionId, isRunning, error } = useAgent(
    "hello-world@development",
  );

  return (
    <main>
      {messages.map((message) => (
        <p key={message.id}>
          <strong>{message.role}:</strong> {message.text}
        </p>
      ))}
      <button
        disabled={isRunning}
        onClick={() => void send("Hello")}
      >
        Send
      </button>
      {sessionId ? <small>Session: {sessionId}</small> : null}
      {error ? <p role="alert">{error}</p> : null}
    </main>
  );
}
```

## Hook result

| Value        | Purpose                                                       |
| ------------ | ------------------------------------------------------------- |
| `messages`   | User and assistant messages accumulated by this hook instance |
| `send(text)` | Starts or continues the session and streams the response      |
| `sessionId`  | Current cloud session after the first message                 |
| `isRunning`  | Whether a turn is active                                      |
| `error`      | Most recent request error                                     |

## Select the target

Pass `agent-id@alias` to choose the agent and environment:

```tsx theme={null}
useAgent("support@development");
useAgent("support@production");
```

An options object can also set the input source, API base path, or fetch
implementation:

```tsx theme={null}
useAgent({
  agent: "support@development",
  source: "customer-portal",
});
```

## Development

Keep `npm run dev` running while using the local application. It starts Vite
and provides the authenticated development bridge; credentials are not bundled
into browser code.

For the durable conversation model, see [Sessions and turns](/agents/sessions).


# Reactive agents
Source: https://docs.opencomputer.dev/agents/reactive-agents

Render instructions and capabilities from the current input

An agent is a synchronous TypeScript function that returns instructions. The
OpenComputer runtime owns the durable conversation, streaming model calls,
tool loop, and continuation. Your function calculates the agent configuration
for the current render.

```tsx theme={null}
export default function Agent() {
  return "You are a helpful assistant.";
}
```

This keeps ordinary TypeScript control flow available. Hooks may be called
conditionally, so a capability can be attached only when the current request
needs it.

## Hooks

| Hook                   | Current value or effect                                         |
| ---------------------- | --------------------------------------------------------------- |
| `useInput()`           | Reads the current source, text, and optional structured payload |
| `useCurrentInput()`    | Alias for `useInput()`                                          |
| `useModel(model)`      | Selects a model using `provider/model` notation                 |
| `useTool(tool)`        | Makes a named or code-defined tool available                    |
| `useSubagent(agent)`   | Makes another project agent available as a subagent             |
| `useMcpServer(server)` | Attaches a managed HTTPS MCP server                             |
| `useSessionData(key)`  | Reads a value previously stored in the current session          |

`useInput()` is not a human-in-the-loop prompt. It describes the input that
caused the current render. See [Inputs](/agents/inputs) for its text, payload,
and source metadata.

## Conditional configuration

```tsx theme={null}
import {
  useInput,
  useModel,
  useSubagent,
  useTool,
} from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  useModel("anthropic/claude-sonnet-4.6");

  if (input.text?.includes("research")) {
    useTool("web-search");
    useSubagent("researcher");
  }

  return "Answer directly. Research and verify when those capabilities exist.";
}
```

The hook calls describe capabilities for the next model step; they do not run
the model or tool themselves.

## Define a tool

Tools are TypeScript values with JSON Schema inputs and an asynchronous or
synchronous `run` function. Put the implementation beside the agent, for
example at `opencomputer/agents/hello-world/tools/hacker-news.ts`:

```tsx theme={null}
import { defineTool } from "@opencomputer/agent";

export const latestStories = defineTool({
  name: "latest_hacker_news_stories",
  description: "Fetch the current top Hacker News stories",
  input: {
    type: "object",
    properties: { limit: { type: "number" } },
  },
  async run({ input, signal, reportProgress }) {
    await reportProgress({ status: "fetching" });
    const limit = Number(input.limit ?? 10);
    const ids = await fetch(
      "https://hacker-news.firebaseio.com/v0/topstories.json",
      { signal },
    ).then((response) => response.json() as Promise<number[]>);
    return ids.slice(0, limit);
  },
});
```

Import and attach it from `agent.ts`:

```tsx theme={null}
import { useTool } from "@opencomputer/agent";
import { latestStories } from "./tools/hacker-news";

export default function Agent() {
  useTool(latestStories);
  return "Use the Hacker News tool when the user asks for current stories.";
}
```

Tool names may contain letters, numbers, underscores, and hyphens. Tool code
runs in the managed agent runtime, not in the browser.

## Skills

Skills are reusable instruction bundles. Add a skill only when an agent needs
one:

```text theme={null}
opencomputer/agents/hello-world/skills/code-review/SKILL.md
```

Skills in an agent's `skills/` directory are packaged with that agent and can
be loaded by the runtime when their description matches the task. Unlike
tools, skills provide instructions and supporting resources rather than a
callable JSON Schema function.

## Models

Use `provider/model` strings:

```tsx theme={null}
useModel("anthropic/claude-sonnet-4.6");
```

An object form is also supported:

```tsx theme={null}
useModel({ provider: "anthropic", model: "claude-sonnet-4.6" });
```

Provider credentials are managed by OpenComputer and are not placed in agent
source or the React application.

Continue with [Agent hooks](/agents/hooks), then use the focused guides for
[inputs](/agents/inputs), [models](/agents/models), [tools](/agents/tools),
[MCP servers](/agents/mcp), [skills](/agents/skills),
[subagents](/agents/subagents), and [session data](/agents/session-data).


# Secrets and outbound requests
Source: https://docs.opencomputer.dev/agents/secrets

Use project and agent secrets without exposing values to agent runtimes

OpenComputer secrets are write-only values used by declared outbound
connections. Plaintext values are not included in source bundles, prompts,
deployment manifests, runtime environment variables, logs, or API responses.

## Declare a connection

```tsx theme={null}
import {
  bearer,
  defineConnection,
  useSecret,
} from "@opencomputer/agent";

const github = defineConnection({
  id: "github-api",
  origin: "https://api.github.com",
  methods: ["GET"],
  pathPrefix: "/repos/",
  headers: {
    Authorization: bearer(useSecret("GITHUB_TOKEN")),
  },
});

export default function Agent() {
  return "Use GitHub when it helps answer the request.";
}
```

The origin must use HTTPS. OpenComputer rejects hard-coded sensitive headers
such as `Authorization`, `Cookie`, and `X-API-Key`; reference a managed secret
instead.

Tools can make requests through the same connection:

```tsx theme={null}
const response = await github.fetch("/repos/opencomputer/example");
const repository = await response.json();
```

Only a relative path is accepted. OpenComputer checks the declared origin,
path prefix, method, agent, and environment before sending the outbound
request.

## Synchronize development secrets

Place development-only values in `opencomputer/.env.local`:

```dotenv theme={null}
GITHUB_TOKEN=github_pat_...
```

When `npm run dev` starts, the CLI considers only names referenced by
`useSecret()` in a `defineConnection()` declaration. It infers the allowed
origins from those declarations and asks before uploading each newly discovered
secret. Changed values are synchronized while the development process is
running.

Variables without a matching declaration are skipped. OpenComputer never
grants an unmatched value access to every host, and removing a local variable
does not delete its cloud value. Use `opencomputer secrets remove` when deletion
is intentional. The starter ignores `opencomputer/.env.local` and includes an
`opencomputer/.env.example` file for documenting required names without values.

## Set a project secret

Secrets belong to a cloud project. If the app is not linked yet, this command
first asks you to select or create one, then continues setting the secret.

```bash theme={null}
npx opencomputer secrets set GITHUB_TOKEN
```

The CLI reads the value from a hidden prompt. When run from an initialized
project it can infer allowed origins from connections that reference the
secret. For CI, provide the value through standard input rather than a command
argument.

Project secrets are available to declared connections in every agent in the
project. Create an agent-specific override when one agent needs a different
credential:

```bash theme={null}
npx opencomputer secrets set GITHUB_TOKEN --agent current
```

Secrets are separate for `development` and `production`:

```bash theme={null}
npx opencomputer secrets set GITHUB_TOKEN --environment production
npx opencomputer secrets list --environment development
npx opencomputer secrets remove GITHUB_TOKEN --environment development
```

List output contains metadata such as the name, scope, environment, and
allowed origins. Secret values are never returned.

## Security guarantees

OpenComputer resolves the declared connection and scoped secret for each
request. The credential is attached only after the destination, method, path,
agent, project, and environment have been validated. The value is never added
to the agent's source bundle, prompt, browser application, or logs.


# Session data
Source: https://docs.opencomputer.dev/agents/session-data

Read durable per-session values with useSessionData

`useSessionData()` reads structured data associated with the current durable
session. Use it for application context that should influence later renders,
such as a campaign name, locale, audience, or workflow phase.

```tsx theme={null}
import { useSessionData } from "@opencomputer/agent";

export default function Agent() {
  const campaign = useSessionData<string>("campaign_name");
  const audience = useSessionData<string>("audience");

  return [
    "Help plan the campaign.",
    campaign ? `Campaign: ${campaign}.` : undefined,
    audience ? `Audience: ${audience}.` : undefined,
  ]
    .filter(Boolean)
    .join(" ");
}
```

## Read a value

The key is a string. Pass a TypeScript type argument for the expected value:

```tsx theme={null}
const locale = useSessionData<string>("locale");
const approved = useSessionData<boolean>("brief_approved");
const tags = useSessionData<readonly string[]>("tags");
```

The hook returns `undefined` when the key is absent. Handle that case rather
than assuming every session has been initialized.

Values must be JSON-compatible: `null`, booleans, numbers, strings, arrays,
and objects containing those values.

## Configure capabilities from session data

Because session data is available during render, it can control instructions
and resource hooks:

```tsx theme={null}
import { useSessionData, useTool } from "@opencomputer/agent";
import { publishCampaign } from "./tools/publish-campaign";

export default function Agent() {
  const approved = useSessionData<boolean>("brief_approved") ?? false;

  if (approved) {
    useTool(publishCampaign);
  }

  return approved
    ? "The brief is approved. Publishing is available when the user asks."
    : "Draft and revise the brief. Do not publish it yet.";
}
```

## Session data versus input

`useInput().payload` belongs to the current admitted input. Session data is
associated with the durable session and can be read again on later renders.
Use input for the event that just arrived and session data for context that
outlives that event.

## Current write behavior

The current `@opencomputer/agent` API exposes session data as a read-only
snapshot. It does not yet include a hook for setting or updating a value from
agent code. Code should treat the returned value as immutable.

See [Sessions and turns](/agents/sessions) for the durable conversation
lifecycle and [Exa research session](/agents/examples/exa-research-session)
for a starter that continues follow-up questions in one session.


# Sessions and turns
Source: https://docs.opencomputer.dev/agents/sessions

Understand durable conversations and multi-turn agent work

A session is a durable conversation with a deployed agent. Each turn appends
input and streamed runtime events to the session, allowing clients to resume a
conversation without rebuilding its history locally.

## React

When you select the React SPA, the starter imports `useAgent()` from
`@opencomputer/react`. The hook exposes:

* `messages` — accumulated user and assistant messages
* `send(text)` — create a session if necessary and stream the next turn
* `isRunning` — whether a turn is active
* `error` — the latest request error

The hook accepts an agent selector such as `hello-world@development`. Build
additional UI and application hooks around its session state as needed.

## Agent playground

Open a project in the dashboard and choose **Agent playground**. Select the
agent and environment independently, then create a new session or resume a
previous playground session.

Playground sessions stay in the playground list. Sessions started through an
API appear under **Sessions**, where their durable turn history can be
inspected.

See [Playground and debugging](/agents/playground) for target selection and the
debug inspector.

## CLI

Start an interactive session against the development agent:

```bash theme={null}
npm run session
```

Or manage remote sessions explicitly:

```bash theme={null}
npx opencomputer session create "Draft a response" --remote \
  --agent hello-world@development
npx opencomputer session list
npx opencomputer session inspect <session-id>
npx opencomputer session attach <session-id>
npx opencomputer session send <session-id> "Continue"
npx opencomputer session end <session-id>
```

Use `--keep` on supported commands when the session should remain active after
the command exits.

## Input sources

Inside an agent, `useInput().source` identifies how the current work arrived.
This lets the same agent distinguish direct work from delegated subagent work
without defining another session type.


# Skills
Source: https://docs.opencomputer.dev/agents/skills

Package reusable instructions and supporting resources with an agent

A skill is a reusable instruction bundle that teaches an agent how to perform
a task. A tool executes code; a skill provides a procedure, checklist, or
domain playbook the agent can load when relevant.

## Create a skill

Add a directory containing `SKILL.md` under the agent:

```text theme={null}
opencomputer/agents/campaign-writer/
├── agent.ts
└── skills/
    └── campaign-brief/
        ├── SKILL.md
        └── CHECKLIST.md
```

Write a clear name and routing description in the frontmatter, then put the
full procedure in the body:

```md theme={null}
---
name: campaign-brief
description: Create a sourced campaign brief. Use when planning a new campaign or revising its audience and messaging.
---

# Campaign brief

1. Restate the product, audience, goal, and constraints.
2. Research the audience before proposing messaging.
3. Separate sourced facts from recommendations.
4. Produce a positioning statement, three message pillars, and five concepts.
5. Read `CHECKLIST.md` before returning the final brief.
```

The description should say both what the skill does and when it applies. The
agent uses it to decide whether to load the instructions.

## Use the skill

Skills do not need a hook. OpenComputer packages the entire `skills/` directory
with that agent, which can load a matching skill during the session.

Tell the agent when the skill should guide its work:

```tsx theme={null}
export default function Agent() {
  return [
    "Plan and improve marketing campaigns.",
    "For a new campaign brief, use the campaign-brief skill and follow its checklist.",
  ].join(" ");
}
```

## Add supporting files

Keep the core procedure in `SKILL.md`. Put longer material beside it:

```text theme={null}
campaign-brief/
├── SKILL.md
├── CHECKLIST.md
├── VOICE.md
└── examples/
    └── launch-brief.md
```

Reference those files from `SKILL.md` so the agent knows when to read them.
Supporting files are deployed with the skill and need no imports from
`agent.ts`.

## Scope skills to an agent

Skills live under `opencomputer/agents/<agent-id>/skills/`, so each deployment
receives only its own skill set. To reuse a skill, copy or generate the skill
directory into each agent that needs it.

## Skills versus tools

| Skill                                 | Tool                              |
| ------------------------------------- | --------------------------------- |
| Markdown instructions and resources   | Executable TypeScript             |
| Teaches a repeatable workflow         | Performs a specific operation     |
| Loaded when its description matches   | Called with JSON Schema arguments |
| May tell the agent which tools to use | Produces a JSON-compatible result |

Many useful workflows combine both: a research skill explains the process
while an [Exa search tool](/agents/examples/exa-research-session) retrieves
current sources.


# Subagents
Source: https://docs.opencomputer.dev/agents/subagents

Let an agent delegate focused work with useSubagent

A subagent is another agent in the same project that can take a focused task.
Use `useSubagent()` to make that agent available to the current render.

## Add the specialist

Create a second agent:

```tsx theme={null}
// opencomputer/agents/researcher/agent.ts
import { useModel, useTool } from "@opencomputer/agent";

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  useTool("web-search");
  return "Research the delegated question. Return sourced findings only.";
}
```

Register both agents in the project:

```tsx theme={null}
// opencomputer/project.ts
export default {
  name: "Campaign workspace",
  agents: ["campaign-planner", "researcher"],
};
```

## Expose it with `useSubagent`

```tsx theme={null}
// opencomputer/agents/campaign-planner/agent.ts
import { useModel, useSubagent } from "@opencomputer/agent";

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  useSubagent("researcher");
  return [
    "Plan the campaign from evidence.",
    "Delegate audience and competitor research to the researcher.",
  ].join(" ");
}
```

The value passed to `useSubagent()` is the agent ID from
`opencomputer/project.ts`. Give the parent clear instructions about what it
should delegate and what result it expects.

Inputs created by delegation have `useInput().source === "subagent"`, so the
specialist can adapt its response:

```tsx theme={null}
import { useInput } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  return input.source === "subagent"
    ? "Complete only the delegated research task and return concise findings."
    : "Help the user research their question.";
}
```

## Attach conditionally

Like other resource hooks, `useSubagent()` can be conditional:

```tsx theme={null}
const input = useInput();
if (input.text?.includes("research")) {
  useSubagent("researcher");
}
```

This keeps the delegate unavailable for requests where it adds no value.


# Tools
Source: https://docs.opencomputer.dev/agents/tools

Define TypeScript tools and expose them with useTool

A tool is TypeScript code the model may call while it works. Use tools for
actions such as searching an API, looking up an order, or updating an external
system. The model decides when a tool fits; your `run` function controls what
happens.

## Define your first tool

Create a tool beside the agent, for example
`opencomputer/agents/support/tools/lookup-order.ts`:

```tsx theme={null}
import { defineTool } from "@opencomputer/agent";

export const lookupOrder = defineTool({
  name: "lookup_order",
  description: "Look up an order by ID and return its current status",
  input: {
    type: "object",
    properties: {
      orderId: { type: "string", description: "The customer order ID" },
    },
    required: ["orderId"],
    additionalProperties: false,
  },
  async run({ input }) {
    const orderId = String(input.orderId);
    return { orderId, status: "processing" };
  },
});
```

Then attach it from `agent.ts`:

```tsx theme={null}
import { useModel, useTool } from "@opencomputer/agent";
import { lookupOrder } from "./tools/lookup-order";

export default function Agent() {
  useModel("anthropic/claude-sonnet-4.6");
  useTool(lookupOrder);
  return "Help customers check orders. Ask for an order ID before lookup.";
}
```

The model sees the tool's name, description, and input schema. When it calls
the tool, OpenComputer runs `run()` in the managed agent runtime and returns
the result to the model.

## Tool definition

| Field         | Required | Purpose                                                             |
| ------------- | -------- | ------------------------------------------------------------------- |
| `name`        | yes      | ID the model calls; letters, numbers, underscores, and hyphens only |
| `description` | yes      | Explains what the tool does and when to use it                      |
| `input`       | no       | JSON Schema for tool arguments                                      |
| `output`      | no       | JSON Schema describing the result                                   |
| `run`         | yes      | Synchronous or asynchronous implementation                          |

Descriptions are the model's documentation. Include the action, when it is
appropriate, and any important precondition.

## Execution context

The `run` function receives:

| Value                      | Purpose                                         |
| -------------------------- | ----------------------------------------------- |
| `input`                    | Arguments created for the tool call             |
| `sessionId`                | Current session ID                              |
| `messageId`                | Message containing the tool call                |
| `agentId`                  | Agent executing the call                        |
| `signal`                   | Optional cancellation signal for abortable work |
| `reportProgress(metadata)` | Emits JSON-compatible progress metadata         |

Use the cancellation signal with `fetch()` and report progress before slow
steps:

```tsx theme={null}
export const importCatalog = defineTool({
  name: "import_catalog",
  description: "Import the latest product catalog; use only when asked",
  async run({ signal, reportProgress }) {
    await reportProgress({ phase: "downloading" });
    const response = await fetch("https://example.com/catalog.json", { signal });
    await reportProgress({ phase: "processing" });
    return { imported: response.ok };
  },
});
```

Tool results and progress metadata must be JSON-compatible values.

## Conditional tools

`useTool()` may be conditional. This keeps sensitive or specialized actions
out of the tool set until they are relevant:

```tsx theme={null}
import { useInput, useTool } from "@opencomputer/agent";
import { issueRefund } from "./tools/issue-refund";

export default function Agent() {
  const input = useInput();

  if (input.text?.toLowerCase().includes("refund")) {
    useTool(issueRefund);
  }

  return "Resolve the support request. Confirm the order before a refund.";
}
```

`useTool()` also accepts a tool ID such as `useTool("web-search")` when the
runtime already provides that tool.

## Call external APIs safely

Do not embed API keys in a tool or read them from the runtime environment.
Declare an HTTP connection, store the value as an OpenComputer secret, and
call the connection's `fetch()` method. See
[Secrets and outbound requests](/agents/secrets) for a complete example.

## Tools versus skills and MCP

* A tool executes TypeScript you own.
* A [skill](/agents/skills) teaches the agent a reusable procedure.
* An [MCP server](/agents/mcp) supplies a remote collection of tools.


# Create Reservation
Source: https://docs.opencomputer.dev/api-reference/capacity/create-reservations

POST /api/capacity/reservations

Commit capacity across one or more 15-minute UTC intervals in a single
atomic write. The result is one reservation event with a server-generated
`reservationId` covering all intervals in the request. See
[Reserving capacity](/reserved-capacity/reserving) for the full write
contract.

Send an `Idempotency-Key` header so retries return the original result.
Same key with a different body returns `idempotency_key_conflict`.

Reservations are non-refundable — there is no cancellation, modification,
or transfer.

<ParamField type="array">
  One entry per 15-minute interval to reserve.
</ParamField>

<ParamField type="string">
  Interval start. RFC 3339, UTC, aligned to 15 minutes (`:00`, `:15`, `:30`, `:45`).
</ParamField>

<ParamField type="string">
  Interval end. Must equal `startsAt + 15 minutes`. Multi-interval spans are rejected.
</ParamField>

<ParamField type="integer">
  Positive multiple of 4 (the grain is 1 GB-hour = 4 GB × 15 min). Other
  values are rejected.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
    "createdAt": "2026-04-28T18:00:05Z",
    "intervals": [
      {
        "startsAt": "2026-04-29T02:00:00Z",
        "endsAt":   "2026-04-29T02:15:00Z",
        "capacityGb": 16
      },
      {
        "startsAt": "2026-04-29T02:15:00Z",
        "endsAt":   "2026-04-29T02:30:00Z",
        "capacityGb": 16
      }
    ]
  }
  ```

  ```json 409 capacity_not_available theme={null}
  {
    "error": "capacity_not_available",
    "intervals": [
      {
        "startsAt": "2026-04-29T02:00:00Z",
        "requestedGb": 80,
        "reservableGb": 28,
        "reason": "insufficient_capacity"
      }
    ]
  }
  ```
</ResponseExample>


# Get Calendar
Source: https://docs.opencomputer.dev/api-reference/capacity/get-calendar

GET /api/capacity/calendar

Return a planning snapshot of 15-minute UTC intervals in the requested window.
One row per interval with current `reservedGb`, `reservableGb`, and the
per-org `reservationLimitGb`. See
[Reading the calendar](/reserved-capacity/calendar) for field semantics.

<ParamField type="string">
  Window start. RFC 3339, aligned to 15 minutes, UTC.
</ParamField>

<ParamField type="string">
  Window end. RFC 3339, aligned to 15 minutes, UTC.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "from":      "2026-04-29T02:00:00Z",
    "to":        "2026-04-29T04:00:00Z",
    "resource":  "memory_gb",
    "intervals": [
      {
        "startsAt": "2026-04-29T02:00:00Z",
        "endsAt":   "2026-04-29T02:15:00Z",
        "reservationLimitGb": 300,
        "reservedGb": 80,
        "reservableGb": 220
      }
    ]
  }
  ```
</ResponseExample>


# List Reservations
Source: https://docs.opencomputer.dev/api-reference/capacity/list-reservations

GET /api/capacity/reservations

Return reservation events made by the authenticated org, in
reverse-chronological order by `createdAt`. Each reservation row includes
all the intervals it committed to. Useful for end-of-month reconciliation
and audit.

<ParamField type="string">
  Return reservations whose `createdAt >= from`. RFC 3339, UTC.
</ParamField>

<ParamField type="string">
  Return reservations whose `createdAt < to`. RFC 3339, UTC.
</ParamField>

<ParamField type="string">
  Pagination cursor from a previous response's `nextCursor`.
</ParamField>

<ParamField type="integer">
  Maximum reservations per page. Server-defined ceiling applies.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "from": "2026-04-01T00:00:00Z",
    "to":   "2026-05-01T00:00:00Z",
    "reservations": [
      {
        "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
        "createdAt": "2026-04-28T18:00:05Z",
        "intervals": [
          {
            "startsAt": "2026-04-29T02:00:00Z",
            "endsAt":   "2026-04-29T02:15:00Z",
            "capacityGb": 16
          },
          {
            "startsAt": "2026-04-29T02:15:00Z",
            "endsAt":   "2026-04-29T02:30:00Z",
            "capacityGb": 16
          }
        ]
      }
    ],
    "nextCursor": null
  }
  ```
</ResponseExample>


# Create Checkpoint
Source: https://docs.opencomputer.dev/api-reference/checkpoints/create

POST /api/sandboxes/{id}/checkpoints

Create a checkpoint of the sandbox state. Each sandbox can have up to 10 full
checkpoints and up to 100 disk-only checkpoints. By default, creating past the
limit for that checkpoint type returns an error. Set `retentionPolicy.mode` to
`delete_oldest` to delete the oldest eligible checkpoint of the same type first
so the new checkpoint can be created.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Checkpoint name (unique per sandbox)
</ParamField>

<ParamField type="string">
  Checkpoint type. Use `full` to preserve disk, memory, and CPU state, or
  `disk_only` to preserve only disk state with a larger per-sandbox limit.
</ParamField>

<ParamField type="object">
  Optional retention policy. Use `{ "mode": "delete_oldest", "maxCount": 10 }`
  for full checkpoints or `{ "mode": "delete_oldest", "maxCount": 100 }` for
  disk-only checkpoints to delete the oldest eligible checkpoint of the same
  type before creating a new one.
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "cp-abc123",
    "sandboxID": "sb-abc123",
    "name": "before-migration",
    "status": "processing",
    "sizeBytes": 0,
    "createdAt": "2025-01-15T10:30:00Z"
  }
  ```
</ResponseExample>


# Delete Checkpoint
Source: https://docs.opencomputer.dev/api-reference/checkpoints/delete

DELETE /api/sandboxes/{id}/checkpoints/{checkpointId}

Delete a checkpoint.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Checkpoint ID
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# Fork from Checkpoint
Source: https://docs.opencomputer.dev/api-reference/checkpoints/fork

POST /api/sandboxes/from-checkpoint/{checkpointId}

Create a new sandbox from a checkpoint.

<ParamField type="string">
  Checkpoint ID
</ParamField>

<ParamField type="integer">
  Idle timeout for the new sandbox (default: `300`)
</ParamField>

<ParamField type="object">
  Environment variables to override on the fork. Keys that match the checkpoint's stored envs are replaced; new keys are added.
</ParamField>

<ParamField type="string">
  Name of a secret store to attach. If the checkpoint already has a store, secrets are merged — the new store's values win on collision and egress allowlists are aggregated.
</ParamField>

<ParamField type="integer">
  Memory for the forked sandbox, in MB. Clamped to a valid range: the floor is the checkpoint's own memory (a fork can't start smaller than the snapshot it restores, so a smaller value is ignored) and the ceiling is 16384 (16 GB; larger values are capped). The `memoryMB` field in the response reports the effective value after clamping.
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "sandboxID": "sb-def456",
    "status": "running",
    "region": "use2",
    "workerID": "w-use2-abc123",
    "memoryMB": 4096
  }
  ```
</ResponseExample>


# List Checkpoints
Source: https://docs.opencomputer.dev/api-reference/checkpoints/list

GET /api/sandboxes/{id}/checkpoints

List all checkpoints for a sandbox.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "cp-abc123",
      "sandboxID": "sb-abc123",
      "name": "before-migration",
      "status": "ready",
      "sizeBytes": 134217728,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
  ```
</ResponseExample>


# Restore Checkpoint
Source: https://docs.opencomputer.dev/api-reference/checkpoints/restore

POST /api/sandboxes/{id}/checkpoints/{checkpointId}/restore

Revert the sandbox in-place to a checkpoint. All changes since the checkpoint are lost.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Checkpoint ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {}
  ```
</ResponseExample>


# Create Exec Session
Source: https://docs.opencomputer.dev/api-reference/exec/create-session

POST /api/sandboxes/{id}/exec

Start a long-running command as a session. Attach via WebSocket to stream I/O.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Command to execute
</ParamField>

<ParamField type="string[]">
  Command arguments
</ParamField>

<ParamField type="object">
  Environment variables
</ParamField>

<ParamField type="string">
  Working directory
</ParamField>

<ParamField type="integer">
  Timeout in seconds
</ParamField>

<ParamField type="integer">
  Seconds to keep running after all clients disconnect
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "sessionID": "es-abc123",
    "sandboxID": "sb-abc123",
    "command": "node",
    "args": ["server.js"],
    "running": true,
    "exitCode": null,
    "startedAt": "2025-01-15T10:30:00Z",
    "attachedClients": 0
  }
  ```
</ResponseExample>


# Kill Exec Session
Source: https://docs.opencomputer.dev/api-reference/exec/kill-session

POST /api/sandboxes/{id}/exec/{sessionID}/kill

Kill an exec session.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Exec session ID
</ParamField>

<ParamField type="integer">
  Signal number (default: `9` / SIGKILL)
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# List Exec Sessions
Source: https://docs.opencomputer.dev/api-reference/exec/list-sessions

GET /api/sandboxes/{id}/exec

List all exec sessions for a sandbox.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "sessionID": "es-abc123",
      "sandboxID": "sb-abc123",
      "command": "node",
      "args": ["server.js"],
      "running": true,
      "exitCode": null,
      "startedAt": "2025-01-15T10:30:00Z",
      "attachedClients": 0
    }
  ]
  ```
</ResponseExample>


# Run Command
Source: https://docs.opencomputer.dev/api-reference/exec/run

POST /api/sandboxes/{id}/exec/run

Execute a command synchronously and return the result.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Command to execute
</ParamField>

<ParamField type="string[]">
  Command arguments
</ParamField>

<ParamField type="object">
  Environment variables
</ParamField>

<ParamField type="string">
  Working directory
</ParamField>

<ParamField type="integer">
  Timeout in seconds (default: `60`)
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "exitCode": 0,
    "stdout": "Hello, World!\n",
    "stderr": ""
  }
  ```
</ResponseExample>


# Delete File or Directory
Source: https://docs.opencomputer.dev/api-reference/files/delete

DELETE /api/sandboxes/{id}/files

Delete a file or directory.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Path to the file or directory to delete
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# Generate Download URL
Source: https://docs.opencomputer.dev/api-reference/files/generate-download-url

POST /api/sandboxes/{id}/files/download-url

Generates a signed URL for downloading a file without an API key. See [Signed URLs](/sandboxes/signed-urls) for usage guide.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Absolute path to the file
</ParamField>

<ParamField type="number">
  URL lifetime in seconds (max: 86400)
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "url": "https://app.opencomputer.dev/api/sandboxes/sb-xxx/files/download?path=%2Fapp%2Foutput.zip&expires=1773906434&signature=abc123",
    "expiresAt": "2025-01-01T01:00:00Z"
  }
  ```
</ResponseExample>


# Generate Upload URL
Source: https://docs.opencomputer.dev/api-reference/files/generate-upload-url

POST /api/sandboxes/{id}/files/upload-url

Generates a signed URL for uploading a file without an API key. See [Signed URLs](/sandboxes/signed-urls) for usage guide.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Absolute path for the destination file
</ParamField>

<ParamField type="number">
  URL lifetime in seconds (max: 86400)
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "url": "https://app.opencomputer.dev/api/sandboxes/sb-xxx/files/upload?path=%2Fapp%2Finput.csv&expires=1773906434&signature=abc123",
    "expiresAt": "2025-01-01T01:00:00Z"
  }
  ```
</ResponseExample>


# List Directory
Source: https://docs.opencomputer.dev/api-reference/files/list-directory

GET /api/sandboxes/{id}/files/list

List contents of a directory.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Directory path (default: `/`)
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
    { "name": "app", "isDir": true, "size": 4096, "path": "/app" },
    { "name": "README.md", "isDir": false, "size": 1234, "path": "/README.md" }
  ]
  ```
</ResponseExample>


# Create Directory
Source: https://docs.opencomputer.dev/api-reference/files/mkdir

POST /api/sandboxes/{id}/files/mkdir

Create a new directory.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Path for the new directory
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# Read File
Source: https://docs.opencomputer.dev/api-reference/files/read

GET /api/sandboxes/{id}/files

Returns file content as plain text (not JSON).

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Absolute path to the file
</ParamField>

<ResponseExample>
  ```text 200 theme={null}
  Hello, World!
  ```
</ResponseExample>


# Signed Download
Source: https://docs.opencomputer.dev/api-reference/files/signed-download

GET /api/sandboxes/{id}/files/download

Download a file using a signed URL. No authentication required — the signature and expiry are validated from query parameters.

Generate a signed URL first via [Generate Download URL](/api-reference/files/generate-download-url).

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Absolute path to the file
</ParamField>

<ParamField type="string">
  Unix timestamp when the URL expires
</ParamField>

<ParamField type="string">
  HMAC-SHA256 signature
</ParamField>

<ResponseExample>
  ```text 200 theme={null}
  (file content with Content-Length header)
  ```

  ```json 403 theme={null}
  {
    "error": "signed URL has expired"
  }
  ```
</ResponseExample>


# Signed Upload
Source: https://docs.opencomputer.dev/api-reference/files/signed-upload

PUT /api/sandboxes/{id}/files/upload

Upload a file using a signed URL. No authentication required — the signature and expiry are validated from query parameters. Send file content as the request body.

Generate a signed URL first via [Generate Upload URL](/api-reference/files/generate-upload-url).

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Absolute path for the destination file
</ParamField>

<ParamField type="string">
  Unix timestamp when the URL expires
</ParamField>

<ParamField type="string">
  HMAC-SHA256 signature
</ParamField>

<ResponseExample>
  ```text 204 theme={null}
  (no content)
  ```

  ```json 403 theme={null}
  {
    "error": "invalid signature"
  }
  ```
</ResponseExample>


# Write File
Source: https://docs.opencomputer.dev/api-reference/files/write

PUT /api/sandboxes/{id}/files

Write content to a file. The request body is written as raw file content (not JSON).

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Absolute path for the destination file
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# API Reference
Source: https://docs.opencomputer.dev/api-reference/overview

Complete REST API reference for OpenComputer

## Base URL

```
https://app.opencomputer.dev/api
```

## Authentication

All requests require an API key passed via the `X-API-Key` header.

```bash theme={null}
curl https://app.opencomputer.dev/api/sandboxes \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY"
```

## WebSocket Authentication

WebSocket endpoints accept auth via query parameter:

```
wss://app.opencomputer.dev/api/sandboxes/{id}/exec/{sessionID}?api_key=<key>
```

## Error Format

All errors use a consistent JSON envelope:

```json theme={null}
{
  "error": "descriptive error message"
}
```

| Status Code | Meaning                                        |
| ----------- | ---------------------------------------------- |
| `400`       | Invalid request (missing fields, bad values)   |
| `401`       | Missing or invalid authentication              |
| `403`       | Insufficient permissions                       |
| `404`       | Resource not found                             |
| `409`       | Conflict (duplicate resource)                  |
| `429`       | Quota exceeded                                 |
| `500`       | Internal server error                          |
| `503`       | Feature unavailable in current deployment mode |


# Create Patch
Source: https://docs.opencomputer.dev/api-reference/patches/create

POST /api/sandboxes/checkpoints/{checkpointId}/patches

Create a patch script that runs when a sandbox is spawned from a checkpoint. Patches apply in sequence order.

<ParamField type="string">
  Checkpoint ID
</ParamField>

<ParamField type="string">
  Bash script to execute on spawn
</ParamField>

<ParamField type="string">
  Human-readable description
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "patch": {
      "id": "pa-abc123",
      "checkpointId": "cp-abc123",
      "script": "apt install -y curl",
      "description": "Install curl",
      "strategy": "on_wake",
      "sequence": 1,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  }
  ```
</ResponseExample>


# Delete Patch
Source: https://docs.opencomputer.dev/api-reference/patches/delete

DELETE /api/sandboxes/checkpoints/{checkpointId}/patches/{patchId}

Delete a patch.

<ParamField type="string">
  Checkpoint ID
</ParamField>

<ParamField type="string">
  Patch ID
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# List Patches
Source: https://docs.opencomputer.dev/api-reference/patches/list

GET /api/sandboxes/checkpoints/{checkpointId}/patches

List all patches for a checkpoint.

<ParamField type="string">
  Checkpoint ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "pa-abc123",
      "checkpointId": "cp-abc123",
      "script": "apt install -y curl",
      "description": "Install curl",
      "strategy": "on_wake",
      "sequence": 1,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
  ```
</ResponseExample>


# Create Preview URL
Source: https://docs.opencomputer.dev/api-reference/preview/create

POST /api/sandboxes/{id}/preview

Create a preview URL to expose a port from the sandbox.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="integer">
  Container port (1–65535)
</ParamField>

<ParamField type="string">
  Custom domain
</ParamField>

<ParamField type="object">
  Authentication configuration
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "pv-abc123",
    "sandboxId": "sb-abc123",
    "hostname": "sb-abc123-p3000.workers.opencomputer.dev",
    "port": 3000,
    "sslStatus": "active",
    "createdAt": "2025-01-15T10:30:00Z"
  }
  ```
</ResponseExample>


# Delete Preview URL
Source: https://docs.opencomputer.dev/api-reference/preview/delete

DELETE /api/sandboxes/{id}/preview/{port}

Delete a preview URL.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Port number
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# List Preview URLs
Source: https://docs.opencomputer.dev/api-reference/preview/list

GET /api/sandboxes/{id}/preview

List all preview URLs for a sandbox.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "pv-abc123",
      "sandboxId": "sb-abc123",
      "hostname": "sb-abc123-p3000.workers.opencomputer.dev",
      "port": 3000,
      "sslStatus": "active",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
  ```
</ResponseExample>


# Rotate Preview-URL Auth Token
Source: https://docs.opencomputer.dev/api-reference/preview/rotate-auth

POST /api/sandboxes/{id}/preview/rotate

Mint a new bearer token for the sandbox's preview-URL auth gate. The old token stops working immediately — there is no zero-downtime dual-token mode, so roll the new token out to your caller before discarding the old one.

If the sandbox was originally created without [`previewAuth`](/api-reference/sandboxes/create), this call installs a token and starts enforcing the gate from that point on.

The plaintext is returned exactly once in the response. Only the SHA-256 hash is persisted server-side; the server cannot show you the token again later.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI",
    "scheme": "bearer"
  }
  ```
</ResponseExample>

### Errors

| Status | When                                                  |
| ------ | ----------------------------------------------------- |
| `404`  | Sandbox not found, or owned by a different org        |
| `410`  | Sandbox is `stopped` or `error`                       |
| `503`  | Database not configured (combined-mode CP without PG) |


# Create PTY Session
Source: https://docs.opencomputer.dev/api-reference/pty/create

POST /api/sandboxes/{id}/pty

Create an interactive terminal session.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="integer">
  Terminal columns (default: `80`)
</ParamField>

<ParamField type="integer">
  Terminal rows (default: `24`)
</ParamField>

<ParamField type="string">
  Shell path (default: `/bin/bash`)
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "sessionID": "ps-abc123",
    "sandboxID": "sb-abc123"
  }
  ```
</ResponseExample>


# Kill PTY Session
Source: https://docs.opencomputer.dev/api-reference/pty/kill

DELETE /api/sandboxes/{id}/pty/{sessionID}

Terminate a PTY session.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  PTY session ID
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# Resize PTY
Source: https://docs.opencomputer.dev/api-reference/pty/resize

POST /api/sandboxes/{id}/pty/{sessionID}/resize

Resize a PTY session.

<Note>
  PTY resize is HTTP-only — not exposed in the TypeScript or Python SDKs. The SDKs handle resize automatically for interactive sessions.
</Note>

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  PTY session ID
</ParamField>

<ParamField type="integer">
  New column count
</ParamField>

<ParamField type="integer">
  New row count
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {}
  ```
</ResponseExample>


# Create Sandbox
Source: https://docs.opencomputer.dev/api-reference/sandboxes/create

POST /api/sandboxes

Create a new sandbox.

<ParamField type="string">
  Template name (default: `"base"`)
</ParamField>

<ParamField type="integer">
  Idle timeout in seconds (default: `300`)
</ParamField>

<ParamField type="integer">
  CPU cores. If omitted but `memoryMB` is set, inferred automatically.
</ParamField>

<ParamField type="integer">
  Memory in MB. If omitted but `cpuCount` is set, inferred automatically.
</ParamField>

<ParamField type="boolean">
  Create a [Burst Sandbox](/sandboxes/burst-sandboxes). Disk is preserved across infrastructure restarts; processes may restart.
</ParamField>

The 1 GB tier provides 1 vCPU on a best-effort basis. For guaranteed CPU allocation, use the 4 GB tier or above.

If both `cpuCount` and `memoryMB` are provided, they must match a platform tier.

<ParamField type="object">
  Environment variables as key-value pairs
</ParamField>

<ParamField type="object">
  Arbitrary key-value pairs
</ParamField>

<ParamField type="object">
  Declarative image manifest (see [Image builder](/sandboxes/templates#image-configuration))
</ParamField>

<ParamField type="string">
  Name of a pre-built snapshot for instant boot
</ParamField>

<ParamField type="object[]">
  Register [webhook](/sandboxes/webhooks) destination(s) for this sandbox's lifecycle events, pinned to this sandbox. Registering inline (rather than via a separate call) means the endpoints exist **before** `sandbox.created` / `sandbox.ready` are relayed, so you don't miss the first events.

  * `url` *(string, required)*: HTTPS endpoint.
  * `secret` *(string)*: signing secret; omit and one is generated and returned on the response (`webhooks[].secret`), also re-fetchable later.
  * `eventTypes` *(string\[])*: event-type allow-list (default all).

  Each spec is validated up-front (same rules as [`POST /api/webhooks`](/api-reference/webhooks/create)): a non-HTTPS `url` or unknown `eventTypes` is rejected with `400`. Registration is otherwise **best-effort** — if a spec fails to register downstream, the sandbox is still created; inspect the echoed `webhooks: [{ id, url, secret? }]` to see what registered.
</ParamField>

<ParamField type="object">
  Opt in to bearer-token authentication on the sandbox's preview URLs. When set, every request to `https://sb-<id>-p<port>.<domain>` must include an `Authorization: Bearer <token>` (or `X-OC-Preview-Token: <token>`) header; missing or wrong → 401.

  * `scheme` *(string)*: must be `"bearer"`. Reserved for HMAC/JWT later.
  * `token` *(string)*: `"auto"` (or omitted) → server generates a 256-bit random token. An explicit string of at least 16 characters lets you bring your own.

  The plaintext is returned exactly once in the response as `previewAuthToken`; only its SHA-256 hash is stored. Use [`POST /api/sandboxes/{id}/preview/rotate`](/api-reference/preview/rotate-auth) to mint a new one.

  Omit this field for the legacy open behavior — preview URLs respond to anyone who can reach the hostname.
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "sandboxID": "sb-abc123",
    "status": "running",
    "region": "use2",
    "workerID": "w-use2-abc123",
    "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI",
    "webhooks": [
      { "id": "whk_3f9a2c", "url": "https://app.example.com/oc-webhook", "secret": "whsec_Hk9…" }
    ]
  }
  ```

  `previewAuthToken` is only present when `previewAuth` was set in the request — read it once and store it durably; the server will not return it again. `webhooks` is present only when `webhooks` were requested; each `secret` (`whsec_…`) is returned here and stays re-fetchable via [`GET /api/webhooks/{id}/secret`](/api-reference/webhooks/get).
</ResponseExample>


# Kill Sandbox
Source: https://docs.opencomputer.dev/api-reference/sandboxes/delete

DELETE /api/sandboxes/{id}

Terminate and remove a sandbox.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# Get Sandbox
Source: https://docs.opencomputer.dev/api-reference/sandboxes/get

GET /api/sandboxes/{id}

Get sandbox details by ID. Available on both control plane and worker.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "sandboxID": "sb-abc123",
    "status": "running",
    "region": "use2",
    "workerID": "w-use2-abc123",
    "tags": { "env": "prod", "team": "payments" },
    "tagsLastUpdatedAt": "2026-04-19T14:02:00Z"
  }
  ```
</ResponseExample>

`tags` and `tagsLastUpdatedAt` are always present — empty object and
`null` respectively when no tags are set. Update them with
[`PUT /api/sandboxes/{id}/tags`](/api-reference/sandboxes/set-tags).


# Get Sandbox Tags
Source: https://docs.opencomputer.dev/api-reference/sandboxes/get-tags

GET /api/sandboxes/{id}/tags

Read the current tag set for a sandbox.

<Note>
  **Preview:** Usage and tag APIs are new. Endpoints, response fields,
  and SDK method names may change before GA; temporary inaccuracies or
  rough edges are possible while the surface settles.
</Note>

<ParamField type="string">
  Sandbox ID.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "tags": { "env": "prod", "team": "payments" },
    "tagsLastUpdatedAt": "2026-04-19T14:02:00Z"
  }
  ```
</ResponseExample>

A sandbox with no tags returns `"tags": {}` and `"tagsLastUpdatedAt":
null`.


# Hibernate Sandbox
Source: https://docs.opencomputer.dev/api-reference/sandboxes/hibernate

POST /api/sandboxes/{id}/hibernate

Snapshot VM state and stop the sandbox. Control plane only.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "sandboxID": "sb-abc123",
    "hibernationKey": "checkpoints/sb-abc123/1234567890.tar.zst",
    "sizeBytes": 134217728,
    "status": "hibernated"
  }
  ```
</ResponseExample>


# List Sandboxes
Source: https://docs.opencomputer.dev/api-reference/sandboxes/list

GET /api/sandboxes

List all running sandboxes.

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "sandboxID": "sb-abc123",
      "status": "running",
      "region": "use2",
      "workerID": "w-use2-abc123",
      "tags": { "env": "prod" },
      "tagsLastUpdatedAt": "2026-04-19T14:02:00Z"
    }
  ]
  ```
</ResponseExample>

Each entry carries `tags` (always present, empty object when unset)
and `tagsLastUpdatedAt` (null when unset). To filter by tag, use
[`GET /api/usage?groupBy=sandbox&filter[tag:<key>]=<value>`](/api-reference/usage/get-usage).


# Set Sandbox Tags
Source: https://docs.opencomputer.dev/api-reference/sandboxes/set-tags

PUT /api/sandboxes/{id}/tags

Replace the full tag set for a sandbox. Partial updates are not
supported — GET, modify, PUT. `{}` clears all tags.

<Note>
  **Preview:** Usage and tag APIs are new. Endpoints, response fields,
  and SDK method names may change before GA; temporary inaccuracies or
  rough edges are possible while the surface settles.
</Note>

<ParamField type="string">
  Sandbox ID.
</ParamField>

<ParamField type="string">
  Each top-level key in the body is a tag name; the value is a
  string. Flat map only — nested objects are rejected.
</ParamField>

### Validation

* At most 50 tag keys per sandbox.
* Keys: 1–128 characters, `A–Z a–z 0–9 _ . - :`. `:` is allowed as
  a user namespace separator.
* Values: 0–256 UTF-8 characters.
* The `oc:` key prefix is reserved for future system-set tags.

<ResponseExample>
  ```json 200 theme={null}
  {
    "tags": { "env": "staging", "team": "growth" },
    "tagsLastUpdatedAt": "2026-04-22T20:31:14Z"
  }
  ```
</ResponseExample>

<Note>
  Retagging rewrites attribution going forward: a sandbox re-tagged
  from `team=payments` to `team=growth` will appear under `growth` in
  every subsequent /usage query, including for time before the retag.
  Surface `tagsLastUpdatedAt` alongside usage in dashboards so readers
  can see when tags changed.
</Note>


# Set Timeout
Source: https://docs.opencomputer.dev/api-reference/sandboxes/set-timeout

POST /api/sandboxes/{id}/timeout

Update the idle timeout for a sandbox.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="integer">
  New timeout in seconds (must be > 0)
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# Wake Sandbox
Source: https://docs.opencomputer.dev/api-reference/sandboxes/wake

POST /api/sandboxes/{id}/wake

Resume a hibernated sandbox. Control plane only.

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="integer">
  Idle timeout after wake (default: `300`)
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "sandboxID": "sb-abc123",
    "status": "running",
    "region": "use2",
    "workerID": "w-use2-abc123"
  }
  ```
</ResponseExample>


# Create Snapshot
Source: https://docs.opencomputer.dev/api-reference/snapshots/create

POST /api/snapshots

Create a pre-built sandbox environment from a declarative image manifest.

<ParamField type="string">
  Unique snapshot name
</ParamField>

<ParamField type="object">
  Declarative image manifest (see [Image builder](/sandboxes/templates#image-configuration))
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "snap-abc123",
    "name": "data-science",
    "status": "building",
    "contentHash": "sha256:...",
    "checkpointId": "",
    "manifest": { "steps": [] },
    "createdAt": "2025-01-15T10:30:00Z",
    "lastUsedAt": ""
  }
  ```
</ResponseExample>


# Delete Snapshot
Source: https://docs.opencomputer.dev/api-reference/snapshots/delete

DELETE /api/snapshots/{name}

Delete a snapshot.

<ParamField type="string">
  Snapshot name
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  {}
  ```
</ResponseExample>


# Get Snapshot
Source: https://docs.opencomputer.dev/api-reference/snapshots/get

GET /api/snapshots/{name}

Get snapshot details by name.

<ParamField type="string">
  Snapshot name
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "snap-abc123",
    "name": "data-science",
    "status": "ready",
    "contentHash": "sha256:...",
    "checkpointId": "cp-abc123",
    "manifest": { "steps": [] },
    "createdAt": "2025-01-15T10:30:00Z",
    "lastUsedAt": "2025-01-16T08:00:00Z"
  }
  ```
</ResponseExample>


# List Snapshots
Source: https://docs.opencomputer.dev/api-reference/snapshots/list

GET /api/snapshots

List all snapshots.

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "snap-abc123",
      "name": "data-science",
      "status": "ready",
      "contentHash": "sha256:...",
      "checkpointId": "cp-abc123",
      "manifest": { "steps": [] },
      "createdAt": "2025-01-15T10:30:00Z",
      "lastUsedAt": "2025-01-16T08:00:00Z"
    }
  ]
  ```
</ResponseExample>


# Sandbox Usage
Source: https://docs.opencomputer.dev/api-reference/usage/get-sandbox-usage

GET /api/sandboxes/{id}/usage

Per-sandbox memory usage over a window, as 1-minute points plus
envelope totals. Allocated memory is the tier the sandbox was
provisioned at, integrated over time; used memory is the actual
resident memory consumed by the sandbox process, sampled every 60s.

<Note>
  **Preview:** Usage and tag APIs are new. Endpoints, response fields,
  and SDK method names may change before GA; temporary inaccuracies or
  rough edges are possible while the surface settles.
</Note>

## Request

<ParamField type="string">
  Sandbox ID.
</ParamField>

<ParamField type="string">
  Lower bound. Accepts either an ISO date (`2026-05-27`, interpreted
  as UTC midnight) or an RFC3339 timestamp. Default: now minus 1 hour.
</ParamField>

<ParamField type="string">
  Upper bound. Same accepted formats as `from`. Default: now. Window
  must be ≤ 30 days.
</ParamField>

## Response

<ResponseField name="sandboxId" type="string">
  Echo of the requested sandbox ID.
</ResponseField>

<ResponseField name="alias" type="string">
  The sandbox's display name (set at create time). Absent if no alias
  was provided.
</ResponseField>

<ResponseField name="from" type="string">
  RFC3339 lower bound of the window the response covers — either the
  caller's `from`, or the server default (`now - 1h`) when omitted.
</ResponseField>

<ResponseField name="to" type="string">
  RFC3339 upper bound. Either the caller's `to`, or the server
  default (`now`) when omitted.
</ResponseField>

<ResponseField name="totals" type="object">
  Envelope totals for the full window. Each additive field equals the
  sum of the matching field across `points[]` — useful for getting
  the headline numbers without iterating.

  <Expandable title="properties">
    <ResponseField name="memoryAllocatedGbSeconds" type="number">
      Total GiB-seconds the sandbox was provisioned for. This is the
      physical quantity the bill is computed from. For a sandbox at
      1 GiB running for 1 hour, this is `3600`.
    </ResponseField>

    <ResponseField name="memoryUsedGbSeconds" type="number">
      Total GiB-seconds the sandbox actually consumed (integrated
      resident memory). Compare against `memoryAllocatedGbSeconds` to
      see headroom — `1 - used/allocated` is wasted provisioning.
    </ResponseField>

    <ResponseField name="uptimeSeconds" type="integer">
      Number of seconds the sandbox was provisioned (i.e., had an
      open scale event) within the window. A 1-hour window where the
      sandbox ran the whole time returns `3600`.
    </ResponseField>

    <ResponseField name="memoryAllocatedPeakMb" type="integer">
      Maximum provisioned memory tier (MiB) seen in the window.
      Reflects the highest size the sandbox was resized to.
    </ResponseField>

    <ResponseField name="memoryUsedPeakMb" type="integer">
      Maximum measured resident memory (MiB) in any sample during the
      window. Useful for detecting workloads that briefly approached
      their tier ceiling.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="points" type="object[]">
  Time-ordered array of 1-minute buckets covering `[from, to)`.
  Buckets are minute-aligned in UTC. Boundary buckets are clamped to
  the original window — a mid-minute `from` produces a partial first
  bucket whose integrals reflect only the overlap with the requested
  range.

  Minutes where the sandbox was not provisioned (before first start,
  after final stop) appear with all fields at `0` rather than as
  missing entries — gaps read as continuous flat zero on a chart.

  <Expandable title="properties">
    <ResponseField name="ts" type="string">
      RFC3339 timestamp of the bucket start (minute-aligned, UTC).
      The bucket covers `[ts, ts + 1 minute)`.
    </ResponseField>

    <ResponseField name="memoryAllocatedGbSeconds" type="number">
      Provisioned memory integrated over this minute, in GiB-seconds.
      Summing this across all points reproduces
      `totals.memoryAllocatedGbSeconds` exactly.
    </ResponseField>

    <ResponseField name="memoryUsedGbSeconds" type="number">
      Measured resident memory integrated over this minute, in
      GiB-seconds. Same compositional property — summing reproduces
      `totals.memoryUsedGbSeconds`.
    </ResponseField>

    <ResponseField name="uptimeSeconds" type="integer">
      Seconds within this minute the sandbox was provisioned. Usually
      `60`; `0` when not running; a fractional value (e.g., `30`)
      appears in the resize or start/stop bucket where the sandbox
      began or ended part-way through the minute.
    </ResponseField>

    <ResponseField name="allocatedMemoryMb" type="integer">
      Time-weighted average of the provisioned memory tier (MiB)
      across this bucket. When a resize falls inside the bucket, this
      shows the blend (e.g., 30s at 2048 + 30s at 4096 → `3072`).
      Designed to render directly as a step line on a chart.
    </ResponseField>

    <ResponseField name="usedMemoryMbAvg" type="integer">
      Average measured resident memory (MiB) across samples that fell
      in this bucket. The natural Y value for a "memory used" chart.
    </ResponseField>

    <ResponseField name="usedMemoryMbPeak" type="integer">
      Maximum measured resident memory (MiB) across samples in this
      bucket. Catches sub-minute spikes that the average smooths out.
    </ResponseField>
  </Expandable>
</ResponseField>

### Units

All `*GbSeconds` fields are **GiB-seconds** (binary, 2<sup>30</sup>
bytes/GiB), not decimal GB. For a sandbox provisioned at 1024 MiB
running for one minute, `memoryAllocatedGbSeconds` is
`1024/1024 × 60 = 60`. For a measured RSS of 612 MiB,
`memoryUsedGbSeconds` is `612/1024 × 60 ≈ 35.86`.

<ResponseExample>
  ```json 200 theme={null}
  {
    "sandboxId": "sb-abc",
    "alias": "my-agent",
    "from":   "2026-05-27T00:00:00Z",
    "to":     "2026-05-28T00:00:00Z",
    "totals": {
      "memoryAllocatedGbSeconds":  86400,
      "memoryUsedGbSeconds":       51640,
      "uptimeSeconds":             86400,
      "memoryAllocatedPeakMb":      1024,
      "memoryUsedPeakMb":            742
    },
    "points": [
      {
        "ts":                       "2026-05-27T00:00:00Z",
        "memoryAllocatedGbSeconds":      60.0,
        "memoryUsedGbSeconds":           35.86,
        "uptimeSeconds":                 60,
        "allocatedMemoryMb":           1024,
        "usedMemoryMbAvg":              612,
        "usedMemoryMbPeak":             720
      },
      {
        "ts":                       "2026-05-27T00:01:00Z",
        "memoryAllocatedGbSeconds":      60.0,
        "memoryUsedGbSeconds":           40.02,
        "uptimeSeconds":                 60,
        "allocatedMemoryMb":           1024,
        "usedMemoryMbAvg":              683,
        "usedMemoryMbPeak":             742
      }
    ]
  }
  ```
</ResponseExample>

### Use the aggregator for cross-sandbox questions

To rank sandboxes by usage, use [`GET /api/usage`](/api-reference/usage/get-usage)
— that endpoint serves cross-sandbox aggregates and supports
filter/sort/cursor. The per-sandbox endpoint here is for "look at
this one sandbox in detail."


# Usage Aggregator
Source: https://docs.opencomputer.dev/api-reference/usage/get-usage

GET /api/usage

Aggregate usage grouped by sandbox or by tag. Dollars are not exposed
— the platform returns the same physical quantities the invoice is
computed from. For per-sandbox time-series drilldown (memory
utilization over time, 1-minute resolution), see
[`GET /api/sandboxes/:id/usage`](/api-reference/usage/get-sandbox-usage).

<Note>
  **Preview:** Usage and tag APIs are new. Endpoints, response fields,
  and SDK method names may change before GA; temporary inaccuracies or
  rough edges are possible while the surface settles.
</Note>

<Note>
  All `*GbSeconds` fields are **GiB-seconds** (binary, 2<sup>30</sup>
  bytes/GiB), not decimal GB. For a sandbox provisioned at 1024 MiB
  running for one second, `memoryGbSeconds` is `1`.
</Note>

<Note>
  Freshness: accurate to the minute under normal conditions. A sandbox
  that exited uncleanly continues to accrue against its provisioned
  tier until the platform reconciles state — the same behavior the
  billing pipeline uses, so the numbers here match the invoice.
</Note>

## Request

<ParamField type="string">
  `sandbox` for top sandboxes, or `tag:<key>` for usage by tag value.
  Keys may contain `:` — everything after the first `:` is the tag
  key (so `groupBy=tag:team:payments` groups by the key
  `team:payments`).
</ParamField>

<ParamField type="string">
  Inclusive lower bound. Accepts either an ISO date (`2026-05-27`,
  interpreted as UTC midnight) or an RFC3339 timestamp. Default: now
  minus 30 days. Max window: 90 days.
</ParamField>

<ParamField type="string">
  Exclusive upper bound. Same accepted formats as `from`. Default:
  now.
</ParamField>

<ParamField type="string">
  One param per dimension. Comma-separated values are OR'd within
  that dimension; different `filter[...]` params are AND'd across
  dimensions. Passing the same `filter[...]` key twice returns 400 —
  put multiple OR values in one comma-separated string instead. Empty
  value (`filter[tag:team]=`) matches sandboxes without the `team`
  key.
</ParamField>

<ParamField type="string">
  `-memoryGbSeconds` (default) or `-diskOverageGbSeconds`.
</ParamField>

<ParamField type="integer">
  Max items per page. Default 50, max 500.
</ParamField>

<ParamField type="string">
  Opaque cursor from a prior response's `nextCursor`.
</ParamField>

## Response

<ResponseField name="from" type="string">
  RFC3339 echo of the effective window lower bound.
</ResponseField>

<ResponseField name="to" type="string">
  RFC3339 echo of the effective window upper bound.
</ResponseField>

<ResponseField name="groupBy" type="string">
  Echo of the requested `groupBy` value.
</ResponseField>

<ResponseField name="total" type="object">
  Aggregate across **all rows matching the window and filters**, not
  just the current page. Use this for headline numbers; sum `items[]`
  if you need a per-page subtotal instead.

  <Expandable title="properties">
    <ResponseField name="memoryGbSeconds" type="number">
      Total provisioned memory × time across matching sandboxes, in
      GiB-seconds.
    </ResponseField>

    <ResponseField name="diskOverageGbSeconds" type="number">
      Total disk-overage × time. Disk usage within the free
      allowance does not contribute; this is the billable excess.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="items" type="object[]">
  Paginated rows, sorted by `sort` (default: largest first).

  When `groupBy=sandbox`, each row is one sandbox:

  <Expandable title="groupBy=sandbox row">
    <ResponseField name="sandboxId" type="string">
      The sandbox identifier.
    </ResponseField>

    <ResponseField name="alias" type="string">
      Display name set at create time. Absent when none was provided.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current sandbox status (e.g., `running`, `hibernated`,
      `stopped`). Absent when no session exists.
    </ResponseField>

    <ResponseField name="tags" type="object">
      Current tag set on the sandbox. Empty object when none.
    </ResponseField>

    <ResponseField name="tagsLastUpdatedAt" type="string">
      RFC3339 timestamp of the most recent tag change, or `null` if
      no tags exist.
    </ResponseField>

    <ResponseField name="memoryGbSeconds" type="number">
      Provisioned memory × time for this sandbox in the window.
    </ResponseField>

    <ResponseField name="diskOverageGbSeconds" type="number">
      Disk overage × time for this sandbox.
    </ResponseField>
  </Expandable>

  When `groupBy=tag:<key>`, each row is one tag value:

  <Expandable title="groupBy=tag row">
    <ResponseField name="tagKey" type="string">
      The tag key from the request (e.g., `team`).
    </ResponseField>

    <ResponseField name="tagValue" type="string">
      The tag value for this group.
    </ResponseField>

    <ResponseField name="memoryGbSeconds" type="number">
      Total provisioned memory × time across sandboxes carrying
      `tagKey=tagValue`.
    </ResponseField>

    <ResponseField name="diskOverageGbSeconds" type="number">
      Total disk overage × time for the same group.
    </ResponseField>

    <ResponseField name="sandboxCount" type="integer">
      Distinct sandboxes contributing to this row.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="untagged" type="object">
  Only present when `groupBy=tag:<key>`. Sibling bucket for sandboxes
  that lack the grouping key — without it, untagged sandboxes would
  silently disappear from the rollup. Same shape as a tag row minus
  `tagKey`/`tagValue`.

  <Expandable title="properties">
    <ResponseField name="memoryGbSeconds" type="number">
      Total provisioned memory × time across untagged sandboxes.
    </ResponseField>

    <ResponseField name="diskOverageGbSeconds" type="number">
      Total disk overage × time.
    </ResponseField>

    <ResponseField name="sandboxCount" type="integer">
      Distinct sandboxes in the untagged bucket.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string">
  Opaque cursor to pass as `cursor=` on the next request, or `null`
  when no further pages exist.
</ResponseField>

<ResponseExample>
  ```json groupBy=sandbox theme={null}
  {
    "from": "2026-03-23T00:00:00Z",
    "to":   "2026-04-22T00:00:00Z",
    "groupBy": "sandbox",
    "total": { "memoryGbSeconds": 20000, "diskOverageGbSeconds": 360 },
    "items": [
      {
        "sandboxId": "sb-abc",
        "alias": "my-agent",
        "status": "running",
        "tags": { "env": "prod", "team": "payments" },
        "tagsLastUpdatedAt": "2026-04-19T14:02:00Z",
        "memoryGbSeconds": 8000,
        "diskOverageGbSeconds": 120
      }
    ],
    "nextCursor": null
  }
  ```

  ```json groupBy=tag:team theme={null}
  {
    "from": "2026-03-23T00:00:00Z",
    "to":   "2026-04-22T00:00:00Z",
    "groupBy": "tag:team",
    "total":    { "memoryGbSeconds": 19000, "diskOverageGbSeconds": 340 },
    "untagged": { "memoryGbSeconds": 1000,  "diskOverageGbSeconds":  20, "sandboxCount": 2 },
    "items": [
      { "tagKey": "team", "tagValue": "payments",
        "memoryGbSeconds": 8000, "diskOverageGbSeconds": 120, "sandboxCount": 12 },
      { "tagKey": "team", "tagValue": "growth",
        "memoryGbSeconds": 4000, "diskOverageGbSeconds":  50, "sandboxCount":  5 }
    ],
    "nextCursor": null
  }
  ```
</ResponseExample>


# List Tag Keys
Source: https://docs.opencomputer.dev/api-reference/usage/list-tags

GET /api/tags

List all tag keys set on any sandbox in the org, with per-key counts
of tagged sandboxes and distinct values. Useful for building
group-by pickers without querying the full tag set.

<Note>
  **Preview:** Usage and tag APIs are new. Endpoints, response fields,
  and SDK method names may change before GA; temporary inaccuracies or
  rough edges are possible while the surface settles.
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "keys": [
      { "key": "team", "sandboxCount": 17, "valueCount": 4 },
      { "key": "env",  "sandboxCount": 23, "valueCount": 3 }
    ]
  }
  ```
</ResponseExample>

<Note>
  Tag keys on torn-down sandboxes are retained so historical drilldowns
  keep resolving. As a result `sandboxCount` may include sandboxes
  that are no longer active.
</Note>


# Create Webhook
Source: https://docs.opencomputer.dev/api-reference/webhooks/create

POST /api/webhooks

Register a webhook destination for sandbox lifecycle events. See [Webhooks](/sandboxes/webhooks).

<ParamField type="string">
  HTTPS endpoint to deliver to. (SSRF protection is applied by the delivery provider at send time, not at registration.)
</ParamField>

<ParamField type="string[]">
  Event-type allow-list — exact (`sandbox.stopped`) or prefix (`sandbox.*`). Default: all event types. Types outside the sandbox taxonomy are rejected with `400`.
</ParamField>

<ParamField type="string">
  Scope to a single sandbox. Omit to receive events for all of the org's sandboxes.
</ParamField>

<ParamField type="string">
  Signing secret. Omit and one is generated (`whsec_…`). The secret is returned in the create response and is re-fetchable any time via [`GET /api/webhooks/{id}/secret`](/api-reference/webhooks/get).
</ParamField>

<ParamField type="string">
  Optional display name for the destination.
</ParamField>

<ParamField type="boolean">
  Whether the destination is active. Default `true`. `false` pauses delivery.
</ParamField>

<ParamField type="string">
  Optional. A retried create with the same key **and same body** returns the **same** destination (`200`) instead of a duplicate. Reusing the key with a **different** body is a `409` conflict.
</ParamField>

Without an `Idempotency-Key`, each call creates a **new** destination and returns **`201`** — there is no get-or-create by `name`. With one, a retried call returns the same destination with **`200`**.

**Validation (all `400`):** `url` must be HTTPS; each `eventTypes` entry must be a known sandbox event type or a `prefix.*` wildcard.

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "whk_3f9a2c",
    "name": "prod",
    "url": "https://app.example.com/oc-webhook",
    "eventTypes": ["sandbox.stopped"],
    "sandboxId": null,
    "enabled": true,
    "hasSecret": true,
    "secret": "whsec_Hk9…",
    "createdAt": "2026-06-24T12:00:00Z",
    "updatedAt": "2026-06-24T12:00:00Z"
  }
  ```

  The `secret` is returned here and stays re-fetchable via [`GET /api/webhooks/{id}/secret`](/api-reference/webhooks/get) — store it to verify deliveries.
</ResponseExample>


# Delete Webhook
Source: https://docs.opencomputer.dev/api-reference/webhooks/delete

DELETE /api/webhooks/{id}

Delete a destination. It stops receiving events, drops out of [list](/api-reference/webhooks/list), and its delivery-provider endpoint is removed. Delivery history for a deleted destination is no longer queryable. See [Webhooks](/sandboxes/webhooks).

<ParamField type="string">
  Destination ID (`whk_…`).
</ParamField>

<ResponseExample>
  ```json 204 theme={null}
  ```
</ResponseExample>


# List Deliveries
Source: https://docs.opencomputer.dev/api-reference/webhooks/deliveries-list

GET /api/webhooks/{id}/deliveries

List a destination's most recent delivery attempts (up to 50). Each entry is a delivery-provider
attempt record. The attempt index lags actual delivery by a few seconds, and resolving a single
message ([get](/api-reference/webhooks/delivery-get)) / [redeliver](/api-reference/webhooks/redeliver)
can lag longer (\~30s+) — retry with backoff. See [Webhooks](/sandboxes/webhooks#deliveries).

<ParamField type="string">
  Destination ID (`whk_…`).
</ParamField>

<ResponseField name="data[].id" type="string">
  The message id — the key for [get](/api-reference/webhooks/delivery-get) / [redeliver](/api-reference/webhooks/redeliver); equals the `svix-id` header on the delivery.
</ResponseField>

<ResponseField name="data[].attemptId" type="string">
  The id of this specific attempt.
</ResponseField>

<ResponseField name="data[].status" type="string">
  One of `success`, `pending`, or `failed`.
</ResponseField>

<ResponseField name="data[].responseStatusCode" type="integer">
  The consumer's HTTP response code, when the attempt reached it.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "msg_2aB…",
        "attemptId": "atmpt_9fE…",
        "status": "success",
        "responseStatusCode": 200,
        "timestamp": "2026-06-24T12:00:01Z"
      }
    ]
  }
  ```
</ResponseExample>


# Get Delivery
Source: https://docs.opencomputer.dev/api-reference/webhooks/delivery-get

GET /api/webhooks/{id}/deliveries/{deliveryId}

Fetch one delivered message by id. See [Webhooks](/sandboxes/webhooks#deliveries).

<Note>
  The delivery provider's attempt index and message store are eventually consistent: a message id can
  appear in [list deliveries](/api-reference/webhooks/deliveries-list) **before** this endpoint (and
  [redeliver](/api-reference/webhooks/redeliver)) can resolve it — observed up to \~30s+ after the
  attempt. So a `404` shortly after a delivery is transient — **retry with backoff** rather than
  treating it as final.
</Note>

<ParamField type="string">
  Destination ID (`whk_…`).
</ParamField>

<ParamField type="string">
  Message id (`msg_…`, the `id` from [list deliveries](/api-reference/webhooks/deliveries-list); equals the `svix-id` header).
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "msg_2aB…",
    "eventType": "sandbox.stopped",
    "eventId": "sb-3f9a…:sandbox.stopped",
    "payload": {
      "type": "sandbox.stopped",
      "sandboxId": "sb-3f9a…",
      "eventId": "sb-3f9a…:sandbox.stopped",
      "event": { "id": "sb-3f9a…:sandbox.stopped", "ts": "2026-06-24T12:00:00Z", "orgId": "org_…", "sandboxId": "sb-3f9a…", "type": "sandbox.stopped", "data": { "reason": "user_requested" } }
    },
    "timestamp": "2026-06-24T12:00:00Z"
  }
  ```
</ResponseExample>


# Get Webhook
Source: https://docs.opencomputer.dev/api-reference/webhooks/get

GET /api/webhooks/{id}

Fetch one webhook destination. The response carries `hasSecret` (not the secret itself); fetch the secret value any time via `GET /api/webhooks/{id}/secret` → `{ "secret": "whsec_…" }`. See [Webhooks](/sandboxes/webhooks).

<ParamField type="string">
  Destination ID (`whk_…`).
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "whk_3f9a2c",
    "name": "prod",
    "url": "https://app.example.com/oc-webhook",
    "eventTypes": ["sandbox.stopped"],
    "sandboxId": null,
    "enabled": true,
    "hasSecret": true,
    "createdAt": "2026-06-24T12:00:00Z",
    "updatedAt": "2026-06-24T12:00:00Z"
  }
  ```
</ResponseExample>


# List Webhooks
Source: https://docs.opencomputer.dev/api-reference/webhooks/list

GET /api/webhooks

List the org's webhook destinations. Deleted destinations are excluded. See [Webhooks](/sandboxes/webhooks).

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "whk_3f9a2c",
        "name": "prod",
        "url": "https://app.example.com/oc-webhook",
        "eventTypes": ["sandbox.stopped"],
        "sandboxId": null,
        "enabled": true,
        "hasSecret": true,
        "createdAt": "2026-06-24T12:00:00Z",
        "updatedAt": "2026-06-24T12:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>


# Redeliver
Source: https://docs.opencomputer.dev/api-reference/webhooks/redeliver

POST /api/webhooks/{id}/deliveries/{deliveryId}/redeliver

Re-send a message to the endpoint. The redelivery carries the **same** `svix-id`, so a receiver that dedupes treats it as the same message. Use it when the original never landed. See [Webhooks](/sandboxes/webhooks#deliveries).

<ParamField type="string">
  Destination ID (`whk_…`).
</ParamField>

<ParamField type="string">
  Message id (`msg_…`, from [list deliveries](/api-reference/webhooks/deliveries-list)).
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true
  }
  ```
</ResponseExample>

The new attempt appears under [deliveries](/api-reference/webhooks/deliveries-list).


# Test Webhook
Source: https://docs.opencomputer.dev/api-reference/webhooks/test

POST /api/webhooks/{id}/test

Enqueue a sample event to exercise your endpoint. It sends a real, signed message of a concrete type
the destination is subscribed to (the first of its `eventTypes`, defaulting to `sandbox.created`),
carrying the **normal delivery envelope** with `event.data.test = true` — so you exercise your real
verifier and parser. Delivery is **asynchronous** — this returns once the message is accepted; check
[deliveries](/api-reference/webhooks/deliveries-list) for the outcome.

<Note>
  The sample is published through your org's webhook app, so it is **not** isolated to this one
  destination: any other destination subscribed to the same event type (and matching scope) also
  receives it (likewise marked `event.data.test = true`).
</Note>

See [Webhooks](/sandboxes/webhooks).

<ParamField type="string">
  Destination ID (`whk_…`).
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "eventType": "sandbox.created",
    "messageId": "msg_2aB…"
  }
  ```
</ResponseExample>

`messageId` is the delivery's message id — find its attempt under [deliveries](/api-reference/webhooks/deliveries-list).


# Update Webhook
Source: https://docs.opencomputer.dev/api-reference/webhooks/update

PATCH /api/webhooks/{id}

Update a destination — pause/resume, retune filters, change the URL, or rotate the secret. See [Webhooks](/sandboxes/webhooks).

<ParamField type="string">
  Destination ID (`whk_…`).
</ParamField>

<ParamField type="string">
  New HTTPS endpoint.
</ParamField>

<ParamField type="string[]">
  Replace the event-type allow-list (unknown types are rejected with `400`). Pass `null` to clear it (deliver all types).
</ParamField>

<ParamField type="boolean">
  Pause (`false`) or resume (`true`) delivery. Pausing does **not** drop events — events that occur while paused are queued and delivered when you re-enable.
</ParamField>

<ParamField type="boolean">
  Rotate to a **new** generated signing secret, returned as `secret` in the response. The previous secret stays valid for a short rollover window so in-flight deliveries still verify. (To set a specific secret, create a new destination.)
</ParamField>

<ParamField type="string">
  Rename the destination.
</ParamField>

`sandboxId` (scope) is **immutable** — set it at create; it can't be changed here. The current signing secret is re-fetchable any time via [`GET /api/webhooks/{id}/secret`](/api-reference/webhooks/get).

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "whk_3f9a2c",
    "name": "prod",
    "url": "https://app.example.com/oc-webhook",
    "eventTypes": ["sandbox.stopped", "sandbox.ready"],
    "sandboxId": null,
    "enabled": true,
    "hasSecret": true,
    "createdAt": "2026-06-24T12:00:00Z",
    "updatedAt": "2026-06-24T12:05:00Z"
  }
  ```
</ResponseExample>


# Browser Sessions
Source: https://docs.opencomputer.dev/browser-sessions/overview

Preview: create cloud browser sessions for Playwright, Magnitude, and profile-backed web automation

<Warning>
  Browser Sessions are currently in invite-only preview. Access is enabled for
  approved organizations, and API routes, SDK method names, response fields,
  limits, and pricing may change before general availability.
</Warning>

Browser Sessions create managed Chromium sessions for web agents and browser
automation. OpenComputer handles API-key auth and org ownership, then returns
browser connection URLs for tools such as Playwright and Magnitude.

If your organization has not been invited to the preview, Browser Session API
calls may fail even when your OpenComputer API key is valid.

Use Browser Sessions when you want a cloud browser without installing Chromium
inside an OpenComputer sandbox. Use [sandboxes](/sandboxes/overview) when you
need a full Linux VM with your own browser runtime and filesystem.

## Create a Browser

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Browser } from "@opencomputer/sdk";

  const browser = await Browser.create({
    headless: false,
    stealth: true,
    startUrl: "https://example.com",
    timeoutSeconds: 120,
  });

  console.log(browser.id);
  console.log(browser.cdpWsUrl);
  console.log(browser.liveViewUrl);

  await browser.delete();
  ```

  ```python Python theme={null}
  from opencomputer import Browser

  browser = await Browser.create(
      headless=False,
      stealth=True,
      start_url="https://example.com",
      timeout_seconds=120,
  )

  print(browser.id)
  print(browser.cdp_ws_url)
  print(browser.live_view_url)

  await browser.delete()
  ```
</CodeGroup>

Headful browsers return a live-view URL. Headless browsers are lighter, but do
not provide a live view. Telemetry is enabled by default for all browser
sessions. Set `telemetry: false` / `telemetry=False` to disable it, or pass a
Kernel telemetry configuration object directly.

Replay recording is disabled by default. Set `recording: true` /
`recording=True` to enable replay recording for a headful browser session.

## Profile Auth Checks

Saved profiles can start an asynchronous auth check for a site. The SDK returns
a run immediately; `wait()` polls with short requests until the run completes.

```typescript TypeScript theme={null}
const profile = await BrowserProfile.connect("linkedin-profile");

const run = await profile.checkAuth({
  homepage: "https://www.linkedin.com/feed/",
  user: "motatoes",
  mode: "vision",
  compareFresh: true,
});

const result = await run.wait();
console.log(result.status, result.result);
```

Auth checks are read-only. They create temporary browser sessions with profile
saving disabled and compare the saved profile against a fresh browser when
`compareFresh` is enabled.

## Playwright

The browser response includes a CDP WebSocket URL. Pass it directly to
Playwright's `connectOverCDP`.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Browser } from "@opencomputer/sdk";
  import { chromium } from "playwright";

  const ocBrowser = await Browser.create({
    headless: false,
    startUrl: "https://example.com",
  });

  try {
    const browser = await chromium.connectOverCDP(ocBrowser.cdpWsUrl);
    const context = browser.contexts()[0] || await browser.newContext();
    const page = context.pages()[0] || await context.newPage();

    await page.goto("https://example.com");
    console.log(await page.title());

    await browser.close();
  } finally {
    await ocBrowser.delete();
  }
  ```

  ```python Python theme={null}
  from opencomputer import Browser
  from playwright.async_api import async_playwright

  oc_browser = await Browser.create(
      headless=False,
      start_url="https://example.com",
  )

  try:
      async with async_playwright() as p:
          browser = await p.chromium.connect_over_cdp(oc_browser.cdp_ws_url)
          context = browser.contexts[0] if browser.contexts else await browser.new_context()
          page = context.pages[0] if context.pages else await context.new_page()

          await page.goto("https://example.com")
          print(await page.title())

          await browser.close()
  finally:
      await oc_browser.delete()
  ```
</CodeGroup>

## Magnitude

Magnitude can use a Playwright-connected browser. Create the OpenComputer
browser first, connect over CDP, then hand the page to your Magnitude agent.

```typescript TypeScript theme={null}
import { Browser } from "@opencomputer/sdk";
import { chromium } from "playwright";
import { startBrowserAgent } from "magnitude-core";

const ocBrowser = await Browser.create({
  headless: false,
  stealth: true,
  startUrl: "https://example.com",
});

try {
  const browser = await chromium.connectOverCDP(ocBrowser.cdpWsUrl);
  const context = browser.contexts()[0] || await browser.newContext();
  const page = context.pages()[0] || await context.newPage();

  const agent = await startBrowserAgent({ page });
  await agent.act("Find the page title and summarize what this site is for.");

  await browser.close();
} finally {
  await ocBrowser.delete();
}
```

<Note>
  Magnitude package names and constructors can vary by version. The
  OpenComputer-specific step is stable: create a `Browser`, connect to
  `cdpWsUrl` with Playwright, then pass the resulting page or browser object to
  Magnitude.
</Note>

## Save and Load Profiles

Profiles persist browser state such as cookies and local storage across browser
sessions. Profiles are scoped to your OpenComputer org; another org cannot
list, load, or delete your profiles.

Create a profile once:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { BrowserProfile } from "@opencomputer/sdk";

  const profile = await BrowserProfile.create({
    name: "github-login",
  });
  ```

  ```python Python theme={null}
  from opencomputer import BrowserProfile

  profile = await BrowserProfile.create(name="github-login")
  ```
</CodeGroup>

Use the profile when creating a browser:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Browser } from "@opencomputer/sdk";

  const browser = await Browser.create({
    profile: {
      id: profile.id,
      saveChanges: true,
    },
    headless: false,
  });

  // Log in or update session state, then delete the browser.
  // With saveChanges enabled, changes are saved back to the profile.
  await browser.delete();
  ```

  ```python Python theme={null}
  from opencomputer import Browser

  browser = await Browser.create(
      profile={
          "id": profile.id,
          "save_changes": True,
      },
      headless=False,
  )

  # Log in or update session state, then delete the browser.
  # With save_changes enabled, changes are saved back to the profile.
  await browser.delete()
  ```
</CodeGroup>

Load the same profile later by ID or name:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Browser, BrowserProfile } from "@opencomputer/sdk";

  const profile = await BrowserProfile.connect("github-login");

  const browser = await Browser.create({
    profile: {
      id: profile.id,
      saveChanges: true,
    },
    headless: false,
  });
  ```

  ```python Python theme={null}
  from opencomputer import Browser, BrowserProfile

  profile = await BrowserProfile.connect("github-login")

  browser = await Browser.create(
      profile={
          "id": profile.id,
          "save_changes": True,
      },
      headless=False,
  )
  ```
</CodeGroup>

## Authentication

The SDK uses your OpenComputer API key:

```bash theme={null}
export OPENCOMPUTER_API_KEY="osb_..."
```

<Note>
  For local development against a non-production Browser Sessions endpoint, set
  `OPENCOMPUTER_BROWSER_API_URL`.
</Note>


# Checkpoints
Source: https://docs.opencomputer.dev/cli/checkpoint

Snapshot, fork, and restore from the CLI

## Creating a Checkpoint

Capture the current state of a running sandbox:

```bash theme={null}
oc checkpoint create sb-abc123 --name before-migration
# or using the shortcut:
oc cp create sb-abc123 --name before-migration
```

The checkpoint saves the filesystem and installed state. Status starts as `processing` and transitions to `ready`.

```bash theme={null}
oc cp list sb-abc123
# ID          NAME               STATUS  SIZE     CREATED
# cp-7f3a1b2c before-migration   ready   128 MB   2025-01-15T10:30:00Z
```

## Forking from a Checkpoint

Create new sandboxes from a saved checkpoint. Each fork is independent:

```bash theme={null}
# Spawn two independent sandboxes from the same checkpoint
ID1=$(oc cp spawn cp-7f3a1b2c --json | jq -r '.sandboxID')
ID2=$(oc cp spawn cp-7f3a1b2c --json | jq -r '.sandboxID')

# Run different experiments
oc exec $ID1 --wait -- ./experiment-a.sh
oc exec $ID2 --wait -- ./experiment-b.sh
```

Forked sandboxes start with a fresh boot from the saved disk state — don't assume running processes carry over.

## Restoring

Revert a sandbox in-place to a checkpoint. All changes since the checkpoint are lost:

```bash theme={null}
oc cp restore sb-abc123 cp-7f3a1b2c
```

## Listing and Deleting

```bash theme={null}
oc cp list sb-abc123
oc cp delete sb-abc123 cp-7f3a1b2c
```

Each sandbox can have up to 10 full checkpoints and up to 100 disk-only checkpoints.

To create a new checkpoint at the limit, opt into automatic deletion of the oldest eligible checkpoint of the same type:

```bash theme={null}
oc cp create sb-abc123 \
  --name autosave \
  --kind disk_only \
  --retention-policy delete_oldest \
  --retention-max-count 100
```

Retention skips public checkpoints, patched checkpoints, and checkpoints that are still referenced by forked sandboxes.

## Checkpoint vs Hibernate

|                  | Checkpoint                    | Hibernate                      |
| ---------------- | ----------------------------- | ------------------------------ |
| Original sandbox | Keeps running                 | Stopped                        |
| Can fork         | Yes — unlimited new sandboxes | No                             |
| Use case         | Branching, parallel testing   | Pause and resume, cost savings |

Use checkpoints when you need to explore multiple paths from the same state. Use hibernation when you just want to pause and resume later.

<Tip>
  SDK usage: [Checkpoints](/sandboxes/checkpoints). Full flags: [CLI Reference](/reference/cli#oc-checkpoint).
</Tip>


# Running Commands
Source: https://docs.opencomputer.dev/cli/exec

Execute shell commands from the CLI

## Running a Command

Use `--wait` to run a command synchronously — output streams to your terminal and the CLI exits with the process exit code:

```bash theme={null}
oc exec sb-abc123 --wait -- echo "Hello, World!"
oc exec sb-abc123 --wait -- npm run build
```

Without `--wait`, `oc exec` creates an **exec session** and prints the session ID with attach instructions. This is useful for long-running commands:

```bash theme={null}
oc exec sb-abc123 -- node server.js
# → Session es-xyz created. Attach with: oc exec attach sb-abc es-xyz
```

## Working Directory & Environment

```bash theme={null}
oc exec sb-abc123 --wait --cwd /app --env NODE_ENV=production -- npm run build
oc exec sb-abc123 --wait --env API_KEY=xxx --env DEBUG=true -- ./run.sh
```

## Timeouts

Set a timeout with `--timeout` (in seconds). Default is 0 (no timeout). When exceeded, the command is killed:

```bash theme={null}
oc exec sb-abc123 --wait --timeout 30 -- npm test
```

## Creating an Exec Session

Plain `oc exec` (without `--wait`) creates a session for long-running commands. The command keeps running even after you disconnect:

```bash theme={null}
oc exec sb-abc123 -- python train.py
# Session es-abc created
```

## Capturing Output as JSON

Combine `--json` with `--wait` for scripting:

```bash theme={null}
RESULT=$(oc exec sb-abc123 --json --wait -- node -e 'console.log("hello")')
echo $RESULT | jq '.stdout'   # "hello\n"
echo $RESULT | jq '.exitCode' # 0
```

## Managing Exec Sessions

```bash theme={null}
# List active sessions
oc exec list sb-abc123

# Kill a session
oc exec kill sb-abc123 es-xyz
oc exec kill sb-abc123 es-xyz --signal 15  # SIGTERM
```

<Warning>
  `oc exec attach` exists as a command but is not yet implemented. It prints guidance to use the SDK or a WebSocket client. Use `oc exec list` and `oc exec kill` to manage sessions from the CLI.
</Warning>

## Shell vs Exec

| Use Case                           | Command                  |
| ---------------------------------- | ------------------------ |
| Single command, capture output     | `oc exec --wait`         |
| Scripting and automation           | `oc exec --wait --json`  |
| Long-running background process    | `oc exec` (no `--wait`)  |
| Interactive development, debugging | [`oc shell`](/cli/shell) |

<Tip>
  SDK usage: [Running Commands](/sandboxes/running-commands). Full flags: [CLI Reference](/reference/cli#oc-exec).
</Tip>


# CLI
Source: https://docs.opencomputer.dev/cli/overview

Manage sandboxes from your terminal

The `oc` CLI lets you manage OpenComputer sandboxes directly from your terminal — create sandboxes, run commands, open interactive shells, manage checkpoints, and more.

## Installation

<CodeGroup>
  ```bash macOS (Apple Silicon) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-darwin-arm64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```

  ```bash macOS (Intel) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-darwin-amd64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```

  ```bash Linux (x86_64) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-linux-amd64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```

  ```bash Linux (ARM64) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-linux-arm64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```
</CodeGroup>

## Sign in

```bash theme={null}
oc login
oc whoami
```

`oc login` prints a short confirmation code and opens the hosted sign-in page.
Use `oc login --no-browser` over SSH or when a coding agent is running the
command for you. The CLI stores the resulting credential in
`~/.oc/config.json` with private file permissions; it never prints the key.

```bash theme={null}
oc logout          # revoke the CLI-created key, then clear it locally
oc logout --local  # clear local login state without claiming remote revocation
```

`oc login` authenticates the local CLI. CI, servers, and SDK applications
should continue to receive an explicit org key through their secret manager and
`OPENCOMPUTER_API_KEY`.

### Credential resolution

| Priority    | Source                | Example                                 |
| ----------- | --------------------- | --------------------------------------- |
| 1 (highest) | CLI flags             | `--api-key=xxx`                         |
| 2           | Environment variables | `OPENCOMPUTER_API_KEY`                  |
| 3           | Config file           | `oc login` or `oc config set api-key …` |
| 4 (lowest)  | Defaults              | `https://app.opencomputer.dev`          |

An active `--api-key` or `OPENCOMPUTER_API_KEY` override must be removed before
`oc login` or remote `oc logout`; `oc logout --local` can still clear the saved
CLI login. Manually setting an API key remains supported:

```bash theme={null}
oc config set api-key "$OPENCOMPUTER_API_KEY"
oc config show
```

## Global Flags

| Flag        | Environment Variable   | Description                      |
| ----------- | ---------------------- | -------------------------------- |
| `--api-key` | `OPENCOMPUTER_API_KEY` | API key for authentication       |
| `--api-url` | `OPENCOMPUTER_API_URL` | Control plane URL                |
| `--json`    | —                      | Output as JSON instead of tables |

## Key Workflows

### Quick Start

```bash theme={null}
# Create a sandbox
oc create

# Run a command and wait for the result
oc exec sb-abc123 --wait -- echo "Hello from the cloud"

# Open an interactive shell
oc shell sb-abc123

# Clean up
oc sandbox kill sb-abc123
```

### JSON Output & Scripting

All commands support `--json` for machine-readable output:

```bash theme={null}
# Get a sandbox ID programmatically
ID=$(oc create --json | jq -r '.sandboxID')

# List all running sandbox IDs
oc ls --json | jq -r '.[].sandboxID'

# Run a command and capture the result
RESULT=$(oc exec $ID --json --wait -- npm test)
echo $RESULT | jq '.exitCode'
```

### Top-level Shortcuts

| Shortcut    | Expands to          |
| ----------- | ------------------- |
| `oc create` | `oc sandbox create` |
| `oc ls`     | `oc sandbox list`   |
| `oc cp`     | `oc checkpoint`     |

### Create and Shell In

```bash theme={null}
oc shell $(oc create --json | jq -r '.sandboxID')
```

### Hibernate for Cost Savings

```bash theme={null}
oc sandbox hibernate sb-abc123
# ... hours later ...
oc sandbox wake sb-abc123
oc shell sb-abc123
```

### Checkpoint and Fork

```bash theme={null}
oc cp create sb-abc --name ready-state
ID1=$(oc cp spawn cp-xyz --json | jq -r '.sandboxID')
ID2=$(oc cp spawn cp-xyz --json | jq -r '.sandboxID')
oc exec $ID1 --wait -- ./test-a.sh
oc exec $ID2 --wait -- ./test-b.sh
```

## Command Reference

| Command                                 | Description                                |
| --------------------------------------- | ------------------------------------------ |
| [`oc sandbox`](/cli/sandbox)            | Create, list, kill, hibernate, wake        |
| [`oc exec`](/cli/exec)                  | Run commands, manage exec sessions         |
| [`oc shell`](/cli/shell)                | Interactive PTY terminal                   |
| [`oc checkpoint`](/cli/checkpoint)      | Snapshot, fork, restore                    |
| [`oc patch`](/cli/patch)                | Checkpoint-attached scripts                |
| [`oc preview`](/cli/preview)            | Expose ports to the internet               |
| [`oc agent`](/reference/cli/agent)      | Invoke durable agents and manage Hook URLs |
| [`oc login`](/reference/cli/auth)       | Sign in, inspect identity, and log out     |
| [`oc config`](/reference/cli#oc-config) | Configure API key and API URL              |

<Tip>
  Full flag reference for every command: [CLI Reference](/reference/cli).
</Tip>


# Patches
Source: https://docs.opencomputer.dev/cli/patch

Attach scripts to checkpoints from the CLI

## What Patches Do

A patch is a shell script attached to a checkpoint. Patches run in order every time a sandbox is forked from that checkpoint — layer setup without re-creating the checkpoint.

## Creating a Patch

From a file or stdin:

```bash theme={null}
# From a file
oc patch create cp-7f3a1b2c --script ./setup.sh --description "Install deps"

# One-liner from stdin
echo "npm install -g typescript" | oc patch create cp-7f3a1b2c --script=-
```

## Layering Setup

Add multiple patches — they execute in creation order on every fork:

```bash theme={null}
oc patch create cp-7f3a1b2c --script ./install-node.sh --description "Node.js 20"
oc patch create cp-7f3a1b2c --script ./app-config.sh --description "App config"

# Each spawned sandbox gets both patches applied in order
oc cp spawn cp-7f3a1b2c
```

## Inspecting Patches

Review what will run before forking:

```bash theme={null}
oc patch list cp-7f3a1b2c
# ID          SEQ  DESCRIPTION     STRATEGY  CREATED
# pa-abc123   1    Node.js 20      on_wake   2025-01-15T10:30:00Z
# pa-def456   2    App config      on_wake   2025-01-15T10:31:00Z
```

## Removing a Patch

```bash theme={null}
oc patch delete cp-7f3a1b2c pa-abc123
```

<Tip>
  SDK usage: [Patches](/sandboxes/patches). Full flags: [CLI Reference](/reference/cli#oc-patch).
</Tip>


# Preview URLs
Source: https://docs.opencomputer.dev/cli/preview

Expose sandbox ports from the CLI

## Exposing a Port

Create a public HTTPS URL that proxies traffic to a port inside your sandbox:

```bash theme={null}
oc preview create sb-abc123 --port 3000
# → hostname: sb-abc123-p3000.workers.opencomputer.dev
```

## Sharing a Dev Server

Start a server inside the sandbox, expose it, and share the URL:

```bash theme={null}
# Start a dev server in the background
oc exec sb-abc123 -- bash -c 'cd /app && npm run dev &'

# Expose port 3000
oc preview create sb-abc123 --port 3000

# Get the URL
oc preview list sb-abc123
```

## Multiple Ports

Expose multiple services from the same sandbox:

```bash theme={null}
oc preview create sb-abc123 --port 3000  # Frontend
oc preview create sb-abc123 --port 8080  # API server

oc preview list sb-abc123
# PORT  HOSTNAME                                      SSL     CREATED
# 3000  sb-abc123-p3000.workers.opencomputer.dev      active  ...
# 8080  sb-abc123-p8080.workers.opencomputer.dev      active  ...
```

## Custom Domains

Pass `--domain` to use your own domain. DNS must point to OpenComputer's ingress, and the domain must be verified in the dashboard. SSL is provisioned automatically.

```bash theme={null}
oc preview create sb-abc123 --port 3000 --domain preview.myapp.com
```

## Cleanup

```bash theme={null}
oc preview delete sb-abc123 3000
```

Preview URLs persist across hibernation/wake cycles — no need to re-create them.

## Bearer-Token Authentication

By default, anyone who knows the preview hostname can hit your sandbox's port. To require an `Authorization: Bearer <token>` header on every request, opt in at create time:

```bash theme={null}
oc sandbox create --preview-auth
# Created sandbox sb-abc123 (status: running)
# Preview auth token (shown once): qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI
```

Then call your preview URL with the token:

```bash theme={null}
curl -H "Authorization: Bearer qx2sSi5IYX..." https://sb-abc123-p3000.workers.opencomputer.dev/
```

Bring your own token if your gateway already has a shared secret:

```bash theme={null}
oc sandbox create --preview-auth-token "$GATEWAY_TOKEN"
```

Rotate the token (old one stops working immediately):

```bash theme={null}
oc preview rotate-auth sb-abc123
# New preview auth token (shown once): <new token>
```

Token is shown exactly once and only its SHA-256 hash is stored. See [Authentication](/sandboxes/preview-urls#authentication) for the SDK equivalents.

<Tip>
  SDK usage: [Preview URLs](/sandboxes/preview-urls). Full flags: [CLI Reference](/reference/cli#oc-preview).
</Tip>


# Sandbox Management
Source: https://docs.opencomputer.dev/cli/sandbox

Create, manage, and control sandbox lifecycles from the CLI

## Creating a Sandbox

`oc create` (shortcut for `oc sandbox create`) provisions a new sandbox VM:

```bash theme={null}
oc create
oc create --timeout 600 --cpu 2 --memory 2048 --env NODE_ENV=production
```

The sandbox ID is printed on success. Use `--json` to capture it programmatically:

```bash theme={null}
ID=$(oc create --json | jq -r '.sandboxID')
```

## Listing & Inspecting

```bash theme={null}
# List all sandboxes
oc ls

# Detailed info for a specific sandbox
oc sandbox get sb-abc123
```

`oc ls` shows a table with ID, template, status, CPU, memory, and age. Add `--json` for machine-readable output.

## Hibernation & Wake

Save state and stop paying for compute. Wake resumes the same sandbox — the platform attempts fast snapshot restore with a cold-boot fallback if needed.

```bash theme={null}
oc sandbox hibernate sb-abc123

# ... hours later ...
oc sandbox wake sb-abc123
oc shell sb-abc123
```

The sandbox keeps the same ID across hibernate/wake cycles. Preview URLs remain active.

## Adjusting Timeout

The idle timeout resets on every operation (exec, file access, agent activity). Default: 300s.

```bash theme={null}
oc sandbox set-timeout sb-abc123 3600  # 1 hour
```

## Killing a Sandbox

```bash theme={null}
oc sandbox kill sb-abc123
```

All data is lost unless you've created a [checkpoint](/cli/checkpoint) first.

## Common Patterns

### Create and Shell In

```bash theme={null}
oc shell $(oc create --json | jq -r '.sandboxID')
```

### Filter Running Sandboxes

```bash theme={null}
oc ls --json | jq '.[] | select(.status == "running") | .sandboxID'
```

### Batch Cleanup

```bash theme={null}
oc ls --json | jq -r '.[].sandboxID' | xargs -I{} oc sandbox kill {}
```

<Tip>
  SDK usage: [Sandboxes](/sandboxes/overview). Full flags: [CLI Reference](/reference/cli#oc-sandbox).
</Tip>


# Secrets
Source: https://docs.opencomputer.dev/cli/secrets

Manage secret stores and secrets from the CLI

## Secret stores

```bash theme={null}
# Create a store (with optional egress restrictions)
oc secret-store create --name my-secrets --egress-allowlist api.anthropic.com

# List stores
oc secret-store list

# Update a store
oc secret-store update <store-id> --egress-allowlist api.anthropic.com,*.openai.com

# Delete a store (and all its secrets)
oc secret-store delete <store-id>
```

## Secrets

```bash theme={null}
# Set a secret
oc secret set <store-id> ANTHROPIC_API_KEY sk-ant-...

# Set from stdin
echo "sk-ant-..." | oc secret set <store-id> ANTHROPIC_API_KEY --from-stdin

# Restrict a secret to specific hosts
oc secret set <store-id> ANTHROPIC_API_KEY sk-ant-... --allowed-hosts api.anthropic.com

# List secrets (names only — values are never returned)
oc secret list <store-id>

# Delete a secret
oc secret delete <store-id> ANTHROPIC_API_KEY
```

## Using secrets in sandboxes

```bash theme={null}
# Create a sandbox with a secret store
oc create --secret-store my-secrets

# Env vars are sealed — real values are never in the VM
oc exec <sandbox-id> -- echo '$ANTHROPIC_API_KEY'
# osb_sealed_7f3a9c... (not the real key)
```

For how secrets work under the hood, see [Secrets](/sandboxes/secrets).


# Shell
Source: https://docs.opencomputer.dev/cli/shell

Interactive terminal sessions from the CLI

## Opening a Shell

```bash theme={null}
oc shell sb-abc123
```

Opens a full interactive terminal over WebSocket. Press `Ctrl+D` or type `exit` to disconnect.

## Choosing a Shell

```bash theme={null}
oc shell sb-abc123 --shell /bin/zsh
```

Default: `/bin/bash`.

## What Works

The PTY supports everything you'd expect from a real terminal:

* **Editors:** vim, nano
* **Monitors:** top, htop
* **Tab completion** and command history
* **Colors** and ANSI escape codes
* **Terminal resizing** — automatic, resize events forwarded

Full-screen applications like `tmux` and `less` work correctly.

## Shell vs Exec

| Use Case                             | Command                 |
| ------------------------------------ | ----------------------- |
| Run a single command, capture output | `oc exec --wait`        |
| Scripting and automation             | `oc exec --wait --json` |
| Interactive development              | `oc shell`              |
| Debugging                            | `oc shell`              |

## Tips

### Create and Shell In

```bash theme={null}
oc shell $(oc create --json | jq -r '.sandboxID')
```

### Shell with Custom Environment

Set up the environment before shelling in:

```bash theme={null}
ID=$(oc create --json | jq -r '.sandboxID')
oc exec $ID --wait -- bash -c 'echo "export PATH=/app/bin:\$PATH" >> ~/.bashrc'
oc shell $ID
```

<Tip>
  SDK usage: [Interactive Terminals](/sandboxes/interactive-terminals). Full flags: [CLI Reference](/reference/cli#oc-shell).
</Tip>


# Agent Skill
Source: https://docs.opencomputer.dev/guides/agent-skill

Use AI agents to manage cloud sandboxes with natural language

The OpenComputer skill lets AI agents like Claude Code create and manage cloud sandboxes using the `oc` CLI. Instead of writing commands yourself, just describe what you want.

## Install

```bash theme={null}
npx skills add diggerhq/opencomputer
```

This works with Claude Code, Codex, Cursor, and any agent that supports the [Agent Skills](https://agentskills.io) standard.

## Prerequisites

The `oc` CLI must be installed and configured:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/diggerhq/opencomputer/main/scripts/install.sh | bash
oc login
```

If the command prints a browser URL or confirmation code, relay it to the user
and wait for them to approve it. The CLI resumes without asking anyone to paste
an API key into chat.

## Usage

The skill activates automatically when you mention sandboxes or the `oc` CLI. Just ask naturally:

**Create a custom base image:**

> Create a base image for me that includes a placeholder React app I can use as a starter kit. Checkpoint it so I can spawn copies later.

**Fork and experiment:**

> Spawn two sandboxes from my react-starter checkpoint. In the first one, add Tailwind CSS. In the second, add Material UI.

**Run commands:**

> Install PostgreSQL in my sandbox and run the test suite

**Manage state:**

> Checkpoint my sandbox before I try this migration, so I can roll back if it breaks

The agent handles all the `oc` commands under the hood — creating sandboxes, running `exec`, taking checkpoints, applying patches, and cleaning up.


# Browser Automation
Source: https://docs.opencomputer.dev/guides/browser-automation

Run headless and headed browsers inside OpenComputer sandboxes — for scraping, logged-in workflows, and AI-driven automation.

OpenComputer sandboxes are full Linux VMs, which means you can run a real Chromium browser inside them the same way you would on a laptop. This guide walks through the setup that makes it *actually work*: the right Chromium flavor, the system libraries you need, the OpenComputer-specific networking quirks, and how to persist browser state across runs.

The examples use [**libretto**](https://libretto.sh), an AI-friendly CLI + library on top of Playwright. Everything here applies equally to raw Playwright, Puppeteer, [browser-use](https://browser-use.com/), or [Browserbase](https://www.browserbase.com/) — libretto is just a convenient default.

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/diggerhq/oc-browser-automation">
    Runnable reference implementation of everything in this guide.
  </Card>

  <Card title="libretto Docs" icon="book" href="https://libretto.sh/docs">
    CLI + library reference for the browser-automation tool used in the examples.
  </Card>
</CardGroup>

***

## When to reach for a browser (vs. an API)

* The target has no API (flight aggregators, airline sites, most SaaS admin UIs).
* The target needs a real logged-in session (cookies + localStorage + JS-challenge cookies).
* You want **AI-driven interaction** — describe a task in English, let the agent figure out the clicks.
* You need screenshots / visual artefacts for verification.

If the site has a good API, use the API. A browser is slower, heavier, and flakier. But when you need it, OpenComputer gives you real VMs — not containers — so you can run full Chromium with no Docker-flavored limitations.

***

## Step 1: Build a snapshot with Chromium pre-installed

Browser setup is heavy (apt packages + Chromium binary is \~500MB). Bake it into a [named snapshot](/sandboxes/snapshots) once, launch sandboxes from it in seconds.

```typescript build-snapshot.ts theme={null}
import { Image, Snapshots } from "@opencomputer/sdk/node";

// Runtime deps Chromium links against on Ubuntu 22.04. Matches Playwright's
// published dependency list.
const CHROMIUM_DEPS = [
  "libnss3", "libnspr4", "libatk1.0-0", "libatk-bridge2.0-0", "libcups2",
  "libdrm2", "libxkbcommon0", "libxcomposite1", "libxdamage1", "libxfixes3",
  "libxrandr2", "libxext6", "libgbm1", "libpango-1.0-0", "libcairo2",
  "libasound2", "fonts-liberation",
  // libnss3-tools gives us `certutil` — needed at runtime to trust OC's
  // egress-proxy CA in Chromium (Chromium ignores SSL_CERT_FILE).
  "libnss3-tools",
];

const image = Image.base()
  .aptInstall(CHROMIUM_DEPS)
  .workdir("/home/sandbox")
  .runCommands(
    "cd /home/sandbox && npm init -y >/dev/null",
    // Install libretto + AI adapter locally so `npx libretto` resolves without
    // a cold npm fetch at runtime.
    "cd /home/sandbox && npm install --no-audit --no-fund libretto @ai-sdk/anthropic",
    // Playwright downloads its own Chromium build — we want headless-shell
    // for lightweight scraping, or full chromium for headed/VNC scenarios.
    "cd /home/sandbox && npx --yes playwright install chromium-headless-shell",
  );

const snapshots = new Snapshots();
await snapshots.create({ name: "browser", image });
```

<Warning>
  **Don't apt-install `chromium-browser` on Ubuntu 22.04.** That package is a snap shim that won't run in a minimal VM. Either install Google Chrome via its apt repo (`google-chrome-stable`), or rely on Playwright's bundled Chromium (recommended — it's purpose-built for automation).
</Warning>

***

## Step 2: Per-boot setup that can't be baked in

A few things need to run at sandbox startup rather than during snapshot build, because they depend on per-sandbox state.

```typescript launch.ts theme={null}
import { Sandbox, SecretStore } from "@opencomputer/sdk/node";

const sandbox = await Sandbox.create({
  snapshot: "browser",
  envs: {
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
    // Keep Playwright/Chromium off the small tmpfs /dev/shm and /tmp —
    // write profile dirs, cache, everything to the data disk.
    TMPDIR: "/home/sandbox/tmp",
  },
  secretStore: "browser-egress",  // see "Networking" section below
});

// Populate /etc/hosts — the guest kernel sets up /etc/resolv.conf but not
// /etc/hosts, and libretto's Playwright CDP client hardcodes http://localhost
// which will ENOTFOUND without this.
await sandbox.commands.run(
  "grep -q 'localhost' /etc/hosts || " +
    "(printf '127.0.0.1 localhost\\n::1 localhost\\n' | sudo tee -a /etc/hosts)",
);

// Trust OC's egress-proxy CA in Chromium's NSS store. Chromium ignores
// SSL_CERT_FILE / NODE_EXTRA_CA_CERTS — the env vars OC sets for libraries
// have no effect on the browser's TLS validation.
await sandbox.commands.run(
  [
    "mkdir -p /home/sandbox/.pki/nssdb",
    "certutil -d sql:/home/sandbox/.pki/nssdb -N --empty-password || true",
    "certutil -d sql:/home/sandbox/.pki/nssdb -A -n opensandbox-proxy -t 'TC,C,T' " +
      "-i /usr/local/share/ca-certificates/opensandbox-proxy.crt",
  ].join(" && "),
);

await sandbox.commands.run("mkdir -p /home/sandbox/tmp && chmod 700 /home/sandbox/tmp");
```

***

## Networking: the `secretStore` requirement

<Warning>
  This is the single most common gotcha. A sandbox without a `secretStore` attached **has no outbound egress at all** — every HTTPS request gets a `407` from the internal proxy.
</Warning>

OpenComputer routes all outbound traffic through a secrets-injection proxy. The proxy only accepts traffic from sandboxes that have at least one sealed secret registered, because session registration happens as part of sealing secrets.

The workaround is to create a `SecretStore` with a wildcard egress allowlist and at least one (possibly dummy) entry:

```typescript theme={null}
import { SecretStore } from "@opencomputer/sdk/node";

const stores = await SecretStore.list();
let store = stores.find((s) => s.name === "browser-egress");
if (!store) {
  store = await SecretStore.create({
    name: "browser-egress",
    egressAllowlist: ["*"],  // wildcard — scope this down for production
  });
}
await SecretStore.setSecret(store.id, "PLACEHOLDER", "not-used-just-triggers-session");

const sandbox = await Sandbox.create({
  snapshot: "browser",
  secretStore: "browser-egress",
});
```

With the store attached, outbound traffic flows normally and the `opensandbox-proxy.crt` we trusted earlier lets Chromium validate the MITM-rewritten certs.

***

## Step 3: Run a headless browser

With the snapshot and per-boot setup in place, driving the browser is a normal libretto session:

```typescript theme={null}
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const run = promisify(execFile);

// Open a page in a named session — libretto persists cookies/localStorage
// per session name in .libretto/sessions/<name>/.
await run("npx", ["libretto", "open", "https://example.com", "--session", "demo", "--headless"], {
  cwd: "/home/sandbox",
});

// AI snapshot — Claude analyzes the page and returns a summary + selectors.
const { stdout } = await run("npx", [
  "libretto", "snapshot", "--session", "demo",
  "--objective", "Describe the main content and interactive elements.",
  "--context", "Freshly loaded page",
], { cwd: "/home/sandbox", maxBuffer: 8 * 1024 * 1024 });

console.log(stdout);
```

The `snapshot` command requires an `ANTHROPIC_API_KEY` (or an OpenAI / Gemini / Vertex key — configure via `.libretto/config.json`). It's the AI-driven feature that makes libretto different from raw Playwright.

***

## Step 4: Run a headed browser (for interactive login)

For workflows where the user needs to log in themselves, you can render the browser to a virtual display and expose it via VNC. This lets you embed the running browser in a web UI.

Install the VNC stack at runtime (same no-rebuild pattern as per-boot setup):

```typescript theme={null}
await sandbox.commands.run(
  "sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq xvfb x11vnc novnc websockify",
);

// Start Xvfb → x11vnc → websockify as long-lived exec sessions so they
// persist across individual commands.
const xvfb = await sandbox.exec.start("Xvfb", {
  args: [":99", "-screen", "0", "1280x800x24", "-ac"],
});
await new Promise((r) => setTimeout(r, 1500));

const x11vnc = await sandbox.exec.start("x11vnc", {
  args: ["-display", ":99", "-forever", "-shared", "-nopw", "-rfbport", "5900", "-quiet"],
});

const websockify = await sandbox.exec.start("websockify", {
  args: ["--web=/usr/share/novnc/", "6080", "localhost:5900"],
});
```

Set `DISPLAY=:99` in the sandbox envs when you create it, then open with `--headed`:

```typescript theme={null}
await run("npx", ["libretto", "open", "https://app.example.com", "--session", "login", "--headed"], {
  cwd: "/home/sandbox",
  env: { ...process.env, DISPLAY: ":99" },
});
```

The VNC WebSocket is available on port 6080 — get its preview URL with `sandbox.getPreviewDomain(6080)` and embed `<iframe src="https://<id>-p6080.<domain>/vnc.html?autoconnect=true">` in your UI. Users click/type directly in the real browser.

***

## Step 5: Persist login across runs

After the user logs in, save the auth state:

```typescript theme={null}
await run("npx", ["libretto", "save", "app.example.com", "--session", "login"], {
  cwd: "/home/sandbox",
});
// → writes /home/sandbox/.libretto/profiles/app.example.com.json
```

The profile lives on the data disk, which survives sandbox hibernation. For cross-sandbox persistence, [snapshot the sandbox](/sandboxes/snapshots) after login and launch future sandboxes from that warm snapshot — they'll boot already logged in.

***

## Resource and concurrency limits

* **Memory per VM** — default is \~1GB. Each headless Chromium uses \~300-500MB; headed full Chromium uses \~500-800MB. Pass `memoryMB: 16384` to `Sandbox.create` for browser-heavy work.
* **File descriptors** — the default `nofile` limit of 1024 is too low for Chromium (which opens hundreds of FDs). Launch the server process under `sudo bash -c "ulimit -n 65535 && exec ..."` to raise it.
* **Concurrency** — with default memory, run 2-3 browsers concurrently per sandbox. With 16GB and proper limits, 5+ works cleanly.

***

## Choosing a browser automation library

| Library                 | Best for                                          | OC integration                                                                   |
| ----------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Playwright** (direct) | Scripted automation with known selectors          | No special setup beyond this guide                                               |
| **libretto**            | AI-agent-driven snapshots + interactive workflows | Shown above                                                                      |
| **browser-use**         | End-to-end natural-language agents                | Install via `pip install browser-use`; set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` |
| **Browserbase**         | Production-grade bot-detection bypass             | Use libretto with `--provider browserbase` + API key                             |

All four run inside OC sandboxes; the snapshot recipe above is compatible with all of them.

***

## Troubleshooting

**`407 from proxy after CONNECT`**
Your sandbox isn't registered with the secrets proxy. Attach a `secretStore` with at least one secret entry.

**Chromium exits with status 1 on launch**
Missing shared library. Check `.libretto/sessions/<name>/logs.jsonl` for the specific `.so` missing. Add it to `CHROMIUM_DEPS` in the snapshot or install at runtime.

**`net::ERR_CERT_AUTHORITY_INVALID`**
Chromium doesn't trust OC's egress-proxy CA. Run the `certutil` NSS-import step from "Per-boot setup".

**`ENOTFOUND localhost`**
The guest's `/etc/hosts` is missing the localhost entry. Run the `grep … /etc/hosts` step from "Per-boot setup".

**`EAGAIN` / `uv_thread_create` / `Killed`**
Out of memory or leaked browser processes from prior runs. Reap stale Chromium processes between sessions (`pkill -9 -f chrome-headless-shell`) and reduce `MAX_CONCURRENT_BROWSERS`.

**Preview URL shows "Waiting for server"**
Your server is bound to `127.0.0.1` instead of `0.0.0.0`. OC's edge forwards from the worker interface, not loopback. Set `hostname: "0.0.0.0"` when calling your web server's `listen()`.

**SSE / streaming responses return 502**
OC's preview-URL edge buffers response bodies — streaming chunks don't reach the client. Use short-polling (`POST /api/job` → `GET /api/job/:id`) instead of SSE or WebSockets for progress updates. WebSockets (for VNC, etc.) *do* pass through as upgrade connections; buffering only affects regular HTTP responses.

***

## Next steps

* Read the [libretto docs](https://libretto.sh/docs) for the full CLI + library reference.
* See [Snapshots](/sandboxes/snapshots) for how to checkpoint a warmed-up browser VM.
* See [Secret Stores](/sandboxes/secrets) for scoping egress and sealing real credentials.


# Build a Lovable Clone
Source: https://docs.opencomputer.dev/guides/build-a-lovable-clone

Build an open-source AI app builder using OpenComputer sandboxes

In this guide you'll build a fully functional **Lovable clone** — an AI-powered web app builder where users describe an app in plain English and get a live, running React application in seconds. The entire project is open-source and uses OpenComputer sandboxes as the execution engine.

<Note>
  For new app-builder projects, start with [Durable Agent Sessions](/agent-sessions/quickstart) and the [app-builder example](https://github.com/diggerhq/oc-sessions-demos). This guide shows the older raw-sandbox orchestration pattern, which is still useful when you want to own the agent loop yourself.
</Note>

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/diggerhq/osslovable">
    Source code for the complete project.
  </Card>

  <Card title="Durable sessions example" icon="github" href="https://github.com/diggerhq/oc-sessions-demos">
    The recommended app-builder architecture for new projects.
  </Card>

  <Card title="Live Demo" icon="globe" href="https://openlovable.cc">
    Try the running app at openlovable.cc.
  </Card>
</CardGroup>

***

## Prerequisites

* **Node.js 20+** installed locally
* An **Anthropic API key** (for Claude)
* An **OpenComputer API key**

***

## Step 1: Sign Up for OpenComputer

Go to [app.opencomputer.dev](https://app.opencomputer.dev) and create an account.

## Step 2: Generate an API Token

From the OpenComputer dashboard, generate an API token. You'll use this to authenticate SDK calls that create and manage sandboxes.

## Step 3: (Optional) Add a Custom Domain

If you want deployed apps to be accessible on your own domain (e.g. `*.mycompany.com`) instead of the default OpenComputer hostnames:

1. In the OpenComputer dashboard, add your domain (e.g. `mycompany.com`).
2. Create a **TXT** record on your domain to verify ownership — the dashboard will show you the exact record to add.
3. Create a **CNAME** record for `*.mycompany.com` pointing to the value provided by OpenComputer. This routes all subdomain traffic to your sandboxes.

Once verified, preview URLs for your sandboxes will be served under your custom domain.

## Step 4: Set Up the Project

Clone the repository and install dependencies:

```bash theme={null}
git clone https://github.com/diggerhq/osslovable.git
cd osslovable
npm run install:all
```

Create a `.env` file at the project root with your API keys:

```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-...
OPENCOMPUTER_API_KEY=your-opencomputer-token
DEPLOY_DOMAIN=mycompany.com  # optional — defaults to openlovable.cc
```

If you configured a custom domain in Step 3, set `DEPLOY_DOMAIN` to that domain so that deployed apps are served under it (e.g. `https://<id>.mycompany.com`). If you skip this, deploy URLs will use the default `openlovable.cc` domain.

Start the development server:

```bash theme={null}
npm run dev
```

This starts both the Express backend (port 3001) and the Vite frontend (port 5173). Open `http://localhost:5173` in your browser, type a prompt, and watch your app get built.

***

## How It Works

The architecture is straightforward: a React frontend sends a user prompt to an Express backend, which orchestrates Claude and an OpenComputer sandbox to generate, write, and run the code.

### Generation Flow

1. **User submits a prompt** — The frontend sends the prompt to `POST /api/generate`.
2. **Sandbox is created** — The server calls `Sandbox.create()` from the OpenComputer SDK to spin up an isolated Node.js environment.
3. **Claude generates code** — The prompt is sent to Claude with a system prompt that instructs it to output complete file contents in a structured XML format (`<file path="...">...</file>`).
4. **Files are streamed and written** — As Claude streams its response, the server parses file blocks in real-time. Each file is written into the sandbox's filesystem using `sandbox.files.write()`.
5. **Dev server starts** — Once all files are written, the server runs `npm install` and starts a Vite dev server inside the sandbox.
6. **Preview URL is returned** — The server calls `sandbox.createPreviewURL({ port: 80 })` to get a public URL, which is sent to the frontend and displayed in an iframe.

### Sandbox as Tool Calls

The key idea is that **every interaction with the sandbox is a tool call** from the server to the OpenComputer SDK. The server uses these SDK methods as its "tools":

```typescript theme={null}
import { Sandbox } from "@opencomputer/sdk";

// Create an isolated environment
const sandbox = await Sandbox.create({ template: "node", timeout: 600 });

// Write files
await sandbox.files.write("/workspace/src/App.tsx", code);

// Run commands
await sandbox.exec.run("cd /workspace && npm install");

// Get a public URL
const preview = await sandbox.createPreviewURL({ port: 80 });
```

This is a simple but effective pattern: Claude generates the code as text, and the server uses the sandbox SDK to make it real. There are no actual LLM tool-use calls involved — the server orchestrates everything itself.

### Limitations of This Approach

* **No iterative editing** — Claude generates the entire project in one shot. There's no back-and-forth where the LLM can see errors, fix them, and retry. A more robust version would use Claude's tool-use capability to let it write files, run commands, see output, and iterate.
* **No persistent state** — The development sandbox is ephemeral. If the server restarts, in-memory sandbox references are lost. There's no git history or checkpoint system to restore previous states.
* **Single-turn only** — Each prompt creates a fresh generation. Follow-up prompts create a new sandbox rather than iterating on the existing code.

***

## Deployment Model

The app includes a **Deploy** button that creates a shareable, publicly accessible URL for the generated app.

### How Deployment Works

1. **A new sandbox is created** — Deployment does *not* reuse the development sandbox. A fresh sandbox is spun up specifically for the deployed version.
2. **Files are copied over** — All source files (excluding `node_modules`) are copied from the dev sandbox to the deploy sandbox using the SDK's file APIs.
3. **Dependencies are installed and the server starts** — The deploy sandbox runs `npm install` and starts the Vite dev server, just like the dev sandbox.
4. **A fixed deploy URL is created** — The server calls `sandbox.createPreviewURL()` with a custom domain configuration, producing a stable URL (e.g. `https://<id>.openlovable.cc`) that can be shared with others.

```typescript theme={null}
const domain = process.env.DEPLOY_DOMAIN || "openlovable.cc";
const url = await sandbox.createPreviewURL({
  port: 80,
  domain,
  authConfig: {},
});
```

### Why a Separate Sandbox?

The deploy sandbox is intentionally separate from the dev sandbox so that:

* The developer can keep iterating in the dev sandbox without affecting the deployed version.
* The deployed version has a fixed, shareable URL that doesn't change.
* Each deployment is a clean, reproducible build.

### Hibernation and Wake-Up

OpenComputer sandboxes have a built-in **hibernation model**. When a deployed sandbox receives no traffic, it is automatically hibernated to save resources. When someone visits the deploy URL, the sandbox is woken up on demand. This means:

* **Deploy URLs are persistent** — they continue to work even after the sandbox hibernates.
* **Cold starts are fast** — sandboxes resume from hibernation in seconds.
* **No always-on cost** — you're not paying for idle compute.

This makes the deployment model practical for sharing prototypes and demos without running up a large bill.

***

## Limitations and What's Coming

### Current Limitations

* **No version control** — There is no git server backing the sandbox, so there's no way to checkpoint, diff, or roll back changes. If you want to restore a previous version, you'd need to regenerate it.
* **No secret management** — API keys and environment variables are passed in plain text. There's no built-in mechanism for securely sealing secrets that the sandbox needs at runtime.
* **Ephemeral dev state** — The development sandbox lives only as long as the server process. A server restart or crash loses all active sandbox references.
* **Single-turn generation** — The current architecture doesn't support multi-turn conversations where Claude can iterate on its output based on build errors or user feedback.
* **No private link sharing** — Deploy URLs are either fully public or not accessible at all. There's no way to share a preview link with specific team members or collaborators behind authentication.

### What's Changed Since This Guide Was Written

Several features mentioned as limitations now exist in OpenComputer:

* **In-sandbox agent loop** — [Agent sessions](/agent-sessions/overview) now run the Claude Agent SDK inside the sandbox. The agent reads files, runs commands, and iterates on errors locally without leaving the VM. This is the recommended approach for new projects.
* **Preview URL authentication** — `authConfig` on [preview URLs](/sandboxes/preview-urls) supports restricting access. Not full private link sharing yet, but a step toward it.
* **Checkpoints** — [Checkpoint and fork](/sandboxes/checkpoints) workflows are available for snapshotting sandbox state, restoring, and branching.
* **Custom templates** — Define [custom environments](/sandboxes/templates) with the Image builder and pre-built snapshots.

### Still Planned

* **Built-in git server** — Git-based version control for sandbox state
* **Secret sealing** — Encrypted secrets decrypted only inside the sandbox at runtime


# How It Works
Source: https://docs.opencomputer.dev/how-it-works

Architecture and key technical decisions

Your code talks to a **control plane** API, which provisions a virtual machine on a worker node. Commands and file operations run inside that VM — I/O streams back over WebSocket. The control plane transparently proxies data-plane requests to the correct worker.

SDK users only need an API key. The SDK handles routing automatically.

<Steps>
  <Step title="Create">
    Your code calls the control plane (`X-API-Key` auth). A VM boots from a golden snapshot in \~300ms.
  </Step>

  <Step title="Operate">
    Run commands, read/write files — all execution happens inside the VM. The control plane routes requests to the correct worker automatically.
  </Step>
</Steps>

## Virtual Machines

Each sandbox is a real virtual machine with its own Linux kernel, memory, and disk. Isolation is hardware-level (KVM), not namespace-based like containers.

Why not containers? Containers share a kernel. A kernel exploit in one container compromises every other container on the host. KVM-based VMs eliminate that attack surface entirely.

## Hibernation

`hibernate()` snapshots the VM's memory and disk state, then stops it. No compute costs while hibernated. `wake()` restores the sandbox — the platform attempts a fast snapshot-based resume and falls back to a cold boot from the saved disk state if needed.

The sandbox keeps the same ID across hibernate/wake cycles. A rolling idle timeout (default 300s) auto-hibernates sandboxes that go unused.

## Checkpoints & Forking

A checkpoint is a named snapshot of a running sandbox. You can:

* **Restore** — revert the sandbox in-place (all changes since the checkpoint are lost)
* **Fork** — create a new sandbox from the checkpoint

Forking preserves the filesystem and installed packages. The new sandbox starts with a fresh boot from that disk state — don't assume running processes carry over.

```bash theme={null}
# Checkpoint, then fork two independent sandboxes
oc checkpoint create sb-abc --name ready-state
oc checkpoint spawn cp-xyz   # → sandbox A
oc checkpoint spawn cp-xyz   # → sandbox B
```

Maximum 10 full checkpoints or 100 disk-only checkpoints per sandbox.

## Templates

Templates define the sandbox environment. The default template includes Ubuntu, Python 3, Node.js, and common CLI tools.

For custom environments, use the **Image builder** to define dependencies programmatically, or create **pre-built snapshots** for instant reuse:

```typescript theme={null}
// On-demand image (built + cached by content hash)
const image = Image.base().aptInstall(['curl']).pipInstall(['pandas']);
const sandbox = await Sandbox.create({ image });

// Pre-built snapshot (instant boot)
const sandbox = await Sandbox.create({ snapshot: 'my-custom-stack' });
```

See [Templates](/sandboxes/templates) for the full guide.

## Elasticity

Sandboxes can scale memory at runtime via an internal metadata endpoint (`http://169.254.169.254/v1/scale`) accessible from inside the VM. CPU scales proportionally. This lets workloads request more resources before heavy tasks and release them after. See [Elasticity](/sandboxes/elasticity) for details.

## Networking

Every sandbox gets full outbound internet access via a TAP device with NAT. No firewall or allowlist to configure.

For inbound access, create a **preview URL** that reverse-proxies public traffic to a port inside the sandbox:

```bash theme={null}
oc preview create sb-abc --port 3000
```

See [Preview URLs](/sandboxes/preview-urls) for custom domains and auth.

<Tip>
  API details: [HTTP API Reference](/reference/api#base-url--authentication).
</Tip>


# Introduction
Source: https://docs.opencomputer.dev/introduction

Cloud sandboxes for AI apps

OpenComputer gives you a full Linux VM in the cloud. Each sandbox is an isolated virtual machine with its own filesystem, network, and process space — persistent, long-running, and capable of hibernating when idle. Write files, install packages, run commands, and build complete projects inside secure, isolated environments.

<CardGroup>
  <Card title="Full Linux VM" icon="server">
    Not a container. Real VM with its own kernel, memory, and disk. Hardware-level isolation via KVM.
  </Card>

  <Card title="Long-running" icon="clock">
    Hours or days, not minutes. Install packages, build projects, run test suites, iterate — no cold starts between steps.
  </Card>

  <Card title="Checkpoint & fork" icon="code-branch">
    Named snapshots you can fork from. Try five approaches in parallel from the same starting point — like git branches for VMs.
  </Card>

  <Card title="Elastic compute" icon="gauge-high">
    Scale memory and CPU at runtime. Request more resources for heavy tasks and release them after.
  </Card>
</CardGroup>

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @opencomputer/sdk
  ```

  ```bash pip theme={null}
  pip install opencomputer-sdk
  ```

  ```bash CLI theme={null}
  # Installs to ~/.local/bin (no sudo). See cli/overview for manual install.
  curl -fsSL https://raw.githubusercontent.com/diggerhq/opencomputer/main/scripts/install.sh | bash
  ```
</CodeGroup>

```bash theme={null}
export OPENCOMPUTER_API_KEY=your-api-key
```

<Tip>Grab your API key from [app.opencomputer.dev](https://app.opencomputer.dev)</Tip>

## Quick Example

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();
  const result = await sandbox.commands.run("echo 'Hello World from OpenSandbox!'");
  console.log(result.stdout);
  await sandbox.kill();
  ```

  ```python Python theme={null}
  import asyncio
  from opencomputer import Sandbox

  async def main():
      sandbox = await Sandbox.create()
      result = await sandbox.commands.run("echo 'Hello World from OpenSandbox!'")
      print(result.stdout)
      await sandbox.kill()

  asyncio.run(main())
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first sandbox in 2 minutes
  </Card>

  <Card title="How It Works" icon="microchip" href="/how-it-works">
    Architecture: VMs, hibernation, checkpoints
  </Card>

  <Card title="Sandboxes" icon="box" href="/sandboxes/overview">
    The compute primitive
  </Card>

  <Card title="Working with Files" icon="file" href="/sandboxes/working-with-files">
    Upload, download, and manage files
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.opencomputer.dev/quickstart

Create your first sandbox in 2 minutes

## Prerequisites

An OpenComputer API key and the SDK installed. See [Introduction](/introduction) for install instructions.

```bash theme={null}
export OPENCOMPUTER_API_KEY=your-api-key
```

<Tip>Grab your API key from [app.opencomputer.dev](https://app.opencomputer.dev)</Tip>

## Create Your First Sandbox

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();

  // Run a command inside the sandbox
  const result = await sandbox.commands.run("echo 'Hello World from OpenSandbox!'");
  console.log(result.stdout);

  await sandbox.kill();
  ```

  ```python Python theme={null}
  import asyncio
  from opencomputer import Sandbox

  async def main():
      sandbox = await Sandbox.create()

      # Run a command inside the sandbox
      result = await sandbox.commands.run("echo 'Hello World from OpenSandbox!'")
      print(result.stdout)

      await sandbox.kill()

  asyncio.run(main())
  ```
</CodeGroup>

Running this will print:

```
Hello World from OpenSandbox!
```

<Note>
  Your sandboxes stay alive as long as you need them. They don't shut down after a command finishes — you can keep running commands, installing packages, and building projects for hours or days. Sandboxes only stop when you explicitly kill them or when the idle timeout expires (default 5 minutes, configurable).
</Note>

## Next Steps

<CardGroup>
  <Card title="Elastic Compute" icon="gauge-high" href="/sandboxes/elasticity">
    Scale memory and CPU at runtime based on workload
  </Card>

  <Card title="Upload & Download Files" icon="file-arrow-up" href="/sandboxes/working-with-files">
    Read, write, and transfer files to and from sandboxes
  </Card>

  <Card title="Custom Sandboxes" icon="palette" href="/sandboxes/templates">
    Build custom environments with your own packages and tools
  </Card>

  <Card title="Checkpoints" icon="code-branch" href="/sandboxes/checkpoints">
    Snapshot and fork VMs for parallel experimentation
  </Card>
</CardGroup>


# Agent URLs and Hooks
Source: https://docs.opencomputer.dev/reference/cli/agent

Invoke agents and manage scoped Hook URLs

These commands use the Durable Agent Sessions API and the API key configured by
`oc login`, `OPENCOMPUTER_API_KEY`, or `--api-key`.

## oc agent invoke

Start a durable session through an agent's canonical URL:

```bash theme={null}
oc agent invoke <id|name> \
  [--data '<json>' | --file <path> | --stdin] \
  [--idempotency-key <key>] \
  [--json]
```

`--data` defaults to `{}`. The CLI rejects non-JSON input locally, calls exact
`POST /` with the configured org key, and prints the accepted session id plus
follow/steer commands. It generates one idempotency key and keeps it stable
across automatic retries; supply your own key when separate command runs must
converge.

With `--json`, the output is the complete acceptance receipt, including the
one-hour session client token and canonical event/message links. Treat that
output as a session-scoped credential.

Use `oc session create` instead when you need model, source, destination, or
per-session limit overrides.

## oc agent hook create

```bash theme={null}
oc agent hook create <name> --agent <id|name> \
  [--expires-at <rfc3339>] [--json]
```

Creates a named Hook and prints its complete secret URL once. If `--agent` is
omitted, the CLI resolves the agent from `agent.toml` in the current directory.

## oc agent hooks

```bash theme={null}
oc agent hooks --agent <id|name> \
  [--include-revoked] [--cursor <cursor>] [--limit <n>] [--json]
```

Lists secret-free Hook metadata. Pagination is newest-first and the server caps
`--limit` at 100.

## oc agent hook get

```bash theme={null}
oc agent hook get <hook-id|name> --agent <id|name> [--json]
```

Shows status, expiry, secret last four, and revoke reason. It cannot recover the
complete URL.

## oc agent hook revoke

```bash theme={null}
oc agent hook revoke <hook-id|name> --agent <id|name> [--yes] [--json]
```

Irreversibly revokes the Hook after confirmation. Create and install a
replacement first if the external integration must stay available.


# Login and identity
Source: https://docs.opencomputer.dev/reference/cli/auth

Sign the local CLI in to OpenComputer

## `oc login`

```bash theme={null}
oc login [--no-browser] [--force]
```

The CLI prints a short confirmation code and a complete HTTPS sign-in URL,
then waits for approval. It tries to open the URL on a local machine; browser
failure does not stop the flow.

* `--no-browser` only prints the URL, which is useful over SSH or when a coding
  agent is running the command.
* `--force` replaces an existing saved credential. A prior CLI-created key is
  revoked only after the replacement is saved and verified. If its previous API
  is unreachable, replacement continues with a warning and that old key remains
  available for manual revocation. A manually configured key is replaced
  locally but never remotely revoked.

The credential is stored in `~/.oc/config.json` with private permissions and is
never printed, including under `--json`. If `--api-key` or
`OPENCOMPUTER_API_KEY` is active, unset that override before logging in.
When an API URL override differs from a saved login, the CLI requires an
explicit replacement rather than reporting the old host as logged in. Remote
login endpoints should use HTTPS; the CLI warns before sending credentials to
a non-loopback HTTP URL.

`oc login` is for a person's local CLI. CI, servers, and SDK applications
should keep using an explicit org API key supplied through their secret
manager.

## `oc whoami`

```bash theme={null}
oc whoami
oc whoami --json
```

Shows the authenticated user, workspace, org id, and API URL for the effective
credential.

## `oc logout`

```bash theme={null}
oc logout
oc logout --local
```

For a CLI-managed login, `oc logout` first revokes that exact key and only then
clears it from the config file. If remote revocation is ambiguous, the local
credential is retained and the command fails so it cannot claim a still-live
key was revoked.

`--local` explicitly clears local login state without remote revocation.
It remains available when an environment or flag key currently overrides the
saved login. Manually configured and environment-provided keys are never
remotely revoked by this command.


# oc checkpoint
Source: https://docs.opencomputer.dev/reference/cli/checkpoint

Manage sandbox checkpoints

**Alias:** `oc cp`

## `oc checkpoint create <sandbox-id>`

Create a named checkpoint of a running sandbox. [HTTP API →](/api-reference/checkpoints/create)

<ParamField type="string">
  Checkpoint name
</ParamField>

<ParamField type="string">
  Optional retention policy. Use `delete_oldest` to delete the oldest eligible checkpoint before creating this one.
</ParamField>

<ParamField type="int">
  Maximum checkpoints of this type to keep when `--retention-policy delete_oldest` is set. Must be between 1 and 10 for full checkpoints, or 1 and 100 for disk-only checkpoints.
</ParamField>

```bash theme={null}
oc cp create sb-abc --name before-migration
```

```bash theme={null}
oc cp create sb-abc \
  --name autosave \
  --kind disk_only \
  --retention-policy delete_oldest \
  --retention-max-count 100
```

***

## `oc checkpoint list <sandbox-id>`

List checkpoints for a sandbox. [HTTP API →](/api-reference/checkpoints/list)

Output columns: `ID`, `NAME`, `STATUS`, `SIZE`, `CREATED`

***

## `oc checkpoint restore <sandbox-id> <checkpoint-id>`

Revert a sandbox in-place to a checkpoint. All changes since the checkpoint are lost. [HTTP API →](/api-reference/checkpoints/restore)

***

## `oc checkpoint spawn <checkpoint-id>`

Create a new sandbox from a checkpoint (fork). [HTTP API →](/api-reference/checkpoints/fork)

<ParamField type="int">
  Idle timeout for the new sandbox
</ParamField>

```bash theme={null}
ID=$(oc cp spawn cp-xyz --json | jq -r '.sandboxID')
oc exec "$ID" --wait -- echo "forked sandbox ready"
```

***

## `oc checkpoint delete <sandbox-id> <checkpoint-id>`

Delete a checkpoint. [HTTP API →](/api-reference/checkpoints/delete)


# oc config
Source: https://docs.opencomputer.dev/reference/cli/config

CLI configuration

Manage CLI configuration. Settings are persisted to a local config file.

For an interactive local setup, prefer [`oc login`](/reference/cli/auth). Use
`oc config set api-key` for a separately managed key.

## `oc config set <key> <value>`

Supported keys: `api-key`, `api-url`.

```bash theme={null}
oc config set api-key sk-1234...
oc config set api-url https://app.opencomputer.dev
```

Setting `api-key` explicitly clears CLI-login management metadata, so a later
`oc logout` cannot revoke a manually supplied key.

***

## `oc config show`

Display current configuration. The API key is masked (first 4 and last 4 characters shown).


# oc exec
Source: https://docs.opencomputer.dev/reference/cli/exec

Execute commands inside a sandbox

## `oc exec <id> [flags] -- <command...>`

By default, creates an **exec session** and prints the session ID with attach instructions. Use `--wait` to run synchronously.

[HTTP API →](/api-reference/exec/run)

<ParamField type="boolean">
  Wait for completion, stream output, mirror exit code
</ParamField>

<ParamField type="string">
  Working directory
</ParamField>

<ParamField type="int">
  Timeout in seconds (0 = none)
</ParamField>

<ParamField type="string">
  Environment variable `KEY=VALUE` (repeatable)
</ParamField>

```bash theme={null}
# Synchronous — streams output, exits with process exit code
oc exec sb-abc --wait -- npm run build

# Asynchronous — creates session, prints session ID
oc exec sb-abc -- node server.js
# → Session es-xyz created. Attach with: oc exec attach sb-abc es-xyz
```

***

## `oc exec list <id>`

List active exec sessions for a sandbox. [HTTP API →](/api-reference/exec/list-sessions)

Output: session ID, status (`running` or `exited (code)`), command, client count.

***

## `oc exec attach <id> <session-id>`

<Warning>
  Not yet implemented. The command exists but prints guidance to use the SDK or a WebSocket client (`websocat`).
</Warning>

***

## `oc exec kill <id> <session-id>`

Kill an exec session. [HTTP API →](/api-reference/exec/kill-session)

<ParamField type="int">
  Signal number (default: SIGKILL)
</ParamField>


# CLI Reference
Source: https://docs.opencomputer.dev/reference/cli/overview

Every command, subcommand, and flag

## Global Flags

These flags apply to all commands.

<ParamField type="string">
  API key for authentication. Env: `OPENCOMPUTER_API_KEY`
</ParamField>

<ParamField type="string">
  Control plane URL. Env: `OPENCOMPUTER_API_URL`
</ParamField>

<ParamField type="boolean">
  Output as JSON
</ParamField>

## Commands

<CardGroup>
  <Card title="oc sandbox" icon="box" href="/reference/cli/sandbox">
    Manage sandbox lifecycle
  </Card>

  <Card title="oc exec" icon="terminal" href="/reference/cli/exec">
    Execute commands inside a sandbox
  </Card>

  <Card title="oc shell" icon="rectangle-terminal" href="/reference/cli/shell">
    Interactive terminal access
  </Card>

  <Card title="oc checkpoint" icon="camera" href="/reference/cli/checkpoint">
    Manage sandbox checkpoints
  </Card>

  <Card title="oc patch" icon="file-code" href="/reference/cli/patch">
    Manage checkpoint patches
  </Card>

  <Card title="oc preview" icon="globe" href="/reference/cli/preview">
    Manage preview URLs
  </Card>

  <Card title="oc agent" icon="robot" href="/reference/cli/agent">
    Invoke agents and manage Hook URLs
  </Card>

  <Card title="oc login" icon="right-to-bracket" href="/reference/cli/auth">
    Sign in, inspect identity, and log out
  </Card>

  <Card title="oc config" icon="gear" href="/reference/cli/config">
    CLI configuration
  </Card>
</CardGroup>


# oc patch
Source: https://docs.opencomputer.dev/reference/cli/patch

Manage checkpoint patches

Patches are scripts that run when a sandbox is spawned from a checkpoint.

## `oc patch create <checkpoint-id>`

[HTTP API →](/api-reference/patches/create)

<ParamField type="string">
  Path to script file, or `-` for stdin
</ParamField>

<ParamField type="string">
  Patch description
</ParamField>

```bash theme={null}
oc patch create cp-xyz --script=./setup.sh --description="Install deps"
echo "apt install -y curl" | oc patch create cp-xyz --script=-
```

***

## `oc patch list <checkpoint-id>`

[HTTP API →](/api-reference/patches/list)

Output columns: `ID`, `SEQ`, `DESCRIPTION`, `STRATEGY`, `CREATED`

***

## `oc patch delete <checkpoint-id> <patch-id>`

[HTTP API →](/api-reference/patches/delete)


# oc preview
Source: https://docs.opencomputer.dev/reference/cli/preview

Manage preview URLs

Expose sandbox ports to the internet.

## `oc preview create <sandbox-id>`

[HTTP API →](/api-reference/preview/create)

<ParamField type="int">
  Container port to expose
</ParamField>

<ParamField type="string">
  Custom domain
</ParamField>

```bash theme={null}
oc preview create sb-abc --port 3000
```

***

## `oc preview list <sandbox-id>`

[HTTP API →](/api-reference/preview/list)

Output columns: `PORT`, `HOSTNAME`, `SSL`, `CREATED`

***

## `oc preview delete <sandbox-id> <port>`

[HTTP API →](/api-reference/preview/delete)

***

## `oc preview rotate-auth <sandbox-id>`

[HTTP API →](/api-reference/preview/rotate-auth)

Mint a new bearer token for the sandbox's preview URLs. The old token stops working immediately. The new plaintext is printed once — capture it before moving on; the server will not return it again.

```bash theme={null}
oc preview rotate-auth sb-abc
# New preview auth token (shown once): qx2sSi5IYX...
```

Calling this on a sandbox that was created without `--preview-auth` installs a token and starts enforcing the gate from that point on.

See [`oc sandbox create --preview-auth`](/reference/cli/sandbox#oc-sandbox-create) to enable at create time, or [`--preview-auth-token`](/reference/cli/sandbox#oc-sandbox-create) to bring your own.


# oc sandbox
Source: https://docs.opencomputer.dev/reference/cli/sandbox

Manage sandbox lifecycle

## `oc sandbox create`

Create a new sandbox. **Alias:** `oc create`

[HTTP API →](/api-reference/sandboxes/create)

<ParamField type="int">
  Idle timeout in seconds
</ParamField>

<ParamField type="int">
  CPU cores (0 = platform default)
</ParamField>

<ParamField type="int">
  Memory in MB (0 = platform default)
</ParamField>

<ParamField type="string">
  Environment variable `KEY=VALUE` (repeatable)
</ParamField>

<ParamField type="string">
  Metadata `KEY=VALUE` (repeatable)
</ParamField>

<ParamField type="bool">
  Require a bearer token on the sandbox's preview URLs. The server generates a 256-bit random token and prints it once. See [Preview-URL authentication](/sandboxes/preview-urls#authentication).
</ParamField>

<ParamField type="string">
  Bring your own preview-URL bearer token (≥16 characters). Implies `--preview-auth`. Useful when your gateway already has a shared secret.
</ParamField>

```bash theme={null}
oc create --timeout 600 --cpu 2 --memory 1024 --env NODE_ENV=production
oc create --preview-auth                                    # server-generated token
oc create --preview-auth-token "$GATEWAY_TOKEN"             # bring your own
```

***

## `oc sandbox list`

List all running sandboxes. **Alias:** `oc ls`

[HTTP API →](/api-reference/sandboxes/list)

Output columns: `ID`, `TEMPLATE`, `STATUS`, `CPU`, `MEM`, `AGE`

```bash theme={null}
oc ls
oc ls --json
```

***

## `oc sandbox get <id>`

Show detailed information for a sandbox. [HTTP API →](/api-reference/sandboxes/get)

Output: ID, Template, Status, CPU, Memory, Started, Ends.

***

## `oc sandbox kill <id>`

Terminate and remove a sandbox. [HTTP API →](/api-reference/sandboxes/delete)

***

## `oc sandbox hibernate <id>`

Snapshot VM state and stop the sandbox. Displays snapshot size on success. [HTTP API →](/api-reference/sandboxes/hibernate)

***

## `oc sandbox wake <id>`

Resume a hibernated sandbox. [HTTP API →](/api-reference/sandboxes/wake)

<ParamField type="int">
  Idle timeout in seconds after wake
</ParamField>

***

## `oc sandbox set-timeout <id> <seconds>`

Update the idle timeout for a running sandbox. [HTTP API →](/api-reference/sandboxes/set-timeout)

```bash theme={null}
oc sandbox set-timeout sb-abc123 600
```

***

For commands that resize a sandbox or freeze its size — `scale`, `autoscale`, `lock`, `unlock`, `lock-status` — see [Scaling](/reference/cli/scaling).

***

## `oc sandbox allowed-hosts <id>`

Show the egress allowlist + per-secret allowed hosts the sandbox's secrets proxy enforces. Useful for debugging "why is my outbound HTTP call being blocked" without having to cross-reference the [secret store](/sandboxes/secrets) config separately.

Sandboxes created without `--secret-store` return an empty allowlist — the sandbox has no per-store egress restriction.

```bash theme={null}
oc sandbox allowed-hosts sb-abc123
# Sandbox sb-abc123 (secret store: my-store)
#
# Egress allowlist:
#   • api.openai.com
#   • api.anthropic.com
#
# Per-secret allowed hosts:
#   OPENAI_API_KEY:
#     • api.openai.com
```

Use `--json` for the structured form:

```bash theme={null}
oc sandbox allowed-hosts sb-abc123 --json
```

```json theme={null}
{
  "sandboxID": "sb-abc123",
  "secretStore": "my-store",
  "egressAllowlist": ["api.openai.com", "api.anthropic.com"],
  "perSecretAllowedHosts": {
    "OPENAI_API_KEY": ["api.openai.com"]
  }
}
```

### Layered forks

When a fork layers an additional `--secret-store` on top of an inherited one, `egressAllowlist` is the **union** of both stores' allowlists (matches what the runtime proxy enforces). The response includes both store names — `secretStore` is the primary (whose secrets shadow the base on env-name collisions), `baseSecretStore` is the inherited parent:

```json theme={null}
{
  "sandboxID": "sb-fork456",
  "secretStore": "fork-override",
  "baseSecretStore": "fork-parent",
  "egressAllowlist": ["api.openai.com", "api.anthropic.com", "api.example.com"],
  "perSecretAllowedHosts": {
    "OPENAI_API_KEY": ["api.openai.com"]
  }
}
```

`baseSecretStore` is omitted in the single-store case (no layering).


# oc sandbox scaling
Source: https://docs.opencomputer.dev/reference/cli/scaling

Resize sandboxes, configure autoscale, and manage scaling locks from the CLI

The CLI groups three related actions for sizing a sandbox:

| Command                                                                                                                    | What it does                                               |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`oc sandbox autoscale`](#oc-sandbox-autoscale-id)                                                                         | Turn the platform autoscaler on/off and inspect its config |
| [`oc sandbox scale`](#oc-sandbox-scale-id-memory-mb)                                                                       | Manually resize once                                       |
| [`oc sandbox lock`](#oc-sandbox-lock-id) / [`unlock`](#oc-sandbox-unlock-id) / [`lock-status`](#oc-sandbox-lock-status-id) | Freeze or unfreeze the current size                        |

CPU follows memory per the platform's tier table; you don't pick CPU separately.

For the underlying concepts and how these three modes interact, see the [Elasticity](/sandboxes/elasticity) guide.

***

## `oc sandbox autoscale <id>`

Configure or inspect per-sandbox autoscale. [HTTP API →](/api-reference/sandboxes/autoscale)

Run with no flags to print the current configuration:

```bash theme={null}
oc sandbox autoscale sb-abc123
# Autoscale enabled for sb-abc123 (1024–16384 MB)
```

Enable with bounds:

```bash theme={null}
oc sandbox autoscale sb-abc123 --on --min 1024 --max 16384
```

Disable:

```bash theme={null}
oc sandbox autoscale sb-abc123 --off
```

When enabled, the platform watches memory pressure and resizes the sandbox between `--min` and `--max`:

* **Scale up** on a single 1-min sample above 75 % memory utilization. Cooldown 60 s between up-scales.
* **Scale down** only when the 1-min, 5-min, AND 15-min averages all sit below 25 %. Cooldown 5 min between down-scales.

The asymmetry is deliberate: rapid response when the user notices lag, conservative shrink after sustained idle.

**Flags**

| Flag      | Description                                        |
| --------- | -------------------------------------------------- |
| `--on`    | Enable autoscale (requires `--min` and `--max`).   |
| `--off`   | Disable autoscale. Mutually exclusive with `--on`. |
| `--min N` | Minimum memory in MB.                              |
| `--max N` | Maximum memory in MB. Must be ≥ `--min`.           |

**Errors**

* `scaling_locked` — the sandbox has a scaling lock active. Run `oc sandbox unlock <id>` first.
* `402 Payment Required` — `--max` exceeds your plan cap.

***

## `oc sandbox scale <id> <memory-mb>`

Manually resize a sandbox to a specific memory tier. [HTTP API →](/api-reference/sandboxes/scale)

```bash theme={null}
oc sandbox scale sb-abc123 8192
# Scaled sb-abc123 to 8192MB / 400% CPU
```

A manual scale **disables autoscale** on this sandbox as a side effect — explicit intent overrides the loop. Re-enable with `oc sandbox autoscale --on` if you want size to track load again.

**Errors**

* `scaling_locked` — the sandbox has a scaling lock active. Run `oc sandbox unlock <id>` first.
* `402 Payment Required` — requested size exceeds your plan cap.

***

## `oc sandbox lock <id>`

Pin a sandbox at its current size. [HTTP API →](/api-reference/sandboxes/scaling-lock)

```bash theme={null}
oc sandbox lock sb-abc123
# Sandbox sb-abc123 locked (scaling disabled)
```

While locked:

* `oc sandbox scale` is rejected with `scaling_locked`.
* `oc sandbox autoscale --on` is rejected with `scaling_locked`.
* The platform autoscaler skips the sandbox entirely.

Locking **also** disables autoscale (single knob — "I don't want this scaling, period"). Unlocking does NOT re-enable autoscale; run `oc sandbox autoscale --on` explicitly if you want it back.

***

## `oc sandbox unlock <id>`

Clear the scaling lock.

```bash theme={null}
oc sandbox unlock sb-abc123
# Sandbox sb-abc123 unlocked
```

***

## `oc sandbox lock-status <id>`

Print the current scaling-lock state.

```bash theme={null}
oc sandbox lock-status sb-abc123
# Sandbox sb-abc123 is unlocked
```


# oc shell
Source: https://docs.opencomputer.dev/reference/cli/shell

Interactive terminal access

## `oc shell <id>`

Open an interactive terminal (PTY) session via WebSocket. [HTTP API →](/api-reference/pty/create)

<ParamField type="string">
  Shell to use
</ParamField>

Terminal size is auto-detected and resize events are forwarded. Press `Ctrl+D` or type `exit` to disconnect. The PTY session is cleaned up automatically on exit.

```bash theme={null}
oc shell sb-abc123
oc shell sb-abc123 --shell /bin/zsh
```


# Exec
Source: https://docs.opencomputer.dev/reference/python-sdk/exec

Run commands and manage exec sessions

Accessed via `sandbox.exec`.

## `await sandbox.exec.run(command, ...)`

Run a command synchronously via `sh -c`. [HTTP API →](/api-reference/exec/run)

<ParamField type="str">
  Shell command
</ParamField>

<ParamField type="int">
  Timeout in seconds
</ParamField>

<ParamField type="dict[str, str]">
  Environment variables
</ParamField>

<ParamField type="str">
  Working directory
</ParamField>

**Returns:** `ProcessResult`

```python theme={null}
result = await sandbox.exec.run("npm test", cwd="/app")
```

***

## `await sandbox.exec.start(command, ...)`

Start a long-running command with streaming I/O. [HTTP API →](/api-reference/exec/create-session)

<ParamField type="str">
  Command
</ParamField>

<ParamField type="list[str]">
  Arguments
</ParamField>

<ParamField type="dict[str, str]">
  Environment variables
</ParamField>

<ParamField type="str">
  Working directory
</ParamField>

<ParamField type="int">
  Timeout in seconds
</ParamField>

<ParamField type="int">
  Seconds to keep running after disconnect
</ParamField>

<ParamField type="Callable[[bytes], None]">
  Stdout callback
</ParamField>

<ParamField type="Callable[[bytes], None]">
  Stderr callback
</ParamField>

<ParamField type="Callable[[int], None]">
  Exit callback
</ParamField>

**Returns:** `ExecSession`

```python theme={null}
session = await sandbox.exec.start(
    "node", args=["server.js"], cwd="/app",
    on_stdout=lambda b: print(b.decode(), end=""),
    on_exit=lambda code: print(f"exited {code}"),
)
exit_code = await session.done
```

***

## `await sandbox.exec.background(command, ...)`

Alias for [`start`](#await-sandbox-exec-start-command). Same signature, same return type. Use when the intent is "run this in the background and observe it".

```python theme={null}
server = await sandbox.exec.background("npm", args=["run", "dev"])
```

***

## `await sandbox.exec.shell(...)`

Open a stateful shell session. Subsequent `.run()` calls share the same bash process, so `cwd`, exported env vars, and shell functions persist — the ergonomics of a terminal tab.

Backed by a long-running `bash --noprofile --norc` session. Foreground-only: concurrent `.run()` raises `ShellBusyError`.

<ParamField type="str">
  Initial working directory
</ParamField>

<ParamField type="dict[str, str]">
  Initial environment variables
</ParamField>

**Returns:** `Shell`

```python theme={null}
sh = await sandbox.exec.shell(cwd="/app")

await sh.run("npm install")
await sh.run("export NODE_ENV=test")
r = await sh.run("npm test", on_stdout=lambda b: print(b.decode(), end=""))
print(r.exit_code)

await sh.close()
```

### Shell

| Member                               | Type            | Description                                 |
| ------------------------------------ | --------------- | ------------------------------------------- |
| `session_id`                         | `str`           | Underlying exec session ID                  |
| `run(cmd, on_stdout=?, on_stderr=?)` | `ProcessResult` | Run a command, blocking until it exits      |
| `close()`                            | `None`          | Write `exit` and wait for bash to terminate |

<Note>
  Per-call `cwd`, `env`, and `timeout` are intentionally not supported in v1. Use inline shell syntax (`cd /x && cmd`, `FOO=bar cmd`) — the shell state carries across calls.
</Note>

Errors:

* `ShellBusyError` — another `run()` is in flight (shell is foreground-only).
* `ShellClosedError` — bash has exited (explicit `close()`, a command ran `exit`, or the session dropped).

***

## `await sandbox.exec.attach(session_id, ...)`

Reconnect to a running exec session over WebSocket.

<ParamField type="str">
  Session ID
</ParamField>

<ParamField type="Callable[[bytes], None]">
  Stdout callback
</ParamField>

<ParamField type="Callable[[bytes], None]">
  Stderr callback
</ParamField>

<ParamField type="Callable[[int], None]">
  Exit callback
</ParamField>

<ParamField type="Callable[[], None]">
  Scrollback replay done
</ParamField>

**Returns:** `ExecSession`

***

## `await sandbox.exec.list()`

List all exec sessions. [HTTP API →](/api-reference/exec/list-sessions)

**Returns:** `list[ExecSessionInfo]`

***

## `await sandbox.exec.kill(session_id, signal=9)`

Kill an exec session. [HTTP API →](/api-reference/exec/kill-session)

**Returns:** `None`

***

## ExecSession

| Member             | Type                  | Description                              |
| ------------------ | --------------------- | ---------------------------------------- |
| `session_id`       | `str`                 | Session ID                               |
| `done`             | `asyncio.Future[int]` | Resolves with exit code                  |
| `send_stdin(data)` | coroutine             | Send input (`str` or `bytes`)            |
| `kill(signal=9)`   | coroutine             | Kill process                             |
| `close()`          | coroutine             | Detach WebSocket (process keeps running) |

***

## Types

<Accordion title="ProcessResult">
  ```python theme={null}
  @dataclass
  class ProcessResult:
      exit_code: int
      stdout: str
      stderr: str
  ```
</Accordion>

<Accordion title="ExecSessionInfo">
  ```python theme={null}
  @dataclass
  class ExecSessionInfo:
      session_id: str
      sandbox_id: str
      command: str
      args: list[str]
      running: bool
      exit_code: int | None
      started_at: str
      attached_clients: int
  ```
</Accordion>


# Filesystem
Source: https://docs.opencomputer.dev/reference/python-sdk/filesystem

Read, write, and manage files

Accessed via `sandbox.files`.

## `await sandbox.files.read(path)`

Read a file as a UTF-8 string. [HTTP API →](/api-reference/files/read)

<ParamField type="str">
  Absolute path to the file
</ParamField>

**Returns:** `str`

***

## `await sandbox.files.read_bytes(path)`

Read a file as raw bytes.

<ParamField type="str">
  Absolute path to the file
</ParamField>

**Returns:** `bytes`

***

## `await sandbox.files.write(path, content)`

Write content to a file. [HTTP API →](/api-reference/files/write)

<ParamField type="str">
  Absolute path for the destination file
</ParamField>

<ParamField type="str | bytes">
  File content
</ParamField>

**Returns:** `None`

***

## `await sandbox.files.list(path="/")`

List directory contents. [HTTP API →](/api-reference/files/list-directory)

<ParamField type="str">
  Directory path
</ParamField>

**Returns:** `list[EntryInfo]`

***

## `await sandbox.files.make_dir(path)`

Create a directory. [HTTP API →](/api-reference/files/mkdir)

<ParamField type="str">
  Directory path
</ParamField>

**Returns:** `None`

***

## `await sandbox.files.remove(path)`

Delete a file or directory. [HTTP API →](/api-reference/files/delete)

<ParamField type="str">
  Path to remove
</ParamField>

**Returns:** `None`

***

## `await sandbox.files.exists(path)`

Check if a path exists. Client-side wrapper — attempts a read and returns `False` on error.

<ParamField type="str">
  Path to check
</ParamField>

**Returns:** `bool`

***

## `await sandbox.files.read_stream(path)`

Stream a file as async byte chunks. Avoids buffering the full file in memory — ideal for large files (50MB+).

<ParamField type="str">
  Absolute path to the file
</ParamField>

**Returns:** `AsyncIterator[bytes]`

***

## `await sandbox.files.write_stream(path, stream)`

Stream content to a file from an async iterator. Avoids buffering the full file in memory.

<ParamField type="str">
  Absolute path for the destination file
</ParamField>

<ParamField type="AsyncIterator[bytes]">
  Async iterator yielding byte chunks
</ParamField>

**Returns:** `None`

***

## Types

<Accordion title="EntryInfo">
  ```python theme={null}
  @dataclass
  class EntryInfo:
      name: str
      is_dir: bool
      path: str
      size: int = 0
  ```
</Accordion>


# Image
Source: https://docs.opencomputer.dev/reference/python-sdk/image

Declarative sandbox image builder

Fluent, immutable builder for declarative sandbox images. Each method returns a new `Image` instance.

## `Image.base()`

Start from the default OpenSandbox environment (Ubuntu 22.04, Python, Node.js, build tools).

```python theme={null}
from opencomputer import Image

image = (
    Image.base()
    .apt_install(["curl", "jq"])
    .pip_install(["requests", "pandas"])
    .env({"PROJECT_ROOT": "/workspace"})
    .workdir("/workspace")
)
```

**Returns:** `Image`

***

## Builder Methods

### `image.apt_install(packages)`

<ParamField type="list[str]">
  System packages to install via apt-get
</ParamField>

**Returns:** `Image`

### `image.pip_install(packages)`

<ParamField type="list[str]">
  Python packages to install via pip
</ParamField>

**Returns:** `Image`

### `image.run_commands(*cmds)`

<ParamField type="str (variadic)">
  Shell commands to run during build
</ParamField>

**Returns:** `Image`

### `image.env(vars)`

<ParamField type="dict[str, str]">
  Environment variables to set
</ParamField>

**Returns:** `Image`

### `image.workdir(path)`

<ParamField type="str">
  Default working directory
</ParamField>

**Returns:** `Image`

### `image.add_file(remote_path, content)`

<ParamField type="str">
  Destination path in the image
</ParamField>

<ParamField type="str">
  File content
</ParamField>

**Returns:** `Image`

### `image.add_local_file(local_path, remote_path)`

<ParamField type="str">
  Path to the local file
</ParamField>

<ParamField type="str">
  Destination path in the image
</ParamField>

**Returns:** `Image`

### `image.add_local_dir(local_path, remote_path)`

<ParamField type="str">
  Path to the local directory
</ParamField>

<ParamField type="str">
  Destination path in the image
</ParamField>

**Returns:** `Image`

### `image.builder_memory(mb)`

Sets the RAM (in MB) used during the build phase. Raise this when a build OOMs
(heavy `apt`/`pip`/`npm`). Defaults to **4096**. Does **not** affect the resulting
sandbox's memory — size that at create time via `memory_mb`.

<ParamField type="int">
  Build-phase memory in MB
</ParamField>

**Returns:** `Image`

***

## Utility Methods

### `image.to_dict()`

Returns the image manifest as a plain dict.

**Returns:** `dict`

### `image.cache_key()`

Computes a deterministic SHA-256 hash of the manifest for cache lookups.

**Returns:** `str`


# Python SDK
Source: https://docs.opencomputer.dev/reference/python-sdk/overview

Complete Python SDK reference

## Installation

```bash theme={null}
pip install opencomputer-sdk
```

```python theme={null}
from opencomputer import Sandbox, Image, Snapshots
```

## Modules

<CardGroup>
  <Card title="Sandbox" icon="box" href="/reference/python-sdk/sandbox">
    Create, connect, and manage sandbox lifecycle
  </Card>

  <Card title="Exec" icon="terminal" href="/reference/python-sdk/exec">
    Run commands and manage exec sessions
  </Card>

  <Card title="Agent" icon="robot" href="/reference/python-sdk/agent">
    Start and manage Claude agent sessions
  </Card>

  <Card title="Filesystem" icon="folder" href="/reference/python-sdk/filesystem">
    Read, write, and manage files
  </Card>

  <Card title="PTY" icon="rectangle-terminal" href="/reference/python-sdk/pty">
    Interactive terminal sessions
  </Card>

  <Card title="Image" icon="layer-group" href="/reference/python-sdk/image">
    Declarative sandbox image builder
  </Card>

  <Card title="Snapshots" icon="camera" href="/reference/python-sdk/snapshots">
    Pre-built sandbox environments
  </Card>

  <Card title="Secret Stores" icon="key" href="/reference/python-sdk/secrets">
    Manage secrets and egress control
  </Card>
</CardGroup>


# PTY
Source: https://docs.opencomputer.dev/reference/python-sdk/pty

Interactive terminal sessions

Accessed via `sandbox.pty`.

## `await sandbox.pty.create(cols=80, rows=24, on_output=None)`

Create an interactive terminal session. [HTTP API →](/api-reference/pty/create)

<ParamField type="int">
  Terminal columns
</ParamField>

<ParamField type="int">
  Terminal rows
</ParamField>

<ParamField type="Callable[[bytes], None]">
  Output callback
</ParamField>

**Returns:** `PtySession`

***

## PtySession

| Member          | Type   | Description                          |
| --------------- | ------ | ------------------------------------ |
| `session_id`    | `str`  | Session ID                           |
| `sandbox_id`    | `str`  | Sandbox ID                           |
| `send(data)`    | method | Send input (str or bytes)            |
| `await recv()`  | method | Receive output bytes (Python-unique) |
| `await close()` | method | Close the PTY                        |

<Note>
  `recv()` is Python-unique — a pull-based alternative to the `on_output` callback. Returns raw `bytes`.
</Note>


# Sandbox
Source: https://docs.opencomputer.dev/reference/python-sdk/sandbox

Create, connect, and manage sandbox lifecycle

## Class Methods

### `await Sandbox.create(...)`

Create a new sandbox. [HTTP API →](/api-reference/sandboxes/create)

<ParamField type="str">
  Template name
</ParamField>

<ParamField type="int">
  Idle timeout in seconds
</ParamField>

<ParamField type="str">
  API key (falls back to `OPENCOMPUTER_API_KEY` env var)
</ParamField>

<ParamField type="str">
  API URL (falls back to `OPENCOMPUTER_API_URL` env var)
</ParamField>

<ParamField type="dict[str, str]">
  Environment variables
</ParamField>

<ParamField type="dict[str, str]">
  Arbitrary metadata
</ParamField>

<ParamField type="bool">
  Create a [Burst Sandbox](/sandboxes/burst-sandboxes). Disk is preserved across infrastructure restarts; processes may restart.
</ParamField>

<ParamField type="Image">
  Declarative image definition (see [Image](/reference/python-sdk/image))
</ParamField>

<ParamField type="str">
  Name of a pre-built snapshot
</ParamField>

<ParamField type="Callable[[str], None]">
  Build log callback (when using `image`)
</ParamField>

**Returns:** `Sandbox`

```python theme={null}
sandbox = await Sandbox.create(template="my-stack", timeout=600)
```

Create a Burst Sandbox:

```python theme={null}
sandbox = await Sandbox.create(
    burst=True,
    timeout=300,
)
```

<Note>
  Burst Sandboxes are alpha. They preserve filesystem state across
  infrastructure restarts, may restart running processes, and are priced roughly
  2x cheaper than on-demand sandboxes.
</Note>

***

### `await Sandbox.connect(sandbox_id, ...)`

Connect to an existing sandbox. [HTTP API →](/api-reference/sandboxes/get)

<ParamField type="str">
  Sandbox ID
</ParamField>

**Returns:** `Sandbox`

```python theme={null}
sandbox = await Sandbox.connect("sb-abc123")
```

***

### `await Sandbox.create_from_checkpoint(checkpoint_id, ...)`

Create a new sandbox from a checkpoint. [HTTP API →](/api-reference/checkpoints/fork)

<ParamField type="str">
  Checkpoint ID
</ParamField>

<ParamField type="int">
  Idle timeout
</ParamField>

**Returns:** `Sandbox`

```python theme={null}
forked = await Sandbox.create_from_checkpoint("cp-abc123")
```

***

### `await Sandbox.create_checkpoint_patch(checkpoint_id, script, ...)`

[HTTP API →](/api-reference/patches/create)

<ParamField type="str">
  Target checkpoint
</ParamField>

<ParamField type="str">
  Bash script
</ParamField>

<ParamField type="str">
  Description
</ParamField>

**Returns:** `dict`

***

### `await Sandbox.list_checkpoint_patches(checkpoint_id, ...)`

[HTTP API →](/api-reference/patches/list) — **Returns:** `list[dict]`

### `await Sandbox.delete_checkpoint_patch(checkpoint_id, patch_id, ...)`

[HTTP API →](/api-reference/patches/delete) — **Returns:** `None`

***

## Context Manager

Auto-kills the sandbox on exit:

```python theme={null}
async with await Sandbox.create() as sandbox:
    result = await sandbox.exec.run("echo hello")
    print(result.stdout)
# sandbox.kill() called automatically
```

***

## Instance Methods

### `await sandbox.kill()`

Terminate the sandbox. [HTTP API →](/api-reference/sandboxes/delete)

**Returns:** `None`

### `await sandbox.is_running()`

Check if the sandbox is running.

**Returns:** `bool`

### `await sandbox.set_timeout(timeout)`

Update idle timeout. [HTTP API →](/api-reference/sandboxes/set-timeout)

<ParamField type="int">
  New timeout in seconds
</ParamField>

**Returns:** `None`

### `await sandbox.create_checkpoint(name, kind=None, retention_policy=None)`

Create a named checkpoint. [HTTP API →](/api-reference/checkpoints/create)

<ParamField type="dict">
  Optional retention policy. Use `{"mode": "delete_oldest", "maxCount": 10}`
  for full checkpoints or `{"mode": "delete_oldest", "maxCount": 100}` with
  `kind="disk_only"` to delete the oldest eligible checkpoint of the same type
  before creating a new one.
</ParamField>

**Returns:** `dict`

### `await sandbox.list_checkpoints()`

[HTTP API →](/api-reference/checkpoints/list) — **Returns:** `list[dict]`

### `await sandbox.restore_checkpoint(checkpoint_id)`

Revert in-place to a checkpoint. [HTTP API →](/api-reference/checkpoints/restore)

**Returns:** `None`

### `await sandbox.delete_checkpoint(checkpoint_id)`

[HTTP API →](/api-reference/checkpoints/delete) — **Returns:** `None`

### `await sandbox.download_url(path, *, expires_in=3600)`

Generate a signed download URL. [HTTP API →](/api-reference/files/generate-download-url) · [Guide →](/sandboxes/signed-urls)

<ParamField type="str">
  Absolute path to the file
</ParamField>

<ParamField type="int">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `str`

### `await sandbox.upload_url(path, *, expires_in=3600)`

Generate a signed upload URL. [HTTP API →](/api-reference/files/generate-upload-url) · [Guide →](/sandboxes/signed-urls)

<ParamField type="str">
  Absolute path for the destination file
</ParamField>

<ParamField type="int">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `str`

### `await sandbox.create_preview_url(port, domain?, auth_config?)`

[HTTP API →](/api-reference/preview/create)

<ParamField type="int">
  Container port (1–65535)
</ParamField>

<ParamField type="str">
  Custom domain
</ParamField>

<ParamField type="dict">
  Auth configuration
</ParamField>

**Returns:** `dict`

### `await sandbox.list_preview_urls()`

[HTTP API →](/api-reference/preview/list) — **Returns:** `list[dict]`

### `await sandbox.delete_preview_url(port)`

[HTTP API →](/api-reference/preview/delete) — **Returns:** `None`

### `await sandbox.get_allowed_hosts()`

Return the egress allowlist + per-secret allowed hosts the sandbox's secrets proxy enforces. Useful for debugging "why is my outbound HTTP call being blocked" without having to cross-reference the [secret store](/sandboxes/secrets) config separately.

Sandboxes created without a `secret_store` option return an empty allowlist with `secretStore` omitted — the sandbox has no per-store egress restriction.

**Returns:** `dict` with the shape:

```python theme={null}
{
    "sandboxID": "sb-...",
    "secretStore": "my-store",                   # omitted if no store
    "baseSecretStore": "parent-store",           # omitted unless this is a layered fork
    "egressAllowlist": ["api.openai.com", ...],
    "perSecretAllowedHosts": {
        "OPENAI_API_KEY": ["api.openai.com"],
    },
}
```

For forks that layered an additional `secret_store` on top of an inherited one, `egressAllowlist` is the **union** of both stores' allowlists (matches what the runtime proxy enforces) and `baseSecretStore` is populated with the inherited parent's name. For sandboxes with a single store (or none), `baseSecretStore` is omitted.

```python theme={null}
info = await sandbox.get_allowed_hosts()
print(info["egressAllowlist"])          # ['api.openai.com', 'api.anthropic.com']
print(info["perSecretAllowedHosts"])    # {'OPENAI_API_KEY': ['api.openai.com']}
```

### `await sandbox.close()`

Close HTTP clients. Called automatically by the context manager.

***

## Not Available in Python

These features are TypeScript-only. Use the [HTTP API](/api-reference/overview) directly:

* `hibernate()` / `wake()`
* `cpuCount` / `memoryMB` on create

***

## Properties

<ParamField type="str">
  Sandbox ID
</ParamField>

<ParamField type="str">
  Current status
</ParamField>

<ParamField type="Agent">
  [Agent sessions](/reference/python-sdk/agent)
</ParamField>

<ParamField type="Exec">
  [Command execution](/reference/python-sdk/exec)
</ParamField>

<ParamField type="Filesystem">
  [File operations](/reference/python-sdk/filesystem)
</ParamField>

<ParamField type="Pty">
  [Terminal sessions](/reference/python-sdk/pty)
</ParamField>

<ParamField type="Exec">
  **Deprecated** — alias for `exec`
</ParamField>


# Scaling
Source: https://docs.opencomputer.dev/reference/python-sdk/scaling

Resize a sandbox manually, autoscale on memory pressure, or freeze its resources.

OpenComputer sandboxes can change size at runtime. There are three knobs:

| What you want                       | Use                                                      |
| ----------------------------------- | -------------------------------------------------------- |
| Resize once, predictably            | [`scale()`](#sandbox-scale-memory-mb)                    |
| Track memory pressure automatically | [`set_autoscale()`](#sandbox-set-autoscale)              |
| Freeze the current size             | [`set_scaling_lock()`](#sandbox-set-scaling-lock-locked) |

CPU follows memory per the platform's tier table. You don't pick CPU separately.

## How the three interact

* **Manual `scale()`** disables autoscale on the sandbox as a side effect — explicit user intent overrides the loop. Re-enable with `set_autoscale(enabled=True, ...)` after if you want.
* **Setting a scaling lock** disables autoscale at the same time (single knob: "I don't want this scaling, period"). While locked, both `scale()` and `set_autoscale(enabled=True)` raise `ScalingLockedError`. Unlocking does NOT auto-re-enable autoscale.
* **Plan caps** apply everywhere. Free-tier orgs are capped at 4 GB. Calls above the cap raise `PlanLimitError`.

***

## `sandbox.scale(memory_mb)`

Manually resize the sandbox. [HTTP API →](/api-reference/sandboxes/scale)

<ParamField type="int">
  Target memory in MB.
</ParamField>

**Returns:** `dict` with `sandboxID`, `memoryMB`, `cpuPercent`.

**Raises:**

* `ScalingLockedError` — sandbox has a scaling lock active.
* `PlanLimitError` — `memory_mb` exceeds the org's plan cap.

```python theme={null}
from opencomputer import Sandbox, ScalingLockedError, PlanLimitError

sandbox = await Sandbox.connect("sb-abc123")

try:
    result = await sandbox.scale(memory_mb=8192)
    print(f"scaled to {result['memoryMB']}MB / {result['cpuPercent']}% CPU")
except ScalingLockedError:
    print("sandbox is locked — unlock to scale")
except PlanLimitError:
    print("upgrade required for larger instances")
```

***

## `sandbox.set_autoscale(enabled, *, min_memory_mb=None, max_memory_mb=None)`

Enable or disable per-sandbox autoscale.

<ParamField type="bool">
  Whether autoscale should be active.
</ParamField>

<ParamField type="int">
  Lower bound when `enabled=True`.
</ParamField>

<ParamField type="int">
  Upper bound when `enabled=True`. Must be ≥ `min_memory_mb`.
</ParamField>

**Returns:** `dict` with `sandboxID`, `enabled`, `minMemoryMB`, `maxMemoryMB`.

**Raises:**

* `ScalingLockedError` — sandbox has a scaling lock active.
* `PlanLimitError` — `max_memory_mb` exceeds the org's plan cap.

When `enabled=True`, the platform watches the sandbox's memory pressure and resizes it within the bounds:

* **Scale up** on a single 1-min sample above 75% memory utilization. Cooldown 60s between up-scales.
* **Scale down** only when 1-min, 5-min, AND 15-min averages all sit below 25%. Cooldown 5 min between down-scales.

The asymmetry matches user perception: rapid response when the user notices lag, conservative shrink after sustained idle. The 15-min window is the dominant constraint on shrink, so a sandbox that briefly idles and resumes won't sawtooth.

```python theme={null}
await sandbox.set_autoscale(
    enabled=True,
    min_memory_mb=1024,
    max_memory_mb=16384,
)
```

To turn off:

```python theme={null}
await sandbox.set_autoscale(enabled=False)
```

***

## `sandbox.get_autoscale()`

Get the current autoscale configuration.

**Returns:** `dict` with `sandboxID`, `enabled`, `minMemoryMB`, `maxMemoryMB`.

```python theme={null}
cfg = await sandbox.get_autoscale()
if cfg["enabled"]:
    print(f"autoscale {cfg['minMemoryMB']}–{cfg['maxMemoryMB']} MB")
```

***

## `sandbox.set_scaling_lock(locked)`

Lock or unlock the sandbox's resources against any size change.

<ParamField type="bool">
  `True` to freeze, `False` to allow scaling again.
</ParamField>

**Returns:** `dict` with `sandboxID`, `locked`.

While locked:

* `scale()` raises `ScalingLockedError`.
* `set_autoscale(enabled=True)` raises `ScalingLockedError`.
* The platform autoscaler skips this sandbox entirely.

Locking ALSO disables autoscale (single knob — "I don't want this scaling"). Unlocking does **not** re-enable autoscale; call `set_autoscale(enabled=True, ...)` explicitly if you want it back.

```python theme={null}
# Pin a sandbox at its current size during a critical workload
await sandbox.set_scaling_lock(True)

# ...

# Allow scaling again after
await sandbox.set_scaling_lock(False)
```

***

## `sandbox.get_scaling_lock()`

Get the current scaling-lock state.

**Returns:** `dict` with `sandboxID`, `locked`.

***

## Errors

### `ScalingLockedError`

Raised when the sandbox has a scaling lock active. Has a class attribute `code = "scaling_locked"` for parity with the HTTP API's error code.

```python theme={null}
from opencomputer import ScalingLockedError

try:
    await sandbox.scale(memory_mb=8192)
except ScalingLockedError:
    # unlock first, or surface to user
    ...
```

### `PlanLimitError`

Raised when the requested size exceeds the org's plan cap. The HTTP API returns 402 Payment Required for this case.


# Secret Stores
Source: https://docs.opencomputer.dev/reference/python-sdk/secrets

Manage secrets and egress control

## `await SecretStore.create(**kwargs)`

Create a new secret store.

```python theme={null}
from opencomputer import SecretStore

store = await SecretStore.create(
    name='my-agent-secrets',
    egress_allowlist=['api.anthropic.com'],
)
```

<ParamField type="str">
  Store name (unique per organization)
</ParamField>

<ParamField type="list[str] | None">
  Allowed egress hosts
</ParamField>

**Returns:** `dict`

***

## `await SecretStore.list(**kwargs)`

**Returns:** `list[dict]`

## `await SecretStore.get(store_id, **kwargs)`

<ParamField type="str">
  UUID of the secret store
</ParamField>

**Returns:** `dict`

***

## `await SecretStore.update(store_id, **kwargs)`

Partial updates — only the fields you pass are changed.

```python theme={null}
updated = await SecretStore.update(
    'store-uuid',
    name='new-name',
    egress_allowlist=['api.anthropic.com', '*.openai.com'],
)
```

<ParamField type="str">
  UUID of the store to update
</ParamField>

<ParamField type="str">
  New store name
</ParamField>

<ParamField type="list[str] | None">
  New allowed egress hosts
</ParamField>

**Returns:** `dict`

***

## `await SecretStore.delete(store_id, **kwargs)`

Deletes the store and all its secrets. Running sandboxes are not affected.

**Returns:** `None`

***

## `await SecretStore.set_secret(store_id, name, value, **kwargs)`

Set a secret. Encrypted at rest, never returned by API.

```python theme={null}
await SecretStore.set_secret('store-uuid', 'ANTHROPIC_API_KEY', 'sk-ant-...')

# Optionally restrict to specific hosts:
await SecretStore.set_secret(
    'store-uuid', 'ANTHROPIC_API_KEY', 'sk-ant-...',
    allowed_hosts=['api.anthropic.com'],
)
```

<ParamField type="str">
  UUID of the secret store
</ParamField>

<ParamField type="str">
  Secret name (env var name in sandboxes)
</ParamField>

<ParamField type="str">
  Secret value
</ParamField>

<ParamField type="list[str] | None">
  Restrict to specific hosts
</ParamField>

**Returns:** `None`

***

## `await SecretStore.list_secrets(store_id, **kwargs)`

Returns metadata only. Values are never exposed.

**Returns:** `list[dict]`

## `await SecretStore.delete_secret(store_id, name, **kwargs)`

**Returns:** `None`

***

## Using Secrets with Sandboxes

```python theme={null}
sandbox = await Sandbox.create(
    secret_store='my-agent-secrets',
    timeout=600,
)

# Secrets are available as sealed env vars
result = await sandbox.commands.run('echo $ANTHROPIC_API_KEY')
# stdout: "osb_sealed_abc123..." (sealed, not the real key)

# Outbound HTTPS requests get the real value substituted by the proxy
api_result = await sandbox.commands.run(
    'curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" ...'
)
```

## Using Secrets with Snapshots and Checkpoints

### Snapshot template with secrets

Attach a secret store when creating a sandbox from a pre-built snapshot — even if the snapshot was built without one:

```python theme={null}
from opencomputer import Sandbox, Snapshots, Image

# Pre-build a snapshot with dependencies
snapshots = Snapshots()
await snapshots.create(
    name='data-pipeline',
    image=Image.base().apt_install(['python3-pip']).pip_install(['pandas']),
)

# Create sandboxes from the snapshot, each with their own credentials
worker1 = await Sandbox.create(
    snapshot='data-pipeline',
    secret_store='worker-1-keys',
)
worker2 = await Sandbox.create(
    snapshot='data-pipeline',
    secret_store='worker-2-keys',
)
```

### Checkpoint fork with secrets

Attach or layer a secret store when forking from a checkpoint:

```python theme={null}
# Bake a base environment with git credentials
base = await Sandbox.create(secret_store='git-creds')
await base.exec.run('git clone https://github.com/org/repo /app')
cp = await base.create_checkpoint('repo-cloned')

# Fork with different credentials per sandbox (layered on top of git-creds)
worker = await Sandbox.create_from_checkpoint(
    cp['id'],
    secret_store='worker-keys',  # layered on top of git-creds
)
```

When layered, secrets merge (fork's store wins on collision) and egress allowlists aggregate.


# Snapshots
Source: https://docs.opencomputer.dev/reference/python-sdk/snapshots

Pre-built sandbox environments

Standalone class — not a property on Sandbox.

## Constructor

```python theme={null}
from opencomputer import Snapshots

snapshots = Snapshots()
# or with explicit config:
snapshots = Snapshots(api_key="...", api_url="...")
```

<ParamField type="str">
  API key (falls back to `OPENCOMPUTER_API_KEY` env var)
</ParamField>

<ParamField type="str">
  API URL (falls back to `OPENCOMPUTER_API_URL` env var)
</ParamField>

***

## `await snapshots.create(name, image, on_build_logs=None)`

Create a pre-built snapshot. [HTTP API →](/api-reference/snapshots/create)

<ParamField type="str">
  Unique snapshot name
</ParamField>

<ParamField type="Image">
  Declarative image definition
</ParamField>

<ParamField type="Callable[[str], None]">
  Build log streaming callback
</ParamField>

**Returns:** `dict`

***

## `await snapshots.list()`

[HTTP API →](/api-reference/snapshots/list) — **Returns:** `list[dict]`

## `await snapshots.get(name)`

[HTTP API →](/api-reference/snapshots/get)

<ParamField type="str">
  Snapshot name
</ParamField>

**Returns:** `dict`

## `await snapshots.delete(name)`

Delete a snapshot. Existing sandboxes are not affected. [HTTP API →](/api-reference/snapshots/delete)

**Returns:** `None`

***

## SnapshotInfo

Snapshot methods return dicts with these fields:

<Accordion title="SnapshotInfo fields">
  ```python theme={null}
  {
      "id": str,           # Unique snapshot identifier
      "name": str,         # Snapshot name
      "status": str,       # "building" | "ready" | "failed"
      "contentHash": str,  # SHA-256 hash of the image manifest
      "checkpointId": str, # Linked checkpoint ID
      "manifest": dict,    # The declarative image manifest
      "createdAt": str,    # ISO 8601 creation timestamp
      "lastUsedAt": str,   # ISO 8601 last usage timestamp
  }
  ```
</Accordion>


# Exec
Source: https://docs.opencomputer.dev/reference/typescript-sdk/exec

Run commands and manage exec sessions

Accessed via `sandbox.exec`.

## `sandbox.exec.run(command, opts?)`

Run a command synchronously. [HTTP API →](/api-reference/exec/run)

<ParamField type="string">
  Shell command
</ParamField>

<ParamField type="number">
  Timeout in seconds
</ParamField>

<ParamField type="Record<string, string>">
  Environment variables
</ParamField>

<ParamField type="string">
  Working directory
</ParamField>

**Returns:** `Promise<ProcessResult>`

```typescript theme={null}
const result = await sandbox.exec.run("npm test", { cwd: "/app" });
```

***

## `sandbox.exec.start(command, opts?)`

Start a long-running command with streaming. [HTTP API →](/api-reference/exec/create-session)

<ParamField type="string">
  Command
</ParamField>

<ParamField type="string[]">
  Arguments
</ParamField>

<ParamField type="Record<string, string>">
  Environment variables
</ParamField>

<ParamField type="string">
  Working directory
</ParamField>

<ParamField type="number">
  Timeout in seconds
</ParamField>

<ParamField type="number">
  Seconds to keep running after disconnect
</ParamField>

<ParamField type="(data: Uint8Array) => void">
  Stdout callback
</ParamField>

<ParamField type="(data: Uint8Array) => void">
  Stderr callback
</ParamField>

<ParamField type="(exitCode: number) => void">
  Exit callback
</ParamField>

**Returns:** `Promise<ExecSession>`

```typescript theme={null}
const session = await sandbox.exec.start("node server.js", {
  onStdout: (data) => process.stdout.write(data),
});
```

***

## `sandbox.exec.background(command, opts?)`

Alias for [`start`](#sandbox-exec-start-command-opts). Same options, same return type. Use when the intent is "run this in the background and observe it" — more discoverable than `start` for that case.

```typescript theme={null}
const server = await sandbox.exec.background("npm", {
  args: ["run", "dev"],
  onStdout: (data) => process.stdout.write(data),
});
```

***

## `sandbox.exec.shell(opts?)`

Open a stateful shell session. Subsequent `.run()` calls share the same bash process, so `cwd`, exported env vars, and shell functions persist — the ergonomics of a terminal tab.

Backed by a long-running `bash --noprofile --norc` session. Foreground-only: concurrent `.run()` rejects with `ShellBusyError`. Use [`background`](#sandbox-exec-background-command-opts) for fire-and-forget processes.

<ParamField type="string">
  Initial working directory
</ParamField>

<ParamField type="Record<string, string>">
  Initial environment variables
</ParamField>

**Returns:** `Promise<Shell>`

```typescript theme={null}
const sh = await sandbox.exec.shell({ cwd: "/app" });

await sh.run("npm install");
await sh.run("export NODE_ENV=test");
const r = await sh.run("npm test", {
  onStdout: (b) => process.stdout.write(b),
});
console.log(r.exitCode);

await sh.close();
```

### Shell

| Member            | Type                     | Description                                 |
| ----------------- | ------------------------ | ------------------------------------------- |
| `sessionId`       | `string`                 | Underlying exec session ID                  |
| `run(cmd, opts?)` | `Promise<ProcessResult>` | Run a command, blocking until it exits      |
| `close()`         | `Promise<void>`          | Write `exit` and wait for bash to terminate |

### ShellRunOpts

| Parameter  | Type                         | Description              |
| ---------- | ---------------------------- | ------------------------ |
| `onStdout` | `(data: Uint8Array) => void` | Per-call stdout callback |
| `onStderr` | `(data: Uint8Array) => void` | Per-call stderr callback |

<Note>
  Per-call `cwd`, `env`, and `timeout` are intentionally not supported in v1. Use inline shell syntax (`cd /x && cmd`, `FOO=bar cmd`) — the shell state carries across calls. Timeouts will land once we have a "signal foreground job" primitive.
</Note>

Errors:

* `ShellBusyError` — another `run()` is in flight (shell is foreground-only).
* `ShellClosedError` — bash has exited (explicit `close()`, a command ran `exit`, or the session dropped).

***

## `sandbox.exec.attach(sessionId, opts?)`

Reconnect to a running exec session.

<ParamField type="string">
  Session ID
</ParamField>

<ParamField type="(data: Uint8Array) => void">
  Stdout callback
</ParamField>

<ParamField type="(data: Uint8Array) => void">
  Stderr callback
</ParamField>

<ParamField type="(exitCode: number) => void">
  Exit callback
</ParamField>

<ParamField type="() => void">
  Scrollback replay done
</ParamField>

**Returns:** `Promise<ExecSession>`

***

## `sandbox.exec.list()`

List all exec sessions. [HTTP API →](/api-reference/exec/list-sessions)

**Returns:** `Promise<ExecSessionInfo[]>`

***

## `sandbox.exec.kill(sessionId, signal?)`

Kill an exec session. Default signal: `9` (SIGKILL). [HTTP API →](/api-reference/exec/kill-session)

**Returns:** `Promise<void>`

***

## ExecSession

| Member            | Type              | Description                       |
| ----------------- | ----------------- | --------------------------------- |
| `sessionId`       | `string`          | Session ID                        |
| `done`            | `Promise<number>` | Resolves with exit code           |
| `sendStdin(data)` | method            | Send input (string or Uint8Array) |
| `kill(signal?)`   | `Promise<void>`   | Kill process                      |
| `close()`         | method            | Close WebSocket                   |

***

## Types

<Accordion title="ProcessResult">
  ```typescript theme={null}
  interface ProcessResult {
    exitCode: number;
    stdout: string;
    stderr: string;
  }
  ```
</Accordion>

<Accordion title="ExecSessionInfo">
  ```typescript theme={null}
  interface ExecSessionInfo {
    sessionID: string;
    sandboxID: string;
    command: string;
    args: string[];
    running: boolean;
    exitCode?: number;
    startedAt: string;
    attachedClients: number;
  }
  ```
</Accordion>


# Filesystem
Source: https://docs.opencomputer.dev/reference/typescript-sdk/filesystem

Read, write, and manage files

Accessed via `sandbox.files`.

## `sandbox.files.read(path)`

Read a file as a UTF-8 string. [HTTP API →](/api-reference/files/read)

<ParamField type="string">
  Absolute path to the file
</ParamField>

**Returns:** `Promise<string>`

***

## `sandbox.files.readBytes(path)`

Read a file as raw bytes.

<ParamField type="string">
  Absolute path to the file
</ParamField>

**Returns:** `Promise<Uint8Array>`

***

## `sandbox.files.write(path, content)`

Write content to a file. [HTTP API →](/api-reference/files/write)

<ParamField type="string">
  Absolute path for the destination file
</ParamField>

<ParamField type="string | Uint8Array">
  File content
</ParamField>

**Returns:** `Promise<void>`

***

## `sandbox.files.list(path?)`

List directory contents. [HTTP API →](/api-reference/files/list-directory)

<ParamField type="string">
  Directory path
</ParamField>

**Returns:** `Promise<EntryInfo[]>`

***

## `sandbox.files.makeDir(path)`

Create a directory (recursive). [HTTP API →](/api-reference/files/mkdir)

<ParamField type="string">
  Directory path
</ParamField>

**Returns:** `Promise<void>`

***

## `sandbox.files.remove(path)`

Delete a file or directory. [HTTP API →](/api-reference/files/delete)

<ParamField type="string">
  Path to remove
</ParamField>

**Returns:** `Promise<void>`

***

## `sandbox.files.readStream(path)`

Stream a file as a `ReadableStream`. Avoids buffering the entire file in memory — ideal for large files (50MB+).

<ParamField type="string">
  Absolute path to the file
</ParamField>

**Returns:** `Promise<ReadableStream<Uint8Array>>`

***

## `sandbox.files.writeStream(path, stream)`

Stream content to a file. Accepts a `ReadableStream` or `Uint8Array` without buffering an extra copy in memory.

<ParamField type="string">
  Absolute path for the destination file
</ParamField>

<ParamField type="ReadableStream<Uint8Array> | Uint8Array">
  File content as a stream or byte array
</ParamField>

**Returns:** `Promise<void>`

***

## `sandbox.files.exists(path)`

Check if a path exists. Client-side wrapper — attempts a read and returns `false` on error.

<ParamField type="string">
  Path to check
</ParamField>

**Returns:** `Promise<boolean>`

***

## Types

<Accordion title="EntryInfo">
  ```typescript theme={null}
  interface EntryInfo {
    name: string;
    isDir: boolean;
    path: string;
    size: number;
  }
  ```
</Accordion>


# Image
Source: https://docs.opencomputer.dev/reference/typescript-sdk/image

Declarative sandbox image builder

Fluent, immutable builder for declarative sandbox images. Each method returns a new `Image` instance.

## `Image.base()`

Start from the default OpenSandbox environment (Ubuntu 22.04, Python, Node.js, build tools).

```typescript theme={null}
import { Image } from "@opencomputer/sdk";

const image = Image.base()
  .aptInstall(['curl', 'jq'])
  .pipInstall(['requests', 'pandas'])
  .env({ PROJECT_ROOT: '/workspace' })
  .workdir('/workspace');
```

**Returns:** `Image`

***

## Builder Methods

### `image.aptInstall(packages)`

<ParamField type="string[]">
  System packages to install via apt-get
</ParamField>

**Returns:** `Image`

***

### `image.pipInstall(packages)`

<ParamField type="string[]">
  Python packages to install via pip
</ParamField>

**Returns:** `Image`

***

### `image.runCommands(...cmds)`

<ParamField type="string[]">
  Shell commands to run during build
</ParamField>

**Returns:** `Image`

***

### `image.env(vars)`

<ParamField type="Record<string, string>">
  Environment variables to set
</ParamField>

**Returns:** `Image`

***

### `image.workdir(path)`

<ParamField type="string">
  Default working directory
</ParamField>

**Returns:** `Image`

***

### `image.addFile(remotePath, content)`

<ParamField type="string">
  Destination path in the image
</ParamField>

<ParamField type="string">
  File content
</ParamField>

**Returns:** `Image`

***

### `image.addLocalFile(localPath, remotePath)`

<ParamField type="string">
  Path to the local file
</ParamField>

<ParamField type="string">
  Destination path in the image
</ParamField>

**Returns:** `Image`

***

### `image.addLocalDir(localPath, remotePath)`

<ParamField type="string">
  Path to the local directory
</ParamField>

<ParamField type="string">
  Destination path in the image
</ParamField>

**Returns:** `Image`

### `image.builderMemory(mb)`

Sets the RAM (MB) used during the build phase. Raise this when a build OOMs
(heavy `apt`/`pip`/`npm`). Defaults to **4096**. Does **not** affect the resulting
sandbox's memory — size that at create time via `memoryMB`.

<ParamField type="number">
  Build-phase memory in MB
</ParamField>

**Returns:** `Image`

***

## Utility Methods

### `image.toJSON()`

Returns the image manifest as a plain object.

**Returns:** `ImageManifest`

### `image.cacheKey()`

Computes a deterministic SHA-256 hash of the manifest for cache lookups.

**Returns:** `string`


# TypeScript SDK
Source: https://docs.opencomputer.dev/reference/typescript-sdk/overview

Complete TypeScript SDK reference

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @opencomputer/sdk
  ```

  ```bash yarn theme={null}
  yarn add @opencomputer/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @opencomputer/sdk
  ```
</CodeGroup>

```typescript theme={null}
import { Sandbox } from "@opencomputer/sdk";
import { Image, Snapshots } from "@opencomputer/sdk/node";
```

> Note: The SDK is ESM-only. Use Node 18+ with `"type": "module"` (or `.mjs/.mts`) and top-level `await`, or use `const { Sandbox } = await import("@opencomputer/sdk"); const { Image, Snapshots } = await import("@opencomputer/sdk/node");` in CommonJS.

## Modules

<CardGroup>
  <Card title="Sandbox" icon="box" href="/reference/typescript-sdk/sandbox">
    Create, connect, and manage sandbox lifecycle
  </Card>

  <Card title="Usage & Tags" icon="gauge" href="/reference/typescript-sdk/usage">
    Query usage, group by tag, and manage sandbox tags
  </Card>

  <Card title="Exec" icon="terminal" href="/reference/typescript-sdk/exec">
    Run commands and manage exec sessions
  </Card>

  <Card title="Sandbox agent" icon="robot" href="/reference/typescript-sdk/agent">
    Start and manage an agent session inside a sandbox (low-level; deprecated)
  </Card>

  <Card title="Filesystem" icon="folder" href="/reference/typescript-sdk/filesystem">
    Read, write, and manage files
  </Card>

  <Card title="PTY" icon="rectangle-terminal" href="/reference/typescript-sdk/pty">
    Interactive terminal sessions
  </Card>

  <Card title="Image" icon="layer-group" href="/reference/typescript-sdk/image">
    Declarative sandbox image builder
  </Card>

  <Card title="Snapshots" icon="camera" href="/reference/typescript-sdk/snapshots">
    Pre-built sandbox environments
  </Card>

  <Card title="Secret Stores" icon="key" href="/reference/typescript-sdk/secrets">
    Manage secrets and egress control
  </Card>
</CardGroup>


# PTY
Source: https://docs.opencomputer.dev/reference/typescript-sdk/pty

Interactive terminal sessions

Accessed via `sandbox.pty`.

## `sandbox.pty.create(opts?)`

Create an interactive terminal session. [HTTP API →](/api-reference/pty/create)

<ParamField type="number">
  Terminal columns
</ParamField>

<ParamField type="number">
  Terminal rows
</ParamField>

<ParamField type="(data: Uint8Array) => void">
  Output callback
</ParamField>

**Returns:** `Promise<PtySession>`

***

## PtySession

| Member       | Type     | Description                       |
| ------------ | -------- | --------------------------------- |
| `sessionId`  | `string` | Session ID                        |
| `send(data)` | method   | Send input (string or Uint8Array) |
| `close()`    | method   | Close the PTY                     |


# Sandbox
Source: https://docs.opencomputer.dev/reference/typescript-sdk/sandbox

Create, connect, and manage sandbox lifecycle

## Static Methods

### `Sandbox.create(opts?)`

Create a new sandbox. [HTTP API →](/api-reference/sandboxes/create)

<ParamField type="string">
  Template name
</ParamField>

<ParamField type="number">
  Idle timeout in seconds
</ParamField>

<ParamField type="string">
  API key (falls back to `OPENCOMPUTER_API_KEY` env var)
</ParamField>

<ParamField type="string">
  API URL (falls back to `OPENCOMPUTER_API_URL` env var)
</ParamField>

<ParamField type="Record<string, string>">
  Environment variables
</ParamField>

<ParamField type="Record<string, string>">
  Arbitrary metadata
</ParamField>

<ParamField type="boolean">
  Create a [Burst Sandbox](/sandboxes/burst-sandboxes). Disk is preserved across infrastructure restarts; processes may restart.
</ParamField>

<ParamField type="number">
  CPU cores
</ParamField>

<ParamField type="number">
  Memory in MB
</ParamField>

<ParamField type="string">
  Secret store name — resolves encrypted secrets and egress allowlist
</ParamField>

<ParamField type="Image">
  Declarative image definition (see [Image](/reference/typescript-sdk/image))
</ParamField>

<ParamField type="string">
  Name of a pre-built snapshot
</ParamField>

<ParamField type="(log: string) => void">
  Build log callback (when using `image`)
</ParamField>

**Returns:** `Promise<Sandbox>`

```typescript theme={null}
const sandbox = await Sandbox.create({ template: "my-stack", timeout: 600 });
```

Create a Burst Sandbox:

```typescript theme={null}
const sandbox = await Sandbox.create({
  burst: true,
  timeout: 300,
});
```

<Note>
  Burst Sandboxes are alpha. They preserve filesystem state across
  infrastructure restarts, may restart running processes, and are priced roughly
  2x cheaper than on-demand sandboxes.
</Note>

***

### `Sandbox.connect(sandboxId, opts?)`

Connect to an existing sandbox. [HTTP API →](/api-reference/sandboxes/get)

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  API key
</ParamField>

<ParamField type="string">
  API URL
</ParamField>

**Returns:** `Promise<Sandbox>`

```typescript theme={null}
const sandbox = await Sandbox.connect("sb-abc123");
```

***

### `Sandbox.createFromCheckpoint(checkpointId, opts?)`

Create a new sandbox from a checkpoint. [HTTP API →](/api-reference/checkpoints/fork)

<ParamField type="string">
  Checkpoint ID
</ParamField>

<ParamField type="number">
  Idle timeout
</ParamField>

**Returns:** `Promise<Sandbox>`

```typescript theme={null}
const forked = await Sandbox.createFromCheckpoint("cp-abc123");
```

***

### `Sandbox.createCheckpointPatch(checkpointId, opts)`

Create a patch for a checkpoint. [HTTP API →](/api-reference/patches/create)

<ParamField type="string">
  Target checkpoint
</ParamField>

<ParamField type="string">
  Bash script
</ParamField>

<ParamField type="string">
  Description
</ParamField>

**Returns:** `Promise<PatchResult>`

```typescript theme={null}
const result = await Sandbox.createCheckpointPatch("cp-abc", { script: "apt install -y curl" });
```

***

### `Sandbox.listCheckpointPatches(checkpointId, opts?)`

[HTTP API →](/api-reference/patches/list)

**Returns:** `Promise<PatchInfo[]>`

***

### `Sandbox.deleteCheckpointPatch(checkpointId, patchId, opts?)`

[HTTP API →](/api-reference/patches/delete)

**Returns:** `Promise<void>`

***

## Instance Methods

### `sandbox.kill()`

Terminate the sandbox. [HTTP API →](/api-reference/sandboxes/delete)

**Returns:** `Promise<void>`

### `sandbox.isRunning()`

Check if the sandbox is running.

**Returns:** `Promise<boolean>`

### `sandbox.hibernate()`

Snapshot VM state and stop. No compute cost while hibernated. [HTTP API →](/api-reference/sandboxes/hibernate)

**Returns:** `Promise<void>`

### `sandbox.wake(opts?)`

Resume a hibernated sandbox. [HTTP API →](/api-reference/sandboxes/wake)

<ParamField type="number">
  Idle timeout after wake
</ParamField>

**Returns:** `Promise<void>`

### `sandbox.setTimeout(timeout)`

Update the idle timeout. [HTTP API →](/api-reference/sandboxes/set-timeout)

<ParamField type="number">
  New timeout in seconds
</ParamField>

**Returns:** `Promise<void>`

### `sandbox.createCheckpoint(name, opts?)`

Create a named checkpoint. [HTTP API →](/api-reference/checkpoints/create)

<ParamField type="string">
  Checkpoint name (unique per sandbox)
</ParamField>

<ParamField type="object">
  Optional retention policy. Use `{ mode: "delete_oldest", maxCount: 10 }` for
  full checkpoints or `{ mode: "delete_oldest", maxCount: 100 }` with
  `kind: "disk_only"` to delete the oldest eligible checkpoint of the same type
  before creating a new one.
</ParamField>

**Returns:** `Promise<CheckpointInfo>`

### `sandbox.listCheckpoints()`

[HTTP API →](/api-reference/checkpoints/list) — **Returns:** `Promise<CheckpointInfo[]>`

### `sandbox.restoreCheckpoint(checkpointId)`

Revert in-place to a checkpoint. [HTTP API →](/api-reference/checkpoints/restore)

**Returns:** `Promise<void>`

### `sandbox.deleteCheckpoint(checkpointId)`

[HTTP API →](/api-reference/checkpoints/delete) — **Returns:** `Promise<void>`

### `sandbox.getPreviewDomain(port)`

Get the preview URL domain for a specific port. No API call — constructs the hostname locally.

<ParamField type="number">
  Port number
</ParamField>

**Returns:** `string` (e.g., `sb-abc123-p3000.workers.opencomputer.dev`)

```typescript theme={null}
const domain = sandbox.getPreviewDomain(3000);
console.log(`https://${domain}`);
```

***

### `sandbox.downloadUrl(path, opts?)`

Generate a signed download URL. [HTTP API →](/api-reference/files/generate-download-url) · [Guide →](/sandboxes/signed-urls)

<ParamField type="string">
  Absolute path to the file
</ParamField>

<ParamField type="number">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `Promise<string>`

### `sandbox.uploadUrl(path, opts?)`

Generate a signed upload URL. [HTTP API →](/api-reference/files/generate-upload-url) · [Guide →](/sandboxes/signed-urls)

<ParamField type="string">
  Absolute path for the destination file
</ParamField>

<ParamField type="number">
  URL lifetime in seconds (max: 86400)
</ParamField>

**Returns:** `Promise<string>`

### `sandbox.createPreviewURL(opts)`

[HTTP API →](/api-reference/preview/create)

<ParamField type="number">
  Container port (1–65535)
</ParamField>

<ParamField type="string">
  Custom domain
</ParamField>

<ParamField type="Record<string, unknown>">
  Auth configuration
</ParamField>

**Returns:** `Promise<PreviewURLResult>`

### `sandbox.listPreviewURLs()`

[HTTP API →](/api-reference/preview/list) — **Returns:** `Promise<PreviewURLResult[]>`

### `sandbox.deletePreviewURL(port)`

[HTTP API →](/api-reference/preview/delete) — **Returns:** `Promise<void>`

***

### `sandbox.getAllowedHosts()`

Return the egress allowlist + per-secret allowed hosts the sandbox's secrets proxy enforces. Useful for debugging "why is my outbound HTTP call being blocked" without having to cross-reference the [secret store](/sandboxes/secrets) config separately.

Sandboxes created without a `secretStore` option return an empty allowlist with `secretStore` undefined — the sandbox has no per-store egress restriction.

**Returns:** `Promise<AllowedHostsInfo>`

```typescript theme={null}
const info = await sandbox.getAllowedHosts();
console.log(info.egressAllowlist);          // ['api.openai.com', 'api.anthropic.com']
console.log(info.perSecretAllowedHosts);    // { 'OPENAI_API_KEY': ['api.openai.com'] }
```

The returned `AllowedHostsInfo`:

<ParamField type="string">
  Sandbox ID
</ParamField>

<ParamField type="string">
  Name of the primary secret store the sandbox is bound to (the "winning" store on the row, whose secrets shadow the base store on env-name collisions). Empty when the sandbox was created without a `secretStore` option.
</ParamField>

<ParamField type="string">
  Name of the inherited parent store, present only when a fork layered an additional `secretStore` on top of an inherited one. Empty for sandboxes created from scratch and for forks without an override.
</ParamField>

<ParamField type="string[]">
  Hosts the sandbox can reach via the secrets proxy. For layered forks this is the **union** of every layered store's allowlist (base first, primary's additions appended, deduped) — matches what the runtime proxy actually enforces.
</ParamField>

<ParamField type="Record<string, string[]>">
  Optional per-secret restrictions. When the sandbox uses a listed secret in a request, only the listed hosts are reachable for that request. For layered forks, the primary store's secrets shadow the base on name collisions (matches runtime env-collision behavior).
</ParamField>

***

## Properties

<ParamField type="string">
  Sandbox ID (readonly)
</ParamField>

<ParamField type="string">
  Current status (readonly)
</ParamField>

<ParamField type="string">
  Preview URL domain for port 80 (e.g., `sb-abc123-p80.workers.opencomputer.dev`). Returns empty string if sandbox domain is not configured.
</ParamField>

<ParamField type="SandboxAgent">
  [Sandbox agent sessions](/reference/typescript-sdk/agent)
</ParamField>

<ParamField type="Exec">
  [Command execution](/reference/typescript-sdk/exec)
</ParamField>

<ParamField type="Filesystem">
  [File operations](/reference/typescript-sdk/filesystem)
</ParamField>

<ParamField type="Pty">
  [Terminal sessions](/reference/typescript-sdk/pty)
</ParamField>

<ParamField type="Exec">
  **Deprecated** — alias for `exec`
</ParamField>

***

## Types

<Accordion title="SandboxOpts">
  ```typescript theme={null}
  interface SandboxOpts {
    template?: string;
    timeout?: number;
    apiKey?: string;
    apiUrl?: string;
    envs?: Record<string, string>;
    metadata?: Record<string, string>;
    cpuCount?: number;
    memoryMB?: number;
    secretStore?: string;
    image?: Image;
    snapshot?: string;
    onBuildLog?: (log: string) => void;
  }
  ```
</Accordion>

<Accordion title="CheckpointInfo">
  ```typescript theme={null}
  interface CheckpointInfo {
    id: string;
    sandboxId: string;
    orgId: string;
    name: string;
    sandboxConfig: object;
    status: string;       // "processing" | "ready" | "failed"
    sizeBytes: number;
    createdAt: string;
  }
  ```
</Accordion>

<Accordion title="PatchInfo / PatchResult">
  ```typescript theme={null}
  interface PatchInfo {
    id: string;
    checkpointId: string;
    sequence: number;
    script: string;
    description: string;
    strategy: string;     // "on_wake"
    createdAt: string;
  }

  interface PatchResult {
    patch: PatchInfo;
  }
  ```
</Accordion>

<Accordion title="PreviewURLResult">
  ```typescript theme={null}
  interface PreviewURLResult {
    id: string;
    sandboxId: string;
    orgId: string;
    hostname: string;
    customHostname?: string;
    port: number;
    cfHostnameId?: string;
    sslStatus: string;
    authConfig?: object;
    createdAt: string;
  }
  ```
</Accordion>


# Scaling
Source: https://docs.opencomputer.dev/reference/typescript-sdk/scaling

Resize a sandbox manually, autoscale on memory pressure, or freeze its resources.

OpenComputer sandboxes can change size at runtime. There are three knobs:

| What you want                       | Use                                                  |
| ----------------------------------- | ---------------------------------------------------- |
| Resize once, predictably            | [`scale()`](#sandbox-scale-opts)                     |
| Track memory pressure automatically | [`setAutoscale()`](#sandbox-setautoscale-opts)       |
| Freeze the current size             | [`setScalingLock()`](#sandbox-setscalinglock-locked) |

CPU follows memory per the platform's tier table. You don't pick CPU separately.

## How the three interact

* **Manual `scale()`** disables autoscale on the sandbox as a side effect — explicit user intent overrides the loop. Re-enable autoscale with `setAutoscale({ enabled: true, ... })` after if you want.
* **Setting a scaling lock** disables autoscale at the same time (single-knob: "I don't want this scaling, period"). While locked, both `scale()` and `setAutoscale({ enabled: true })` reject with `ScalingLockedError`. Unlocking does NOT auto-re-enable autoscale.
* **Plan caps** apply everywhere. Free-tier orgs are capped at 4 GB. Calls above the cap throw `PlanLimitError`.

***

## `sandbox.scale(opts)`

Manually resize the sandbox. [HTTP API →](/api-reference/sandboxes/scale)

<ParamField type="number">
  Target memory in MB.
</ParamField>

**Returns:** `Promise<{ sandboxID: string; memoryMB: number; cpuPercent: number }>`

**Throws:**

* `ScalingLockedError` — sandbox has a scaling lock active.
* `PlanLimitError` — `memoryMB` exceeds the org's plan cap.

```typescript theme={null}
import { Sandbox, ScalingLockedError, PlanLimitError } from "@opencomputer/sdk";

const sandbox = await Sandbox.connect("sb-abc123");

try {
  const result = await sandbox.scale({ memoryMB: 8192 });
  console.log(`scaled to ${result.memoryMB}MB / ${result.cpuPercent}% CPU`);
} catch (err) {
  if (err instanceof ScalingLockedError) {
    console.warn("sandbox is locked — unlock to scale");
  } else if (err instanceof PlanLimitError) {
    console.warn("upgrade required for larger instances");
  } else {
    throw err;
  }
}
```

***

## `sandbox.setAutoscale(opts)`

Enable or disable per-sandbox autoscale.

<ParamField type="boolean">
  Whether autoscale should be active.
</ParamField>

<ParamField type="number">
  Lower bound when `enabled=true`.
</ParamField>

<ParamField type="number">
  Upper bound when `enabled=true`. Must be ≥ `minMemoryMB`.
</ParamField>

**Returns:** `Promise<{ sandboxID: string; enabled: boolean; minMemoryMB: number; maxMemoryMB: number }>`

**Throws:**

* `ScalingLockedError` — sandbox has a scaling lock active.
* `PlanLimitError` — `maxMemoryMB` exceeds the org's plan cap.

When `enabled=true`, the platform watches the sandbox's memory pressure and resizes it within the bounds:

* **Scale up** on a single 1-min sample above 75% memory utilization. Cooldown 60s between up-scales.
* **Scale down** only when 1-min, 5-min, AND 15-min averages all sit below 25%. Cooldown 5 min between down-scales.

The asymmetry matches user perception: rapid response when the user notices lag, conservative shrink after sustained idle. The 15-min window is the dominant constraint on shrink, so a sandbox that briefly idles and resumes won't sawtooth.

```typescript theme={null}
await sandbox.setAutoscale({
  enabled: true,
  minMemoryMB: 1024,
  maxMemoryMB: 16384,
});
```

To turn off:

```typescript theme={null}
await sandbox.setAutoscale({ enabled: false });
```

***

## `sandbox.getAutoscale()`

Get the current autoscale configuration.

**Returns:** `Promise<{ sandboxID: string; enabled: boolean; minMemoryMB: number; maxMemoryMB: number }>`

```typescript theme={null}
const cfg = await sandbox.getAutoscale();
if (cfg.enabled) {
  console.log(`autoscale ${cfg.minMemoryMB}–${cfg.maxMemoryMB} MB`);
}
```

***

## `sandbox.setScalingLock(locked)`

Lock or unlock the sandbox's resources against any size change.

<ParamField type="boolean">
  `true` to freeze, `false` to allow scaling again.
</ParamField>

**Returns:** `Promise<{ sandboxID: string; locked: boolean }>`

While locked:

* `scale()` rejects with `ScalingLockedError`.
* `setAutoscale({ enabled: true })` rejects with `ScalingLockedError`.
* The platform autoscaler skips this sandbox entirely.

Locking ALSO disables autoscale (single knob — "I don't want this scaling"). Unlocking does **not** re-enable autoscale; call `setAutoscale({ enabled: true, ... })` explicitly if you want it back.

```typescript theme={null}
// Pin a sandbox at its current size during a critical workload
await sandbox.setScalingLock(true);

// ...

// Allow scaling again after
await sandbox.setScalingLock(false);
```

***

## `sandbox.getScalingLock()`

Get the current scaling-lock state.

**Returns:** `Promise<{ sandboxID: string; locked: boolean }>`

***

## Errors

### `ScalingLockedError`

Thrown when the sandbox has a scaling lock active. Has a `code` property of `"scaling_locked"` for parity with the HTTP API's error code.

```typescript theme={null}
import { ScalingLockedError } from "@opencomputer/sdk";

try {
  await sandbox.scale({ memoryMB: 8192 });
} catch (err) {
  if (err instanceof ScalingLockedError) {
    // unlock first, or surface to user
  }
}
```

### `PlanLimitError`

Thrown when the requested size exceeds the org's plan cap. The HTTP API returns 402 Payment Required for this case.


# Secret Stores
Source: https://docs.opencomputer.dev/reference/typescript-sdk/secrets

Manage secrets and egress control

## `SecretStore.create(opts)`

Create a new secret store.

```typescript theme={null}
import { SecretStore } from '@opencomputer/sdk';

const store = await SecretStore.create({
  name: 'my-agent-secrets',
  egressAllowlist: ['api.anthropic.com'],
});
```

<ParamField type="string">
  Store name (unique per organization)
</ParamField>

<ParamField type="string[]">
  Allowed egress hosts (e.g. `["api.anthropic.com"]`)
</ParamField>

**Returns:** `Promise<SecretStoreInfo>`

***

## `SecretStore.list(opts?)`

List all secret stores.

**Returns:** `Promise<SecretStoreInfo[]>`

***

## `SecretStore.get(storeId, opts?)`

Get a secret store by ID.

<ParamField type="string">
  UUID of the secret store
</ParamField>

**Returns:** `Promise<SecretStoreInfo>`

***

## `SecretStore.update(storeId, opts)`

Partial updates — only the fields you pass are changed.

```typescript theme={null}
const updated = await SecretStore.update('store-uuid', {
  name: 'new-name',
  egressAllowlist: ['api.anthropic.com', '*.openai.com'],
});
```

<ParamField type="string">
  UUID of the store to update
</ParamField>

<ParamField type="string">
  New store name
</ParamField>

<ParamField type="string[]">
  New allowed egress hosts
</ParamField>

**Returns:** `Promise<SecretStoreInfo>`

***

## `SecretStore.delete(storeId, opts?)`

Deletes the store and all its secrets. Running sandboxes are not affected.

**Returns:** `Promise<void>`

***

## `SecretStore.setSecret(storeId, name, value, opts?)`

Set a secret in a store. Secrets are encrypted at rest. The value is never returned by the API.

```typescript theme={null}
await SecretStore.setSecret('store-uuid', 'ANTHROPIC_API_KEY', 'sk-ant-...');
```

Optionally restrict which hosts can receive this secret:

```typescript theme={null}
await SecretStore.setSecret('store-uuid', 'ANTHROPIC_API_KEY', 'sk-ant-...', {
  allowedHosts: ['api.anthropic.com'],
});
```

<ParamField type="string">
  UUID of the secret store
</ParamField>

<ParamField type="string">
  Secret name (used as the env var name in sandboxes)
</ParamField>

<ParamField type="string">
  Secret value (encrypted at rest, never returned by API)
</ParamField>

<ParamField type="string[]">
  Restrict this secret to specific hosts only
</ParamField>

**Returns:** `Promise<void>`

***

## `SecretStore.listSecrets(storeId, opts?)`

Returns secret metadata only. Values are never exposed.

**Returns:** `Promise<SecretEntryInfo[]>`

***

## `SecretStore.deleteSecret(storeId, name, opts?)`

**Returns:** `Promise<void>`

***

## Using Secrets with Sandboxes

Pass the `secretStore` option to `Sandbox.create()` to inject the store's secrets:

```typescript theme={null}
const sandbox = await Sandbox.create({
  secretStore: 'my-agent-secrets',
  timeout: 600,
});

// Secrets are available as sealed env vars
const result = await sandbox.commands.run('echo $ANTHROPIC_API_KEY');
// stdout: "osb_sealed_abc123..." (sealed, not the real key)

// But outbound HTTPS requests get the real value substituted by the proxy
const apiResult = await sandbox.commands.run(
  'curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" ...'
);
```

## Using Secrets with Snapshots and Checkpoints

### Snapshot template with secrets

Attach a secret store when creating a sandbox from a pre-built snapshot — even if the snapshot was built without one:

```typescript theme={null}
import { Sandbox, Snapshots, Image } from '@opencomputer/sdk/node';

// Pre-build a snapshot with dependencies
const snapshots = new Snapshots();
await snapshots.create({
  name: 'data-pipeline',
  image: Image.base().aptInstall(['python3-pip']).pipInstall(['pandas']),
});

// Create sandboxes from the snapshot, each with their own credentials
const worker1 = await Sandbox.create({
  snapshot: 'data-pipeline',
  secretStore: 'worker-1-keys',
});
const worker2 = await Sandbox.create({
  snapshot: 'data-pipeline',
  secretStore: 'worker-2-keys',
});
```

### Checkpoint fork with secrets

Attach or layer a secret store when forking from a checkpoint:

```typescript theme={null}
// Bake a base environment with git credentials
const base = await Sandbox.create({ secretStore: 'git-creds' });
await base.exec.run('git clone https://github.com/org/repo /app', { cwd: '/' });
const cp = await base.createCheckpoint('repo-cloned');

// Fork with different credentials per sandbox (layered on top of git-creds)
const worker = await Sandbox.createFromCheckpoint(cp.id, {
  secretStore: 'worker-keys',  // layered on top of git-creds
});
```

When layered, secrets merge (fork's store wins on collision) and egress allowlists aggregate.

***

## Types

<Accordion title="SecretStoreInfo">
  | Property          | Type       | Description          |
  | ----------------- | ---------- | -------------------- |
  | `id`              | `string`   | Store UUID           |
  | `orgId`           | `string`   | Organization UUID    |
  | `name`            | `string`   | Store name           |
  | `egressAllowlist` | `string[]` | Allowed egress hosts |
  | `createdAt`       | `string`   | ISO 8601 timestamp   |
  | `updatedAt`       | `string`   | ISO 8601 timestamp   |
</Accordion>

<Accordion title="SecretEntryInfo">
  | Property       | Type       | Description                |
  | -------------- | ---------- | -------------------------- |
  | `id`           | `string`   | Entry UUID                 |
  | `storeId`      | `string`   | Parent store UUID          |
  | `name`         | `string`   | Secret name (env var name) |
  | `allowedHosts` | `string[]` | Host restrictions          |
  | `createdAt`    | `string`   | ISO 8601 timestamp         |
  | `updatedAt`    | `string`   | ISO 8601 timestamp         |
</Accordion>


# Snapshots
Source: https://docs.opencomputer.dev/reference/typescript-sdk/snapshots

Pre-built sandbox environments

Standalone class — not a property on Sandbox.

## Constructor

```typescript theme={null}
import { Snapshots } from "@opencomputer/sdk";

const snapshots = new Snapshots();
// or with explicit config:
const snapshots = new Snapshots({ apiKey: "...", apiUrl: "..." });
```

<ParamField type="string">
  API key (falls back to `OPENCOMPUTER_API_KEY` env var)
</ParamField>

<ParamField type="string">
  API URL (falls back to `OPENCOMPUTER_API_URL` env var)
</ParamField>

***

## `snapshots.create(opts)`

Create a pre-built snapshot from a declarative image. [HTTP API →](/api-reference/snapshots/create)

<ParamField type="string">
  Unique snapshot name
</ParamField>

<ParamField type="Image">
  Declarative image definition
</ParamField>

<ParamField type="(log: string) => void">
  Build log streaming callback
</ParamField>

**Returns:** `Promise<SnapshotInfo>`

***

## `snapshots.list()`

List all snapshots. [HTTP API →](/api-reference/snapshots/list)

**Returns:** `Promise<SnapshotInfo[]>`

***

## `snapshots.get(name)`

Get a snapshot by name. [HTTP API →](/api-reference/snapshots/get)

<ParamField type="string">
  Snapshot name
</ParamField>

**Returns:** `Promise<SnapshotInfo>`

***

## `snapshots.delete(name)`

Delete a snapshot. Existing sandboxes created from it are not affected. [HTTP API →](/api-reference/snapshots/delete)

<ParamField type="string">
  Snapshot name
</ParamField>

**Returns:** `Promise<void>`

***

## Types

<Accordion title="SnapshotInfo">
  ```typescript theme={null}
  interface SnapshotInfo {
    id: string;
    name: string;
    status: string;       // "building" | "ready" | "failed"
    contentHash: string;
    checkpointId: string;
    manifest: object;
    createdAt: string;
    lastUsedAt: string;
  }
  ```
</Accordion>


# Usage & Tags
Source: https://docs.opencomputer.dev/reference/typescript-sdk/usage

Query sandbox usage, group by tag, and manage sandbox tags

Use `Usage` for billing-aligned usage queries and per-sandbox
time-series drilldowns. Use `Tags` to set and read sandbox tags used
by the usage aggregator.

<Note>
  **Preview:** Usage and tag APIs are new. Endpoints, response fields,
  and SDK method names may change before GA; temporary inaccuracies or
  rough edges are possible while the surface settles.
</Note>

```typescript theme={null}
import { Usage, Tags } from "@opencomputer/sdk";

const usage = new Usage("https://app.opencomputer.dev", process.env.OPENCOMPUTER_API_KEY!);
const tags = new Tags("https://app.opencomputer.dev", process.env.OPENCOMPUTER_API_KEY!);
```

The `apiUrl` may include or omit `/api`; both
`https://app.opencomputer.dev` and `https://app.opencomputer.dev/api`
work.

## `usage.forSandbox(sandboxId, opts?)`

Return 1-minute memory points plus envelope totals for one sandbox.
[HTTP API ->](/api-reference/usage/get-sandbox-usage)

<ParamField type="string">
  Sandbox ID.
</ParamField>

<ParamField type="string">
  ISO date (`YYYY-MM-DD`) or RFC3339 lower bound. Default: now minus
  1 hour.
</ParamField>

<ParamField type="string">
  ISO date (`YYYY-MM-DD`) or RFC3339 upper bound. Default: now.
  Window must be at most 30 days.
</ParamField>

**Returns:** `Promise<SandboxUsageResponse>`

```typescript theme={null}
const r = await usage.forSandbox("sb-abc123", {
  from: "2026-05-27T00:00:00Z",
  to: "2026-05-27T01:00:00Z",
});

const utilization =
  r.totals.memoryAllocatedGbSeconds === 0
    ? 0
    : r.totals.memoryUsedGbSeconds / r.totals.memoryAllocatedGbSeconds;

console.log(`${(utilization * 100).toFixed(0)}% memory utilization`);

for (const point of r.points) {
  // point.ts, point.allocatedMemoryMb, point.usedMemoryMbAvg
  // are ready to render as chart series.
}
```

## `usage.bySandbox(opts?)`

Rank sandboxes by usage for an organization. [HTTP API ->](/api-reference/usage/get-usage)

<ParamField type="string">
  ISO date (`YYYY-MM-DD`) or RFC3339 lower bound. Default: now minus
  30 days.
</ParamField>

<ParamField type="string">
  ISO date (`YYYY-MM-DD`) or RFC3339 upper bound. Default: now.
  Window must be at most 90 days.
</ParamField>

<ParamField type="Record<string, string>">
  Tag filters. Keys are dimensions such as `"tag:team"`. Values are
  exact tag values, comma-separated OR values, or `""` to match
  sandboxes without that tag key.
</ParamField>

<ParamField type="string">
  `"-memoryGbSeconds"` (default) or `"-diskOverageGbSeconds"`.
</ParamField>

<ParamField type="number">
  Max rows per page. Default 50, max 500.
</ParamField>

<ParamField type="string">
  Cursor returned by the previous page's `nextCursor`.
</ParamField>

**Returns:** `Promise<UsageBySandboxResponse>`

```typescript theme={null}
const page = await usage.bySandbox({
  from: "2026-05-01T00:00:00Z",
  to: "2026-06-01T00:00:00Z",
  filter: { "tag:team": "payments" },
  limit: 20,
});

for (const item of page.items) {
  console.log(item.sandboxId, item.memoryGbSeconds, item.tags);
}

if (page.nextCursor) {
  const next = await usage.bySandbox({
    from: "2026-05-01T00:00:00Z",
    to: "2026-06-01T00:00:00Z",
    filter: { "tag:team": "payments" },
    cursor: page.nextCursor,
  });
}
```

## `usage.byTag(tagKey, opts?)`

Group usage by the value of one tag key. Tag keys may contain `:`.
[HTTP API ->](/api-reference/usage/get-usage)

<ParamField type="string">
  Tag key to group by, for example `"team"` or `"team:subsystem"`.
</ParamField>

<ParamField type="Record<string, string>">
  Optional tag filters applied before grouping.
</ParamField>

<ParamField type="string">
  ISO date (`YYYY-MM-DD`) or RFC3339 lower bound. Default: now minus
  30 days.
</ParamField>

<ParamField type="string">
  ISO date (`YYYY-MM-DD`) or RFC3339 upper bound. Default: now.
  Window must be at most 90 days.
</ParamField>

<ParamField type="string">
  `"-memoryGbSeconds"` (default) or `"-diskOverageGbSeconds"`.
</ParamField>

<ParamField type="number">
  Max rows per page. Default 50, max 500.
</ParamField>

<ParamField type="string">
  Cursor returned by the previous page's `nextCursor`.
</ParamField>

**Returns:** `Promise<UsageByTagResponse>`

```typescript theme={null}
const byTeam = await usage.byTag("team", {
  filter: { "tag:env": "prod" },
});

for (const row of byTeam.items) {
  console.log(row.tagValue, row.memoryGbSeconds, row.sandboxCount);
}

console.log("untagged", byTeam.untagged.memoryGbSeconds);

const bySubsystem = await usage.byTag("team:subsystem");
```

## `tags.set(sandboxId, tags)`

Replace the full tag set for a sandbox. Partial updates are not
supported: read, modify, then write the full map. [HTTP API ->](/api-reference/sandboxes/set-tags)

<ParamField type="string">
  Sandbox ID.
</ParamField>

<ParamField type="Record<string, string>">
  Flat tag map. `{}` clears all tags.
</ParamField>

**Returns:** `Promise<{ tags: Record<string, string>; tagsLastUpdatedAt: string | null }>`

```typescript theme={null}
await tags.set("sb-abc123", {
  team: "payments",
  env: "prod",
  "team:subsystem": "checkout",
});
```

## `tags.get(sandboxId)`

Read the current tag set for a sandbox. [HTTP API ->](/api-reference/sandboxes/get-tags)

**Returns:** `Promise<{ tags: Record<string, string>; tagsLastUpdatedAt: string | null }>`

```typescript theme={null}
const current = await tags.get("sb-abc123");
console.log(current.tags);
```

## `tags.listKeys()`

List tag keys seen in the organization, with counts for tagged
sandboxes and distinct values. [HTTP API ->](/api-reference/usage/list-tags)

**Returns:** `Promise<TagKeyInfo[]>`

```typescript theme={null}
const keys = await tags.listKeys();
for (const key of keys) {
  console.log(key.key, key.sandboxCount, key.valueCount);
}
```

## Units

All `*GbSeconds` fields are **GiB-seconds**. For example, a sandbox
provisioned at `4096` MiB for one minute reports `240`
`memoryAllocatedGbSeconds`.

`memoryAllocatedGbSeconds` is billing-aligned provisioned memory.
`memoryUsedGbSeconds` is measured resident memory from the worker
collector, so it can lag by a few minutes after a sandbox starts.

## Types

<Accordion title="SandboxUsageResponse">
  ```typescript theme={null}
  interface SandboxUsageResponse {
    sandboxId: string;
    alias?: string;
    from: string;
    to: string;
    totals: SandboxUsageTotals;
    points: SandboxUsagePoint[];
  }
  ```
</Accordion>

<Accordion title="SandboxUsagePoint">
  ```typescript theme={null}
  interface SandboxUsagePoint {
    ts: string;
    memoryAllocatedGbSeconds: number;
    memoryUsedGbSeconds: number;
    uptimeSeconds: number;
    allocatedMemoryMb: number;
    usedMemoryMbAvg: number;
    usedMemoryMbPeak: number;
  }
  ```
</Accordion>

<Accordion title="SandboxUsageTotals">
  ```typescript theme={null}
  interface SandboxUsageTotals {
    memoryAllocatedGbSeconds: number;
    memoryUsedGbSeconds: number;
    uptimeSeconds: number;
    memoryAllocatedPeakMb: number;
    memoryUsedPeakMb: number;
  }
  ```
</Accordion>

<Accordion title="UsageSandboxItem">
  ```typescript theme={null}
  interface UsageSandboxItem {
    sandboxId: string;
    alias?: string;
    status?: string;
    tags: Record<string, string>;
    tagsLastUpdatedAt: string | null;
    memoryGbSeconds: number;
    diskOverageGbSeconds: number;
  }
  ```
</Accordion>

<Accordion title="UsageTagItem">
  ```typescript theme={null}
  interface UsageTagItem {
    tagKey: string;
    tagValue: string;
    memoryGbSeconds: number;
    diskOverageGbSeconds: number;
    sandboxCount: number;
  }
  ```
</Accordion>


# Reading the Calendar
Source: https://docs.opencomputer.dev/reserved-capacity/calendar

Preview reservable capacity and existing commitments per 15-minute interval

The calendar is how you plan. It answers, per 15-minute interval:

1. How much GB can I still reserve here?
2. How much do I already hold here?
3. What's the policy cap I'm working under?

The calendar never holds capacity — it's a snapshot. Write validation is
always authoritative.

## Request

```bash curl theme={null}
curl "https://app.opencomputer.dev/api/capacity/calendar?from=2026-04-29T02:00:00Z&to=2026-04-29T04:00:00Z" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY"
```

| Query param | Required | Notes                                     |
| ----------- | -------- | ----------------------------------------- |
| `from`      | yes      | Window start, aligned to 15 minutes, UTC. |
| `to`        | yes      | Window end, aligned to 15 minutes, UTC.   |

## Response

```json theme={null}
{
  "from":      "2026-04-29T02:00:00Z",
  "to":        "2026-04-29T04:00:00Z",
  "resource":  "memory_gb",
  "intervals": [
    {
      "startsAt": "2026-04-29T02:00:00Z",
      "endsAt":   "2026-04-29T02:15:00Z",
      "reservationLimitGb": 300,
      "reservedGb": 80,
      "reservableGb": 220
    }
  ]
}
```

### Top-level fields

| Field        | Meaning                                       |
| ------------ | --------------------------------------------- |
| `from`, `to` | The query window, echoed back.                |
| `resource`   | Always `memory_gb` in v1.                     |
| `intervals`  | One row per 15-minute interval in the window. |

### Per-interval fields

| Field                | Meaning                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `startsAt`, `endsAt` | The 15-minute UTC interval.                                                              |
| `reservationLimitGb` | Maximum GB this org may commit in this interval (your `max_memory_gb`).                  |
| `reservedGb`         | Total GB this org already has reserved in this interval.                                 |
| `reservableGb`       | Additional GB the server would currently accept. **This is the number to plan against.** |

The server enforces a **30-minute minimum lead time** between `now`
and a reservation's `startsAt`. Intervals starting sooner are returned
in the calendar (so you can see your existing commitments) but the
write endpoint rejects new reservations against them.

## `reservableGb` is the planning field

Everything you need to decide "can I reserve 50 GB at 02:00?" is in
`reservableGb`. The other fields are context:

* `reservationLimitGb` minus `reservedGb` is your remaining headroom under
  your org's per-interval cap. The server may still reduce `reservableGb`
  below that headroom because of platform-level capacity.
* `reservedGb` lets you confirm what you already hold without a separate
  call to `GET /api/capacity/reservations`.

## The calendar is a snapshot, not a hold

The calendar reflects state at the moment the request was served.
Capacity can change between read and write — another tenant (or you,
in another tab) may reserve in the meantime.

This is fine. Writes are atomic and validation is authoritative: if
capacity moved, the write returns `capacity_not_available` and you read
again.

## Race patterns

### Plan then write

```text theme={null}
GET  /api/capacity/calendar                       → reservableGb: 220
POST /api/capacity/reservations  capacityGb: 80   → applied
```

### Plan then write, lost race

```text theme={null}
GET  /api/capacity/calendar                       → reservableGb: 48
POST /api/capacity/reservations  capacityGb: 80   → rejected with reservableGb: 28
```

On rejection, read the calendar again and either:

* Re-submit with the actual current `reservableGb`, or
* Accept a smaller amount via multiple writes at different intervals, or
* Bail out — not all demand fits.

V1 does not accept a "reserve up to N, at least M" shape. Keep retries
explicit in client code.

### Multi-interval request, partial conflict

```text theme={null}
POST /api/capacity/reservations
  intervals: [
    02:00 → 02:15, 80 GB
    02:15 → 02:30, 80 GB    # only 30 available
  ]
→ rejected; nothing reserved
```

Multi-interval writes are atomic. If any interval fails, none are
reserved. Split your request if you want partial success.

## Choosing the window

The calendar accepts arbitrary `from`–`to` ranges aligned to the 15-minute
grid. Practical guidance:

* For interactive planning UIs, pull a day or a week at a time; render a
  heatmap of `reservableGb`.
* For scheduled reservation scripts, query just the intervals you're about
  to write — don't pull a week if you only need two hours.
* For large time ranges, expect the response to scale linearly (`4 ×
  hours` rows). Chunk your queries if you need months.

## What the calendar does *not* tell you

* **Past reservation events.** Use `GET /api/capacity/reservations` for
  the audit log.
* **Other customers' commitments.** Numbers are org-scoped.
* **Future limit changes.** Your `reservationLimitGb` reflects current
  policy.

## Where to go next

<CardGroup>
  <Card title="Reserving capacity" icon="lock" href="/reserved-capacity/reserving">
    The write flow, idempotency, atomicity.
  </Card>

  <Card title="Concepts" icon="shapes" href="/reserved-capacity/concepts">
    Vocabulary: intervals, reservations, the log.
  </Card>

  <Card title="Get calendar endpoint" icon="code" href="/api-reference/capacity/get-calendar">
    Full request/response reference.
  </Card>
</CardGroup>


# Concepts
Source: https://docs.opencomputer.dev/reserved-capacity/concepts

Intervals, reservations, the reservation log, and the per-org cap

A small vocabulary. Learn these and the rest of the API reads itself.

## Interval

A 15-minute window on the UTC quarter-hour grid.

| Field      | Meaning                                                                          |
| ---------- | -------------------------------------------------------------------------------- |
| `startsAt` | Inclusive start. Always ends in `:00`, `:15`, `:30`, or `:45` with zero seconds. |
| `endsAt`   | Exclusive end. Always `startsAt + 15 minutes`.                                   |

The 15-minute grain is the smallest commitment unit and that's the point.
You can shape a reservation to the exact contour of your workload — a
nightly window, working-hour blocks, an hourly cron — without paying for
idle slots outside it.

Half-open intervals (`[startsAt, endsAt)`) mean two adjacent reservations
never overlap and never leave gaps.

```text theme={null}
02:00 ────────────── 02:15 ────────────── 02:30
   interval A            interval B
```

A reservation that spans multiple intervals is a list of adjacent interval
entries, not a single range:

```json theme={null}
{
  "intervals": [
    { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 },
    { "startsAt": "2026-04-29T02:15:00Z", "endsAt": "2026-04-29T02:30:00Z", "capacityGb": 16 }
  ]
}
```

## Reservation

A commitment event. Each `POST /api/capacity/reservations` creates one
reservation: a server-generated UUID, a `createdAt` timestamp, and one or
more `(interval, capacityGb)` line items. `capacityGb` must be a positive
multiple of 4 (= 1 GB-hour over the 15-minute interval); single-GB
reservations aren't accepted.

```json theme={null}
{
  "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
  "createdAt": "2026-04-28T18:00:05Z",
  "intervals": [
    { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 }
  ]
}
```

Reservations are **append-only**. Once created, a reservation cannot be
cancelled, modified, or transferred. To add more capacity to an interval,
post another reservation; the totals add up at the interval level.

## The reservation log

The list of all your reservations is the durable, auditable record of your
commitments over time. `GET /api/capacity/reservations` returns it in
reverse-chronological order.

This is also how the calendar is computed internally: at any moment,
`reservedGb` for an interval is just the sum of `capacityGb` across all
your reservations covering that interval.

## Calendar

The planning read model. Given a time range, returns one row per interval
with the numbers you need to plan:

| Field                | Meaning                                                                                |
| -------------------- | -------------------------------------------------------------------------------------- |
| `reservableGb`       | Additional GB you could add to this interval right now.                                |
| `reservationLimitGb` | The policy cap on how much you can hold in this interval (your org's `max_memory_gb`). |
| `reservedGb`         | What you already hold in this interval (sum of all your reservations covering it).     |

The calendar **previews availability** but never holds capacity. Capacity
can change between when you read the calendar and when you submit a
reservation; if it does, the write returns `capacity_not_available` and you
re-read.

See [Reading the calendar](/reserved-capacity/calendar) for the full shape.

## Per-org capacity cap

Your org has a configured ceiling: `max_memory_gb`. It limits how
much capacity you can hold in any single 15-minute interval — your
`reservedGb` for an interval cannot exceed it. The cap appears as
`reservationLimitGb` in calendar interval rows.

If you need to reserve more than your current limit allows, ask to
have the limit raised.

## Usage and overage

Starting and stopping sandboxes is independent of reserving capacity.
Reservations don't pre-warm or pre-allocate compute; they're an
accounting commitment.

For each 15-minute interval, at every instant:

* If your concurrent memory ≤ `reservedGb` → you're inside your reserved
  capacity. That portion of the interval is billed at the reserved rate.
* If your concurrent memory > `reservedGb` → the excess is overage,
  billed at the on-demand rate.

Reserved capacity is a flat ceiling at any instant, not a GB-second budget
that averages out over the interval. A brief spike above the ceiling
produces overage during those seconds, even if your average usage was
below it.

You also pay for the **full reservation** regardless of actual usage.
That's the commitment; it's why reserved rates are lower.

## Where to go next

<CardGroup>
  <Card title="Reading the calendar" icon="calendar" href="/reserved-capacity/calendar">
    Plan reservations before you commit.
  </Card>

  <Card title="Reserving capacity" icon="lock" href="/reserved-capacity/reserving">
    The write flow, idempotency, atomicity.
  </Card>

  <Card title="Usage and overage" icon="gauge" href="/reserved-capacity/usage-and-overage">
    How reserved capacity is consumed.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/capacity/get-calendar">
    Every endpoint with full request/response shapes.
  </Card>
</CardGroup>


# Reserved Capacity
Source: https://docs.opencomputer.dev/reserved-capacity/overview

Commit memory capacity to future 15-minute intervals at a discounted rate

Reserved capacity lets you pre-commit to memory you'll use later. OpenComputer
plans for it instead of holding margin against uncertain demand; you get a
lower effective rate on the committed usage. Pure on-demand still works for
everything else.

## Reservations are non-refundable

Once you commit to capacity for an interval, that's a permanent commitment.
There is no cancellation, no transfer, no partial refund. The commitment is
the whole reason the rate is lower — any carve-out re-introduces the demand
risk reserved capacity exists to remove.

The hedge is to **book conservatively**: reserve only what you're confident
you'll run, and let on-demand absorb everything else.

## The unit is 1 GB-hour

Reservations are made against 15-minute UTC intervals on the quarter-hour
grid: `:00`, `:15`, `:30`, `:45`. Within each interval, the minimum
commitment is **4 GB for 15 minutes — that is, 1 GB-hour.** All
reservations must be multiples of 4 GB per interval; anything smaller
isn't a meaningful commitment unit and the API rejects it.

The 15-minute time grain is deliberate. Reserve the slots you'll actually
run in — you aren't pushed into a long contiguous block and asked to pay
for the troughs in between. A nightly batch reserves the eight intervals
it occupies; a weekday workload reserves working hours and skips evenings
and weekends. The reserved rate applies whatever shape your demand takes.

You don't book individual blocks or get block IDs back. You just tell the
API "for this interval, add this many GB to my reserved capacity," and the
calendar shows you the new total.

## A small example

Reserve 16 GB for the 02:00–02:15 UTC slot tomorrow:

```bash curl theme={null}
curl -X POST https://app.opencomputer.dev/api/capacity/reservations \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
  -H "Idempotency-Key: demo-1" \
  -H "Content-Type: application/json" \
  -d '{
    "intervals": [
      {
        "startsAt": "2026-04-29T02:00:00Z",
        "endsAt":   "2026-04-29T02:15:00Z",
        "capacityGb": 16
      }
    ]
  }'
```

Response:

```json theme={null}
{
  "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
  "createdAt": "2026-04-28T18:00:05Z",
  "intervals": [
    {
      "startsAt": "2026-04-29T02:00:00Z",
      "endsAt":   "2026-04-29T02:15:00Z",
      "capacityGb": 16
    }
  ]
}
```

That's it. Run sandboxes normally during 02:00–02:15; they'll be allocated
against your reserved capacity automatically. Anything over 16 GB during
that interval falls back to on-demand rates.

## Why reserve instead of running on-demand?

|              | On-demand (instant)               | Reserved (pre-booked)                                      |
| ------------ | --------------------------------- | ---------------------------------------------------------- |
| Rate         | \$0.060/GB-hour                   | \$0.012/GB-hour                                            |
| Commitment   | None                              | Full — you pay regardless of usage                         |
| Availability | Subject to platform headroom      | Guaranteed for the interval you booked                     |
| Best for     | Unpredictable or bursty workloads | Nightly batch jobs, scheduled runs, known traffic patterns |

If you already know you'll run 48 GB of agents at 3am every night, reserve
the day before, get the lower rate, get the guarantee. If your workload is
"whatever users ask for," stay on-demand. And because the granularity is
15 minutes, you can be precise — reserve the peaks, leave the troughs to
on-demand, and don't commit to capacity outside your actual workload
window.

## Where to go next

<CardGroup>
  <Card title="Concepts" icon="shapes" href="/reserved-capacity/concepts">
    The vocabulary: intervals, reservations, the reservation log.
  </Card>

  <Card title="Reading the calendar" icon="calendar" href="/reserved-capacity/calendar">
    Plan reservations before you commit.
  </Card>

  <Card title="Reserving capacity" icon="lock" href="/reserved-capacity/reserving">
    The write flow, idempotency, atomicity.
  </Card>

  <Card title="Usage and overage" icon="gauge" href="/reserved-capacity/usage-and-overage">
    How reserved capacity is consumed and how overage is billed.
  </Card>
</CardGroup>

<Tip>
  Full endpoint reference: [`/api/capacity/*`](/api-reference/capacity/get-calendar).
</Tip>

<Note>
  **Pricing.** Pre-booked capacity bills at **$0.012/GB-hour**; instant
      (overage) bills at **$0.060/GB-hour** — a 5× ratio that's the price of
  optionality for capacity you didn't pre-commit. Both rates are flat
  across sandbox sizes. Disk above the 20 GB allowance is billed
  separately at the disk-overage rate (unchanged).
</Note>


# Reserving Capacity
Source: https://docs.opencomputer.dev/reserved-capacity/reserving

Write flow, idempotency, atomicity, and the audit list

There are two write-side endpoints: `POST` to commit, `GET` to audit. Both
work in terms of intervals and integer GB; there are no individual blocks
or unit IDs.

Reservations compose at 15-minute granularity, so a multi-hour or
multi-day commitment is just a list of contiguous (or non-contiguous)
intervals. Reserve precisely the windows your workload occupies — there's
no minimum block size beyond the interval itself, and no requirement to
reserve continuously through periods you won't use.

## Make a reservation

One call commits capacity to one or more 15-minute intervals. Atomic across
the whole request — either every interval is reserved, or nothing is.

```bash curl theme={null}
curl -X POST https://app.opencomputer.dev/api/capacity/reservations \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
  -H "Idempotency-Key: nightly-batch-2026-04-29" \
  -H "Content-Type: application/json" \
  -d '{
    "intervals": [
      { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 },
      { "startsAt": "2026-04-29T02:15:00Z", "endsAt": "2026-04-29T02:30:00Z", "capacityGb": 16 }
    ]
  }'
```

Response (success):

```json theme={null}
{
  "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
  "createdAt": "2026-04-28T18:00:05Z",
  "intervals": [
    { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 },
    { "startsAt": "2026-04-29T02:15:00Z", "endsAt": "2026-04-29T02:30:00Z", "capacityGb": 16 }
  ]
}
```

### Validation

The server rejects malformed requests with `400 Bad Request` and a
plain text error message:

| Rule                                            | Failure                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------- |
| `startsAt` / `endsAt` UTC and 15-minute aligned | Misaligned values rejected.                                      |
| `endsAt == startsAt + 15 minutes`               | Multi-interval spans rejected — enumerate intervals instead.     |
| `capacityGb` is a positive multiple of 4        | Other values rejected. The grain is 1 GB-hour (= 4 GB × 15 min). |
| `startsAt >= now + 30 minutes`                  | Lead-time violation rejected.                                    |

### Capacity shortfall (409)

When the request is well-formed but doesn't fit available capacity,
the server returns `409 capacity_not_available` with a list of every
problematic interval, so the client can retry with adjusted numbers in
a single round-trip:

```json theme={null}
{
  "error": "capacity_not_available",
  "intervals": [
    {
      "startsAt": "2026-04-29T02:00:00Z",
      "requestedGb": 80,
      "reservableGb": 28,
      "reason": "insufficient_capacity"
    }
  ]
}
```

`reason` is one of:

| `reason`                | Meaning                                                                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `insufficient_capacity` | Request exceeds current `reservableGb` for the interval (either the platform-side limit or your org's `max_memory_gb`). |
| `concurrent_write`      | Another reservation for the same interval committed first; retry with the updated `reservableGb`.                       |

## Idempotency

Both reservation writes accept an `Idempotency-Key` header. The server
stores the key with a hash of the request body and the response. Retries
return the cached response, even if the original write succeeded.

| Behavior                 | Response                                                      |
| ------------------------ | ------------------------------------------------------------- |
| Same key, same body      | Cached response from the first call.                          |
| Same key, different body | `409 idempotency_key_conflict`.                               |
| No key                   | Request processed normally; retries are the client's problem. |

Build keys from a deterministic name for the operation, e.g.
`reserve-nightly-2026-04-29`, so a client retry sends the same key.

## Cancellation does not exist

Reservations are non-refundable. Once committed, capacity is permanent for
that interval. There is no `DELETE`, no cancel endpoint, no transfer to a
different interval.

The hedge: book conservatively, only what you're confident you'll run, and
let on-demand absorb the variability above.

## List your reservations

The audit list. Returns every reservation event you've made in the time
window, in reverse-chronological order.

```bash curl theme={null}
curl "https://app.opencomputer.dev/api/capacity/reservations?from=2026-04-01T00:00:00Z&to=2026-05-01T00:00:00Z" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY"
```

Response:

```json theme={null}
{
  "from": "2026-04-01T00:00:00Z",
  "to":   "2026-05-01T00:00:00Z",
  "reservations": [
    {
      "reservationId": "9f67b8f7-7b91-4d2d-b1cb-19d0d0a14562",
      "createdAt": "2026-04-28T18:00:05Z",
      "intervals": [
        { "startsAt": "2026-04-29T02:00:00Z", "endsAt": "2026-04-29T02:15:00Z", "capacityGb": 16 },
        { "startsAt": "2026-04-29T02:15:00Z", "endsAt": "2026-04-29T02:30:00Z", "capacityGb": 16 }
      ]
    }
  ],
  "nextCursor": null
}
```

| Query param | Required | Meaning                                                    |
| ----------- | -------- | ---------------------------------------------------------- |
| `from`      | yes      | Return reservations whose `createdAt >= from`.             |
| `to`        | yes      | Return reservations whose `createdAt < to`.                |
| `cursor`    | no       | Pagination cursor from a previous response's `nextCursor`. |
| `limit`     | no       | Max reservations per page. Server applies a ceiling.       |

For end-of-month reconciliation, list reservations and group totals by
interval. The calendar gives you the current per-interval state; the list
gives you the history of how it got there.

## Concurrency and atomicity

| Operation            | Atomic across                | On failure        |
| -------------------- | ---------------------------- | ----------------- |
| `POST /reservations` | All intervals in the request | Nothing reserved. |

Parallel writes to the same interval from the same org serialize on the
server. Whichever request commits first claims the remaining capacity;
later requests see the updated `reservableGb` in their validation error.

## Where to go next

<CardGroup>
  <Card title="Usage and overage" icon="gauge" href="/reserved-capacity/usage-and-overage">
    How reserved capacity consumes actual usage.
  </Card>

  <Card title="Reading the calendar" icon="calendar" href="/reserved-capacity/calendar">
    Plan before you commit.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/capacity/create-reservations">
    Every endpoint with full request/response shapes.
  </Card>
</CardGroup>


# Usage and Overage
Source: https://docs.opencomputer.dev/reserved-capacity/usage-and-overage

How reserved capacity is consumed and how overage is calculated

## Every second is its own settlement

Reserved capacity is billed and settled per second. Not per minute, not per
interval, not against a GB-second budget. At each second `t` within an
interval:

* if `usage(t) ≤ reservedGb`: that second's memory is covered by your
  reservation and billed at the reserved rate
* if `usage(t) > reservedGb`: the part above the ceiling is overage, billed
  at the on-demand rate

Per 15-minute interval, per `(org, resource)`:

```text theme={null}
reservedBilled  =  reservedGb × 900 sec                 (the commitment, regardless of usage)
overageBilled   =  ∑_t  max(usage(t) − reservedGb, 0)    (per-second integration)
```

Two charges, computed independently:

* **Reserved**: a flat `reservedGb × 900` GB-seconds, billed every interval
  at the reserved rate, whether you used it or not. That's the commitment.
* **Overage**: whatever exceeded the reserved ceiling at any instant,
  summed second by second, billed at the on-demand rate.

There is no draw-down, no carry-forward, no averaging. The ceiling is
re-checked every second.

## A worked example

You reserve 16 GB for `02:00–02:15`. Your sandboxes use:

| Phase | Duration | Memory |
| ----: | -------: | -----: |
|     1 |    600 s |   8 GB |
|     2 |     60 s |  30 GB |
|     3 |    240 s |   0 GB |

Each second is settled against the 16 GB ceiling:

| Phase | Reserved per s | Overage per s | Reserved GB·s | Overage GB·s |
| ----: | -------------: | ------------: | ------------: | -----------: |
|     1 |              8 |             0 |         4 800 |            0 |
|     2 |             16 |            14 |           960 |      **840** |
|     3 |              0 |             0 |             0 |            0 |

Bill for the interval:

| Charge                | GB-seconds | Rate      |
| --------------------- | ---------: | --------- |
| Reserved (commitment) |     14 400 | reserved  |
| Overage               |        840 | on-demand |

You pay the full 14 400 GB-seconds (`16 × 900`) for the reservation
regardless of consumption. The 60-second spike to 30 GB produced 840
GB-seconds of overage on top, calculated second by second.

## Three contrasting cases

**Usage stays below the ceiling.** Reserve 16 GB, run 4 GB throughout.
Reserved = 14 400 GB·s (commitment, paid in full). Overage = 0. The unused
capacity is the cost of optionality you gave up.

**Usage stays above the ceiling.** Reserve 16 GB, run 24 GB throughout.
Reserved = 14 400 GB·s. Overage = `8 × 900 = 7 200` GB·s.

**Usage averages below the ceiling but spikes above.** Reserve 16 GB, run
4 GB for 800 s then 25 GB for 100 s. Average is 6.8 GB — under
reservation. The 100 s above the ceiling still produces `9 × 100 = 900`
GB·s of overage. The ceiling is checked every second; averages are
irrelevant.

## Reservation and overage are independent

| Question                                              | Answer                                                            |
| ----------------------------------------------------- | ----------------------------------------------------------------- |
| Does the reservation amount affect the reserved bill? | Yes. Reserved bill = `reservedGb × 900` per interval, always.     |
| Does actual usage affect the reserved bill?           | No. The commitment is paid in full regardless.                    |
| Does the reservation amount affect the overage bill?  | Yes. Higher ceiling → less excess at each instant → less overage. |
| Does actual usage affect the overage bill?            | Yes. Sum of seconds where usage exceeded the ceiling.             |
| Do I get a credit for unused reserved capacity?       | No. Unused reserved is the cost of commitment.                    |

## Common confusions

> **"I'll only get overage when my total usage exceeds the GB-second budget."**

There is no GB-second budget. Every second is settled independently
against the ceiling.

> **"I averaged less than my reservation, so there can't be overage."**

Wrong if you ever exceeded the ceiling. Averaging is never applied.

> **"I didn't use my reservation; I shouldn't pay for it."**

You pay for it because reserving means committing unconditionally. The
reserved rate is lower precisely because of that.

> **"My reservation should auto-cover spikes."**

It doesn't. Spikes above the ceiling are overage. To cover spikes,
reserve a higher amount.

## Edge cases

| Case                                                      | Behavior                                                                                 |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| You hold a reservation but run nothing                    | Reserved billed in full. No overage.                                                     |
| You run workloads but have no reservation                 | Ceiling is at zero. Every second of usage is overage.                                    |
| You hold a reservation in one interval but run in another | No carryover. Allocation is per interval.                                                |
| Multiple sandboxes' memory sums above the ceiling         | Concurrent memory is summed before the ceiling is applied. No per-sandbox attribution.   |
| A sandbox crashes mid-interval                            | Memory drops as soon as the scale event closes; subsequent seconds see the lower number. |
| You try to reserve for an interval you're already in      | Rejected — reservations require a 30-minute minimum lead time.                           |

## Why per-second

A GB-second budget would let arbitrary spikes ride for free as long as
quiet time balanced them out. That's burstable behavior, not
committed-capacity behavior, and it creates incentives for adversarial
spike patterns.

Per-second settlement matches what the reservation actually is: at every
moment, the ceiling is what you committed to. Above it is overage. Below
it is covered.

## Where to go next

<CardGroup>
  <Card title="Reserving capacity" icon="lock" href="/reserved-capacity/reserving">
    How to commit to capacity in advance.
  </Card>

  <Card title="Reading the calendar" icon="calendar" href="/reserved-capacity/calendar">
    Plan capacity you'll actually use.
  </Card>
</CardGroup>


# Burst Sandboxes
Source: https://docs.opencomputer.dev/sandboxes/burst-sandboxes

Alpha lower-cost sandboxes that preserve disk across infrastructure restarts

<Warning>
  Burst Sandboxes are in alpha. They preserve filesystem state across
  infrastructure restarts, but running processes, in-memory state, terminal
  sessions, and open network connections may restart.
</Warning>

Burst Sandboxes are lower-cost OpenComputer sandboxes designed for workloads that can recover from a process restart. They expose the same OpenComputer API for commands, files, PTY, preview URLs, images, snapshots, scaling, and lifecycle operations.

If OpenComputer receives advance infrastructure interruption notice, the sandbox gets up to **25 seconds** to flush state before it restarts on healthy capacity. The sandbox's filesystem is preserved and made available after resume.

## Pricing

Burst Sandboxes are priced roughly **2x cheaper than on-demand sandboxes**.

## Create a Burst Sandbox

Set `burst: true` when creating the sandbox.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create({
    burst: true,
    memoryMB: 4096,
    timeout: 300,
  });

  const result = await sandbox.exec.run("echo hello from burst");
  console.log(result.stdout);

  await sandbox.kill();
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  async with await Sandbox.create(
      burst=True,
      memory_mb=4096,
      timeout=300,
  ) as sandbox:
      result = await sandbox.exec.run("echo hello from burst")
      print(result.stdout)
  ```

  ```bash HTTP theme={null}
  curl -X POST https://app.opencomputer.dev/api/sandboxes \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "burst": true,
      "memoryMB": 4096,
      "timeout": 300
    }'
  ```
</CodeGroup>

## What Happens on Interruption

Infrastructure capacity can be reclaimed or restarted by the cloud provider. When OpenComputer receives advance notice, it notifies the sandbox and starts the burst restart flow.

The sandbox receives these environment variables:

* `OPENSANDBOX_RESUMABLE=true`
* `OPENSANDBOX_RESUME_NOTICE_SECONDS=25`

During the notice window, write important state to disk. After resume, restart your process from durable state.

## Good Fits

Burst Sandboxes work well for cost-sensitive workloads that can restart from disk:

* Batch code execution where failed jobs can be requeued.
* CI-style checks, test runners, linters, and formatters.
* AI agent tool calls with durable task state outside the sandbox.
* Parallel exploration jobs where one attempt can restart.
* Development, previews, and experiments where cost matters more than availability.

## Poor Fits

Use on-demand sandboxes when process continuity is required:

* User-facing interactive sessions where a rare disconnect is still disruptive.
* Long-running stateful services that keep important state only in RAM.
* Databases, queues, or coordinators running inside the sandbox.
* Workloads with strict deadlines and no retry budget.
* Any task that cannot safely restart after a partial command failure.

## Alpha Limitations

During alpha, Burst Sandboxes have these restrictions:

| Capability          | Burst alpha behavior                                             |
| ------------------- | ---------------------------------------------------------------- |
| Process state       | May restart                                                      |
| Filesystem          | Preserved across burst restarts                                  |
| Notice window       | Up to 25 seconds when advance notice is available                |
| Sudden host failure | May resume without advance notice                                |
| Capacity            | Best effort; create may fail or wait when burst capacity is full |

## Reliability Pattern

For agent or batch systems, run your work from a small process wrapper and install a restart-notice hook.

1. Store task state on disk or outside the sandbox.
2. Write outputs to durable storage as the task progresses.
3. Install `/home/sandbox/.opencomputer/on-restart-notice` to flush or checkpoint before restart.
4. Make your startup command resume from the last durable state.
5. Use on-demand sandboxes for workloads with no process restart budget.

Example setup:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create({
    burst: true,
    timeout: 0,
  });

  await sandbox.exec.run("mkdir -p /home/sandbox/.opencomputer /home/sandbox/app");

  await sandbox.files.write(
    "/home/sandbox/.opencomputer/on-restart-notice",
    `#!/bin/sh
  set -eu
  echo "restart notice: ${1:-25}s" >> /home/sandbox/app/events.log
  touch /home/sandbox/app/restarting
  sync
  `,
  );

  await sandbox.exec.run("chmod +x /home/sandbox/.opencomputer/on-restart-notice");

  await sandbox.files.write(
    "/home/sandbox/app/worker.sh",
    `#!/bin/sh
  set -eu
  cd /home/sandbox/app
  if [ -f restarting ]; then
    echo "resumed after restart" >> events.log
    rm -f restarting
  else
    echo "started" >> events.log
  fi

  i=$(cat counter 2>/dev/null || echo 0)
  while true; do
    i=$((i + 1))
    echo "$i" > counter
    sync
    sleep 5
  done
  `,
  );

  await sandbox.exec.run("chmod +x /home/sandbox/app/worker.sh");
  await sandbox.exec.background("/home/sandbox/app/worker.sh", {
    maxRunAfterDisconnect: 0,
  });
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  sandbox = await Sandbox.create(burst=True, timeout=0)

  await sandbox.exec.run("mkdir -p /home/sandbox/.opencomputer /home/sandbox/app")

  await sandbox.files.write(
      "/home/sandbox/.opencomputer/on-restart-notice",
      """#!/bin/sh
  set -eu
  echo "restart notice: ${1:-25}s" >> /home/sandbox/app/events.log
  touch /home/sandbox/app/restarting
  sync
  """,
  )

  await sandbox.exec.run("chmod +x /home/sandbox/.opencomputer/on-restart-notice")

  await sandbox.files.write(
      "/home/sandbox/app/worker.sh",
      """#!/bin/sh
  set -eu
  cd /home/sandbox/app
  if [ -f restarting ]; then
    echo "resumed after restart" >> events.log
    rm -f restarting
  else
    echo "started" >> events.log
  fi

  i=$(cat counter 2>/dev/null || echo 0)
  while true; do
    i=$((i + 1))
    echo "$i" > counter
    sync
    sleep 5
  done
  """,
  )

  await sandbox.exec.run("chmod +x /home/sandbox/app/worker.sh")
  await sandbox.exec.background(
      "/home/sandbox/app/worker.sh",
      max_run_after_disconnect=0,
  )
  ```
</CodeGroup>

When OpenComputer receives notice, it runs the hook with the notice window in seconds. If the sandbox resumes on another worker, start your process again and read the state you wrote under `/home/sandbox/app`.

## Related

<CardGroup>
  <Card title="Elasticity" href="/sandboxes/elasticity">
    Resource tiers and autoscaling
  </Card>

  <Card title="Checkpoints" href="/sandboxes/checkpoints">
    Save and resume sandbox state
  </Card>
</CardGroup>


# Checkpoints
Source: https://docs.opencomputer.dev/sandboxes/checkpoints

Snapshot and fork sandbox state

A checkpoint is a named snapshot of a running sandbox. Fork new sandboxes from it to start from a known-good environment — like git branches for VMs.

## Checkpoint Types

OpenComputer supports two checkpoint modes:

| Type                 | Preserves                       | Use when                                                                                                                                                                                        |
| -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full checkpoint      | Disk, memory, and CPU state     | You want the fastest fork or restore path from an exact running VM state. This is best for templates, important milestones, and branches you expect to fork often.                              |
| Disk-only checkpoint | Rootfs and workspace disk state | You want lightweight, frequent snapshots of files, installed packages, and workspace changes. Forks boot from the saved disks, so they are cheaper to keep but may take longer to become ready. |

Full checkpoints are the default. Use `kind: "disk_only"` when creating autosaves or high-frequency checkpoints where disk state is enough.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();
  await sandbox.exec.run("npm install && npm run build", { cwd: "/app" });

  // Checkpoint after setup
  const cp = await sandbox.createCheckpoint("after-build");

  // Fork two independent sandboxes
  const a = await Sandbox.createFromCheckpoint(cp.id);
  const b = await Sandbox.createFromCheckpoint(cp.id);

  await a.exec.run("npm run test:unit", { cwd: "/app" });
  await b.exec.run("npm run test:e2e", { cwd: "/app" });
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  sandbox = await Sandbox.create()
  await sandbox.exec.run("npm install && npm run build", cwd="/app")

  cp = await sandbox.create_checkpoint("after-build")

  a = await Sandbox.create_from_checkpoint(cp["id"])
  b = await Sandbox.create_from_checkpoint(cp["id"])

  await a.exec.run("npm run test:unit", cwd="/app")
  await b.exec.run("npm run test:e2e", cwd="/app")
  ```
</CodeGroup>

## Checkpoints vs Hibernation

|                  | Checkpoint                                                    | Hibernation                           |
| ---------------- | ------------------------------------------------------------- | ------------------------------------- |
| Purpose          | Fork new sandboxes from saved state                           | Pause and resume the **same** sandbox |
| Original sandbox | Keeps running                                                 | Stopped                               |
| Can fork         | Yes — unlimited new sandboxes                                 | No                                    |
| Count            | Up to 10 per sandbox, with optional oldest-checkpoint cleanup | One hibernation state                 |
| Use case         | Parallel testing, branching experiments                       | Cost savings, idle timeout            |

## What Gets Preserved

Checkpoints capture the filesystem and installed state. Forked sandboxes start with a fresh boot from that disk state — the platform attempts warm restore when possible, but may fall back to a cold boot. Don't assume running processes carry over.

## API Reference

### Create Checkpoint

<CodeGroup>
  ```typescript TypeScript theme={null}
  const checkpoint = await sandbox.createCheckpoint("before-migration");
  // checkpoint.id, checkpoint.status ("processing" → "ready")
  ```

  ```python Python theme={null}
  checkpoint = await sandbox.create_checkpoint("before-migration")
  # checkpoint["id"], checkpoint["status"]
  ```

  ```bash CLI theme={null}
  oc cp create sb-abc123 --name before-migration
  ```
</CodeGroup>

Checkpoint name must be unique within the sandbox. Status transitions from `processing` to `ready` (or `failed`).

Each sandbox can have up to 10 full checkpoints and up to 100 disk-only checkpoints. To create a new checkpoint without failing at the limit, pass a retention policy that deletes the oldest eligible checkpoint of the same type first:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const checkpoint = await sandbox.createCheckpoint("autosave", {
    kind: "disk_only",
    retentionPolicy: { mode: "delete_oldest", maxCount: 100 },
  });
  ```

  ```python Python theme={null}
  checkpoint = await sandbox.create_checkpoint(
      "autosave",
      kind="disk_only",
      retention_policy={"mode": "delete_oldest", "maxCount": 100},
  )
  ```

  ```bash CLI theme={null}
  oc cp create sb-abc123 \
    --name autosave \
    --kind disk_only \
    --retention-policy delete_oldest \
    --retention-max-count 100
  ```
</CodeGroup>

Retention skips checkpoints that are public, have patches, or are still referenced by forked sandboxes. If no eligible checkpoint of the requested type can be deleted, creation fails instead of deleting protected state.

### List Checkpoints

<CodeGroup>
  ```typescript TypeScript theme={null}
  const checkpoints = await sandbox.listCheckpoints();
  ```

  ```python Python theme={null}
  checkpoints = await sandbox.list_checkpoints()
  ```
</CodeGroup>

### Fork from Checkpoint

Creates a new sandbox from a checkpoint:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const forked = await Sandbox.createFromCheckpoint(checkpointId, {
    timeout: 600,
  });
  ```

  ```python Python theme={null}
  forked = await Sandbox.create_from_checkpoint(checkpoint_id, timeout=600)
  ```
</CodeGroup>

### Restore Checkpoint

Revert a sandbox in-place. All changes since the checkpoint are lost:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.restoreCheckpoint(checkpointId);
  ```

  ```python Python theme={null}
  await sandbox.restore_checkpoint(checkpoint_id)
  ```
</CodeGroup>

### Delete Checkpoint

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.deleteCheckpoint(checkpointId);
  ```

  ```python Python theme={null}
  await sandbox.delete_checkpoint(checkpoint_id)
  ```
</CodeGroup>

## CheckpointInfo

| Field      | TypeScript  | Python      | Description                        |
| ---------- | ----------- | ----------- | ---------------------------------- |
| ID         | `id`        | `id`        | Checkpoint UUID                    |
| Sandbox ID | `sandboxId` | `sandboxID` | Source sandbox                     |
| Name       | `name`      | `name`      | Human-readable name                |
| Status     | `status`    | `status`    | `processing`, `ready`, or `failed` |
| Size       | `sizeBytes` | `sizeBytes` | Snapshot size in bytes             |
| Created    | `createdAt` | `createdAt` | Timestamp                          |

<Note>
  The TypeScript SDK returns typed `CheckpointInfo` objects. Python returns raw dictionaries with the HTTP API field names.
</Note>

## Example: Parallel Exploration

Try multiple approaches from the same starting point:

```typescript theme={null}
const sandbox = await Sandbox.create();
await sandbox.exec.run("git clone https://github.com/user/repo /app");
const cp = await sandbox.createCheckpoint("fresh-clone");

// Try three different migration strategies in parallel
const strategies = ["--strategy=ours", "--strategy=theirs", "--strategy=recursive"];
const results = await Promise.all(
  strategies.map(async (strategy) => {
    const fork = await Sandbox.createFromCheckpoint(cp.id);
    const result = await fork.exec.run(`cd /app && git merge origin/main ${strategy}`);
    await fork.kill();
    return { strategy, exitCode: result.exitCode };
  }),
);
```

<Tip>
  CLI equivalent: [`oc checkpoint`](/cli/checkpoint). Full reference: [TypeScript SDK](/reference/typescript-sdk#sandbox) · [Python SDK](/reference/python-sdk#sandbox) · [HTTP API](/reference/api#checkpoints).
</Tip>


# Elasticity
Source: https://docs.opencomputer.dev/sandboxes/elasticity

Dynamically scale sandbox memory and CPU — automatically, manually, or via the in-VM API

A sandbox's memory and CPU can be resized at runtime. The platform's recommended path is **Autoscaling** — opt the sandbox in once and we resize it for you based on observed memory pressure. Lower-level controls are also available if you want to drive sizing yourself or freeze it.

CPU scales proportionally to memory in all modes (1 vCPU per \~4 GB up to 16 GB / 4 vCPU). The permissible memory tiers are:

| Memory | vCPU            |
| ------ | --------------- |
| 1 GB   | 1 (best-effort) |
| 4 GB   | 1               |
| 8 GB   | 2               |
| 16 GB  | 4               |

If you want a sandbox to **stay at a fixed size**, see [Locking Resources](#locking-resources).

## Autoscaling

Opt a sandbox into the per-sandbox autoscaler and the platform resizes it for you based on observed memory pressure. Autoscale is **opt-in per sandbox** and **disabled by default**.

This is the recommended way to size a sandbox: turn it on once with bounds you're comfortable with, then leave it. Manual `scale` and the in-VM API are escape hatches for cases where the autoscaler isn't a good fit (e.g. you want a hard guarantee for a benchmark, or you're scripting your own logic).

### Enable

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.setAutoscale({
    enabled: true,
    minMemoryMB: 1024,
    maxMemoryMB: 16384,
  });
  ```

  ```python Python theme={null}
  await sandbox.set_autoscale(
      enabled=True,
      min_memory_mb=1024,
      max_memory_mb=16384,
  )
  ```

  ```bash CLI theme={null}
  oc sandbox autoscale sb-abc123 --on --min 1024 --max 16384
  ```

  ```bash HTTP theme={null}
  curl -sf -X PUT "$API/api/sandboxes/$SANDBOX_ID/autoscale" \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"enabled": true, "minMemoryMB": 1024, "maxMemoryMB": 16384}'
  ```
</CodeGroup>

`minMemoryMB` and `maxMemoryMB` must be values from the tier table above. The autoscaler keeps the sandbox between these bounds, in tier steps.

### Behavior

* **Scale up**: when the sandbox's 1-minute average memory utilization exceeds 75 %, jump to the next tier. 60-second cooldown between up-events.
* **Scale down**: when **all** of the 1-min, 5-min, and 15-min utilization averages stay below 25 %, drop one tier. 5-minute cooldown between down-events. Down requires at least 15 minutes of low-utilization data, so a brief idle pause won't shrink you.
* **Manual override**: any explicit `scale` call disables autoscale on that sandbox. Re-enable explicitly via `setAutoscale({ enabled: true, ... })` (or the equivalent in any SDK) if you want it back.

### Disable

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.setAutoscale({ enabled: false });
  ```

  ```python Python theme={null}
  await sandbox.set_autoscale(enabled=False)
  ```

  ```bash CLI theme={null}
  oc sandbox autoscale sb-abc123 --off
  ```

  ```bash HTTP theme={null}
  curl -sf -X PUT "$API/api/sandboxes/$SANDBOX_ID/autoscale" \
    -H "X-API-Key: $API_KEY" \
    -d '{"enabled": false}'
  ```
</CodeGroup>

### Inspect

<CodeGroup>
  ```typescript TypeScript theme={null}
  const cfg = await sandbox.getAutoscale();
  // { sandboxID: "sb-...", enabled: true, minMemoryMB: 1024, maxMemoryMB: 16384 }
  ```

  ```python Python theme={null}
  cfg = await sandbox.get_autoscale()
  # {"sandboxID": "sb-...", "enabled": True, "minMemoryMB": 1024, "maxMemoryMB": 16384}
  ```

  ```bash CLI theme={null}
  oc sandbox autoscale sb-abc123
  # Autoscale enabled for sb-abc123 (1024–16384 MB)
  ```

  ```bash HTTP theme={null}
  curl -sf "$API/api/sandboxes/$SANDBOX_ID/autoscale" -H "X-API-Key: $API_KEY"
  # {"sandboxID":"sb-...","enabled":true,"minMemoryMB":1024,"maxMemoryMB":16384}
  ```
</CodeGroup>

## Manual Scaling (Control Plane)

When you want to resize once — predictable size for a benchmark, a one-off scale-up before a known-heavy task, an operator response to an alert — call `scale` from your application or operator tooling:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.scale({ memoryMB: 4096 });
  ```

  ```python Python theme={null}
  await sandbox.scale(memory_mb=4096)
  ```

  ```bash CLI theme={null}
  oc sandbox scale sb-abc123 4096
  ```

  ```bash HTTP theme={null}
  curl -sf -X POST "$API/api/sandboxes/$SANDBOX_ID/scale" \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"memoryMB": 4096}'
  ```
</CodeGroup>

A manual scale **disables autoscale** on the sandbox — explicit user intent overrides the loop. Re-enable it later if you want size to track load again.

The endpoint can return:

* **403 `scaling_locked`** — the sandbox is locked. See [Locking Resources](#locking-resources).
* **409 `oom_floor`** — the requested size would force a guest OOM-kill because the current working set exceeds it. Free memory inside the guest, then retry.
* **402 Payment Required** — the requested size exceeds your plan cap.

## In-VM Scaling

Sandboxes expose an internal metadata API at `http://169.254.169.254` that lets code **inside** the VM scale itself. Useful for workload-aware scripts where the workload knows its own demand better than the platform autoscaler can infer (e.g. "scale up before this build, back down after").

<Note>
  This endpoint is only reachable from inside the sandbox. It is not exposed through the control plane API or SDKs.
</Note>

### Scale Memory

Send a `POST` to `/v1/scale` with the desired memory in MB. CPU is adjusted proportionally.

```bash theme={null}
curl -s -X POST http://169.254.169.254/v1/scale \
  -H "Content-Type: application/json" \
  -d '{"memoryMB": 4096}'
```

### Check Current Limits

```bash theme={null}
curl -s http://169.254.169.254/v1/limits
```

### Example: Rust Compilation

Rust builds are memory-hungry. You can alias `cargo` to scale up before compilation and scale back down after:

```bash theme={null}
alias cargo='_cargo_scaled'
_cargo_scaled() {
  # Scale up to 16GB / 4 vCPU before build
  curl -sf -X POST http://169.254.169.254/v1/scale \
    -H "Content-Type: application/json" -d '{"memoryMB": 16384}'

  # Run the actual cargo command
  command cargo "$@"
  local exit_code=$?

  # Scale back down to 4GB / 1 vCPU
  curl -sf -X POST http://169.254.169.254/v1/scale \
    -H "Content-Type: application/json" -d '{"memoryMB": 4096}'

  return $exit_code
}
```

Add this to your sandbox's `~/.bashrc` or inject it via `sandbox.exec.run` so every `cargo build`, `cargo test`, etc. automatically gets the extra resources.

### Example: Custom Scaling Loop

A simple shell script that monitors memory pressure and scales automatically. Useful when you want fine-grained control inside the sandbox itself; for the platform-managed equivalent see [Autoscaling](#autoscaling) above.

```bash theme={null}
#!/bin/sh
SCALE_API="http://169.254.169.254/v1/scale"
MIN_MB=1024
MAX_MB=8192
SCALE_UP_THRESHOLD=80
SCALE_DOWN_THRESHOLD=30
COOLDOWN=30
last_scale=0

while true; do
  mem_total=$(awk '/MemTotal/{print $2}' /proc/meminfo)
  mem_avail=$(awk '/MemAvailable/{print $2}' /proc/meminfo)
  usage_pct=$(( (mem_total - mem_avail) * 100 / mem_total ))
  total_mb=$((mem_total / 1024))
  now=$(date +%s)
  elapsed=$((now - last_scale))

  if [ $usage_pct -gt $SCALE_UP_THRESHOLD ] && [ $elapsed -gt $COOLDOWN ]; then
    new_mb=$((total_mb * 2))
    [ $new_mb -gt $MAX_MB ] && new_mb=$MAX_MB
    if [ $new_mb -gt $total_mb ]; then
      echo "usage=$usage_pct% -> scaling UP to ${new_mb}MB"
      curl -sf -X POST "$SCALE_API" \
        -H "Content-Type: application/json" \
        -d "{\"memoryMB\":$new_mb}"
      last_scale=$now
    fi
  elif [ $usage_pct -lt $SCALE_DOWN_THRESHOLD ] && [ $total_mb -gt $MIN_MB ] && [ $elapsed -gt $COOLDOWN ]; then
    new_mb=$((total_mb / 2))
    [ $new_mb -lt $MIN_MB ] && new_mb=$MIN_MB
    if [ $new_mb -lt $total_mb ]; then
      echo "usage=$usage_pct% -> scaling DOWN to ${new_mb}MB"
      curl -sf -X POST "$SCALE_API" \
        -H "Content-Type: application/json" \
        -d "{\"memoryMB\":$new_mb}"
      last_scale=$now
    fi
  fi

  sleep 5
done
```

## Locking Resources

If you want a sandbox to **stay at a fixed size** — predictable billing, a benchmark, a long-running pinned workload — lock it. Locking blocks both manual scaling and autoscaling on the sandbox.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.setScalingLock(true);
  ```

  ```python Python theme={null}
  await sandbox.set_scaling_lock(True)
  ```

  ```bash CLI theme={null}
  oc sandbox lock sb-abc123
  ```

  ```bash HTTP theme={null}
  curl -sf -X PUT "$API/api/sandboxes/$SANDBOX_ID/scaling-lock" \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"locked": true}'
  ```
</CodeGroup>

While locked:

* `scale` returns **403** `scaling_locked`
* `setAutoscale({ enabled: true })` returns **403** `scaling_locked`
* The autoscaler skips the sandbox

Locking automatically disables autoscale on the sandbox, so you have a single user-facing toggle. Unlocking does **not** auto-re-enable autoscale; turn it back on explicitly if you want it.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Unlock
  await sandbox.setScalingLock(false);

  // Inspect
  const lock = await sandbox.getScalingLock();
  // { sandboxID: "sb-...", locked: false }
  ```

  ```python Python theme={null}
  # Unlock
  await sandbox.set_scaling_lock(False)

  # Inspect
  lock = await sandbox.get_scaling_lock()
  # {"sandboxID": "sb-...", "locked": False}
  ```

  ```bash CLI theme={null}
  oc sandbox unlock sb-abc123
  oc sandbox lock-status sb-abc123
  ```

  ```bash HTTP theme={null}
  # Unlock
  curl -sf -X PUT "$API/api/sandboxes/$SANDBOX_ID/scaling-lock" \
    -H "X-API-Key: $API_KEY" \
    -d '{"locked": false}'

  # Inspect
  curl -sf "$API/api/sandboxes/$SANDBOX_ID/scaling-lock" -H "X-API-Key: $API_KEY"
  # {"sandboxID":"sb-...","locked":false}
  ```
</CodeGroup>


# Interactive Terminals
Source: https://docs.opencomputer.dev/sandboxes/interactive-terminals

Full PTY sessions inside sandboxes

A PTY session is a full interactive terminal inside the sandbox — like SSH but over WebSocket. Supports colors, cursor movement, and full-screen applications (vim, htop).

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();
  const pty = await sandbox.pty.create({
    onOutput: (data) => process.stdout.write(data),
  });

  pty.send("ls -la /app\n");
  // ... wait for output ...
  pty.close();
  await sandbox.kill();
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  sandbox = await Sandbox.create()
  pty = await sandbox.pty.create(
      on_output=lambda data: print(data.decode(), end=""),
  )

  pty.send("ls -la /app\n")
  output = await pty.recv()  # pull-based alternative
  pty.close()
  await sandbox.kill()
  ```
</CodeGroup>

## Creating a PTY

<CodeGroup>
  ```typescript TypeScript theme={null}
  const pty = await sandbox.pty.create({
    cols: 120,
    rows: 40,
    onOutput: (data) => process.stdout.write(data),
  });
  ```

  ```python Python theme={null}
  pty = await sandbox.pty.create(
      cols=120,
      rows=40,
      on_output=lambda data: print(data.decode(), end=""),
  )
  ```
</CodeGroup>

### Parameters

| Parameter  | Type     | Default | Description                                                 |
| ---------- | -------- | ------- | ----------------------------------------------------------- |
| `cols`     | number   | `80`    | Terminal columns                                            |
| `rows`     | number   | `24`    | Terminal rows                                               |
| `onOutput` | callback | —       | Called with output data (TS: `Uint8Array`, Python: `bytes`) |

## PtySession

| Member         | TypeScript              | Python              | Description                 |
| -------------- | ----------------------- | ------------------- | --------------------------- |
| Session ID     | `pty.sessionId`         | `pty.session_id`    | Unique session ID           |
| Send input     | `pty.send(data)`        | `pty.send(data)`    | Send keystrokes or commands |
| Receive output | via `onOutput` callback | `await pty.recv()`  | Get terminal output         |
| Close          | `pty.close()`           | `await pty.close()` | Close the PTY session       |

<Note>
  `recv()` is Python-only — a pull-based alternative to the `on_output` callback. Returns raw bytes.
</Note>

### Resize

PTY resize is available via the [HTTP API](/reference/api#pty) only (`POST /api/sandboxes/:id/pty/:sessionID/resize`). The SDKs do not expose a resize method — the CLI handles resize automatically for interactive sessions.

## CLI

The fastest way to get an interactive shell:

```bash theme={null}
oc shell sb-abc123
oc shell sb-abc123 --shell /bin/zsh
```

Terminal size is auto-detected and resize events are forwarded. See [`oc shell`](/cli/shell) for details.

<Tip>
  CLI equivalent: [`oc shell`](/cli/shell). Full reference: [TypeScript SDK](/reference/typescript-sdk#pty) · [Python SDK](/reference/python-sdk#pty) · [HTTP API](/reference/api#pty).
</Tip>


# Mounts
Source: https://docs.opencomputer.dev/sandboxes/mounts

Mount S3, GCS, Azure Blob, SFTP, WebDAV, and Dropbox into a sandbox via FUSE

<Note>
  **Preview:** the mounts API is new. Endpoints, request shape, and SDK
  method names may change before GA.
</Note>

Mount remote filesystems directly into your sandbox so your code reads and
writes them like local files — no SDK calls, no chunked downloads, no
boilerplate. Perfect for pulling in datasets, model weights, or a customer's
bucket without staging anything to disk first.

```typescript theme={null}
import { Sandbox } from "@opencomputer/sdk";

const sandbox = await Sandbox.create();

await sandbox.mounts.add({
  path: "/mnt/data",
  remote: "s3:my-bucket/datasets",
  backend: "s3",
  creds: {
    access_key_id: process.env.AWS_ACCESS_KEY_ID!,
    secret_access_key: process.env.AWS_SECRET_ACCESS_KEY!,
    region: "us-east-1",
  },
});

// Now anything in the sandbox can read s3://my-bucket/datasets as /mnt/data:
await sandbox.exec.run("ls /mnt/data");
await sandbox.exec.run("head /mnt/data/train.csv");
```

## How it works

Mounts use [`rclone mount`](https://rclone.org/commands/rclone_mount/) under the
hood — a single binary that speaks \~40 backends (S3, GCS, Azure Blob, SFTP,
WebDAV, Dropbox, and more). When you call `mounts.add()`:

1. The control plane templates an rclone config from your `backend` + `creds`.
2. The config is written to a tmpfs file inside the VM (mode `0600` — the
   sandbox user can't read it).
3. `rclone mount` is spawned as a background daemon, exposing the remote at
   the path you specified.
4. Every process in the sandbox can now read/write that path.

Credentials live only inside the VM's tmpfs for the lifetime of the mount.
The worker keeps no copy.

## Supported Backends

`backend` selects how `creds` are templated. The keys you pass map directly to
[rclone config fields](https://rclone.org/docs/) for that backend type.

| Backend     | Common keys                                                                            |
| ----------- | -------------------------------------------------------------------------------------- |
| `s3`        | `access_key_id`, `secret_access_key`, `region`, `provider` (default `AWS`), `endpoint` |
| `gcs`       | `service_account_credentials` (JSON string) or `service_account_file`                  |
| `azureblob` | `account`, `key` *or* `sas_url`                                                        |
| `sftp`      | `host`, `user`, `pass` or `key_file`, `port`                                           |
| `webdav`    | `url`, `vendor`, `user`, `pass`                                                        |
| `dropbox`   | `token`                                                                                |

For anything not in this list, or for advanced tuning, pass `rcloneConfig`
directly with a raw rclone config string — see [Custom Config](#custom-config)
below.

## Examples

### S3 (AWS)

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.mounts.add({
    path: "/mnt/data",
    remote: "s3:my-bucket",
    backend: "s3",
    creds: {
      access_key_id: process.env.AWS_ACCESS_KEY_ID!,
      secret_access_key: process.env.AWS_SECRET_ACCESS_KEY!,
      region: "us-east-1",
    },
  });
  ```

  ```python Python theme={null}
  await sandbox.mounts.add(
      path="/mnt/data",
      remote="s3:my-bucket",
      backend="s3",
      creds={
          "access_key_id": os.environ["AWS_ACCESS_KEY_ID"],
          "secret_access_key": os.environ["AWS_SECRET_ACCESS_KEY"],
          "region": "us-east-1",
      },
  )
  ```
</CodeGroup>

### S3-compatible (MinIO, R2, Tigris, etc.)

Override the `provider` and point at the endpoint:

```typescript theme={null}
await sandbox.mounts.add({
  path: "/mnt/r2",
  remote: "r2:my-bucket",
  backend: "s3",
  creds: {
    provider: "Cloudflare",
    access_key_id: "...",
    secret_access_key: "...",
    endpoint: "https://<accountid>.r2.cloudflarestorage.com",
    region: "auto",
  },
});
```

### Google Cloud Storage

<CodeGroup>
  ```typescript TypeScript theme={null}
  import fs from "node:fs";

  await sandbox.mounts.add({
    path: "/mnt/gcs",
    remote: "gcs:my-bucket",
    backend: "gcs",
    creds: {
      service_account_credentials: fs.readFileSync("./sa-key.json", "utf8"),
    },
  });
  ```

  ```python Python theme={null}
  with open("./sa-key.json") as f:
      sa_json = f.read()

  await sandbox.mounts.add(
      path="/mnt/gcs",
      remote="gcs:my-bucket",
      backend="gcs",
      creds={"service_account_credentials": sa_json},
  )
  ```
</CodeGroup>

### SFTP

```typescript theme={null}
await sandbox.mounts.add({
  path: "/mnt/remote",
  remote: "ssh:/home/data",
  backend: "sftp",
  creds: {
    host: "data.example.com",
    user: "agent",
    pass: process.env.SSH_PASSWORD!, // or key_file
  },
});
```

### Custom Config

For backends not in the typed list — or to tune things like `--vfs-cache-mode`
or `--dir-cache-time` — pass an rclone config string directly. The section
name in the config must match the part of `remote` before the colon.

```typescript theme={null}
await sandbox.mounts.add({
  path: "/mnt/box",
  remote: "box:Reports",
  rcloneConfig: `
[box]
type = box
token = {"access_token":"...","refresh_token":"...","expiry":"..."}
`.trim(),
  mountOptions: ["--dir-cache-time", "1m"],
});
```

## Read-only by default

Mounts are read-only unless you explicitly opt into read-write:

```typescript theme={null}
await sandbox.mounts.add({
  path: "/mnt/writable",
  remote: "s3:scratch",
  backend: "s3",
  creds: {...},
  readOnly: false,    // opts into RW; uses --vfs-cache-mode writes
});
```

<Warning>
  Object-store FUSE mounts have well-known write footguns — concurrent writers
  to the same key can produce surprising results, and small-write workloads
  amplify request counts (and your bill). Prefer object-store SDKs for
  write-heavy workloads; use mounts for read-heavy access and append-style
  artifacts.
</Warning>

## Listing and removing

```typescript theme={null}
const mounts = await sandbox.mounts.list();
// [{ path: "/mnt/data", remote: "s3:my-bucket", backend: "s3", readOnly: true }]

await sandbox.mounts.remove("/mnt/data");
```

## Hibernate behavior

Mounts survive hibernate/wake transparently. The VM snapshot captures the live
FUSE mount and the rclone daemon process; when the sandbox wakes, both are
restored as-is. No re-mount call needed — the mount is exactly where you left
it, with the same credentials, serving the same path.

```typescript theme={null}
await sandbox.mounts.add({ path: "/mnt/data", remote: "s3:my-bucket", backend: "s3", creds });

await sandbox.hibernate();
await sandbox.wake();

await sandbox.exec.run("ls /mnt/data");   // still works, no re-mount needed
```

When you want a mount gone, call `remove()` explicitly:

```typescript theme={null}
await sandbox.mounts.remove("/mnt/data");
```

That triggers an actual `fusermount3 -u` in the VM and drops the registry
entry. No magic teardown on hibernate.

### Stale credentials

If the credentials behind a mount get rotated or revoked while the sandbox is
hibernated, the in-VM rclone daemon — restored intact from the snapshot — is
still holding the *old* keys and will start hitting auth errors on the next
request. Fix: `mounts.remove(path)` then `mounts.add(...)` again with fresh
credentials.

## CLI

```bash theme={null}
oc mounts add sb-abc123 \
  --path /mnt/data \
  --remote s3:my-bucket \
  --backend s3 \
  --cred access_key_id=AKIA... \
  --cred secret_access_key=... \
  --cred region=us-east-1

oc mounts list sb-abc123
oc mounts rm sb-abc123 /mnt/data
```

For raw rclone configs, point `--config-file` at a local file:

```bash theme={null}
oc mounts add sb-abc123 --path /mnt/box --remote box:Reports --config-file ./rclone.conf
```

## Troubleshooting

**`sandbox image is missing rclone and/or fusermount3`** — the sandbox is
running on an older base image. Recreate the sandbox from the latest default
template, or build an image off the current `Dockerfile.default`.

**Mount succeeds but `ls` returns empty** — usually a creds /
permission issue on the remote side. SSH in (`oc shell`) and run
`rclone ls <remote>: --config /run/oc-agent/mounts/<id>.conf` to see the real
error. Or `ls -la` the mount point — FUSE errors surface as filesystem errors.

**`fuse: bad mount point ... permission denied`** — make sure the target path
isn't already a non-empty directory you don't own. The mount call creates the
path with `sandbox:sandbox` ownership; pre-existing roots can conflict.

<Tip>
  CLI equivalent: [`oc mounts`](/cli/mounts). Full reference:
  [TypeScript SDK](/reference/typescript-sdk#mounts) ·
  [Python SDK](/reference/python-sdk#mounts).
</Tip>

## Bring your own FUSE

<Note>
  Advanced — most users want the rclone path above. Reach for this only if you
  already have a FUSE-ready filesystem.
</Note>

Under the hood, `mounts.add()` picks a **driver** — the daemon that actually
establishes the FUSE mount. Everything above uses the default `rclone` driver.
If you already have a FUSE-ready filesystem (your own VFS, gcsfuse, s3fs, …) and
don't want rclone as a middle layer, use the **`command` driver**: you hand us
the daemon's argv and we run it as the sandbox user, inject your env/secrets,
wait for the mount to come live, and tear it down on `remove` — the same
lifecycle as an rclone mount.

```typescript theme={null}
await sandbox.mounts.add({
  path: "/mnt/data",
  driver: "command",
  command: ["my-vfs-fuse", "--bucket", "gs://my-bucket", "{mountpoint}"],
  secrets: { MY_VFS_TOKEN: process.env.MY_VFS_TOKEN! },
});
```

In Python this is a separate method, `mounts.add_command(...)`.

### The `{mountpoint}` token

`{mountpoint}` (or `{path}`) in your argv is replaced with `path` before the
command runs, so you don't repeat the path twice. The call above runs:

```
my-vfs-fuse --bucket gs://my-bucket /mnt/data
```

You can also hardcode the path — the token is just a convenience.

### env and secrets

* **`env`** — plain environment variables for the daemon. Recorded and returned
  by `list()`.
* **`secrets`** — credentials. Injected into the daemon's **process
  environment** (never the command line, so they don't leak via `ps`), never
  written to disk on the worker, and never returned by `list()`.

For daemons that need a credentials *file* (e.g. a service-account JSON), write
it first with the [filesystem API](/sandboxes/filesystem) and point the command
at it.

`readOnly` is **advisory** for this driver — your command must honor it (we also
export `OC_MOUNT_READONLY=1`). Unlike rclone, the platform can't enforce
read-only on an arbitrary daemon.

### Requirements

Your daemon must:

* be present in the sandbox — bake it into your image, or install/download it at
  runtime before mounting;
* mount at the mountpoint and keep running (a foreground daemon is fine — we
  background it; a self-daemonizing one works too);
* exit when its mount is unmounted (standard libfuse behavior) so `remove`
  cleans up.

The platform handles the rest: `/dev/fuse` access, creating the mountpoint, and
`-o allow_other` support (`user_allow_other` is set in `/etc/fuse.conf`). If the
mount doesn't come up within the timeout, the call fails with the **daemon's own
log tail** so you can see why (a bad flag, missing binary, auth error, etc.).

### Example: gcsfuse

[gcsfuse](https://cloud.google.com/storage/docs/gcsfuse-install) is Google's own
GCS-to-FUSE adapter. Install it in your image (or at runtime), write your
service-account key with the [filesystem API](/sandboxes/filesystem), and mount:

```typescript theme={null}
await sandbox.files.write("/run/gcp-sa.json", process.env.GCP_SA_JSON!);

await sandbox.mounts.add({
  path: "/mnt/bucket",
  driver: "command",
  command: [
    "gcsfuse", "--foreground", "--implicit-dirs",
    "-o", "allow_other",
    "--key-file", "/run/gcp-sa.json",
    "my-bucket", "{mountpoint}",
  ],
});

await sandbox.exec.run("ls /mnt/bucket");   // GCS objects, read like local files
```

For a **public** bucket, skip the key and pass `--anonymous-access`:

```typescript theme={null}
command: ["gcsfuse", "--foreground", "--anonymous-access", "-o", "allow_other",
          "gcp-public-data-landsat", "{mountpoint}"],
```

### Example: bindfs

A minimal local FUSE — mirror one directory onto another path:

```typescript theme={null}
await sandbox.exec.run("apt-get update && apt-get install -y bindfs");
await sandbox.mounts.add({
  path: "/mnt/mirror",
  driver: "command",
  command: ["bindfs", "-f", "-o", "allow_other", "/home/sandbox/data", "{mountpoint}"],
  readOnly: false,
});
// reads/writes under /mnt/mirror now pass through to /home/sandbox/data
```

### CLI

Pass `--command` once per argv element; `--env`/`--secret` take `key=value`:

```bash theme={null}
oc mounts add sb-abc123 \
  --path /mnt/mirror \
  --command bindfs --command -f --command -o --command allow_other \
  --command /home/sandbox/data --command '{mountpoint}' \
  --secret MY_VFS_TOKEN=...
```

If the mount doesn't come up, the error includes the **daemon's log tail** —
usually a missing binary, a bad flag, or an auth failure. Reproduce by hand with
`oc shell` and run the same command.


# Sandboxes
Source: https://docs.opencomputer.dev/sandboxes/overview

The compute primitive — full Linux VMs in the cloud

A sandbox is a full Linux virtual machine in the cloud. Each one has its own filesystem, network stack, and process space — completely isolated from other sandboxes via hardware-level virtualization. Think of it as a disposable laptop that starts in milliseconds and sleeps when idle.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();
  const result = await sandbox.exec.run("echo Hello from $(uname -a)");
  console.log(result.stdout);
  await sandbox.kill();
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  async with await Sandbox.create() as sandbox:
      result = await sandbox.exec.run("echo Hello from $(uname -a)")
      print(result.stdout)
  # sandbox is killed automatically on exit
  ```
</CodeGroup>

## Creating a Sandbox

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sandbox = await Sandbox.create({
    template: "my-custom-template",
    timeout: 600,
    cpuCount: 2,
    memoryMB: 1024,
    diskMB: 20480, // 20GB workspace (default; larger sizes in closed beta)
    envs: { NODE_ENV: "production" },
    metadata: { project: "my-app" },
  });
  ```

  ```python Python theme={null}
  sandbox = await Sandbox.create(
      template="my-custom-template",
      timeout=600,
      disk_mb=20480,  # 20GB workspace (default; larger sizes in closed beta)
      envs={"NODE_ENV": "production"},
      metadata={"project": "my-app"},
  )
  ```

  ```bash curl theme={null}
  curl -X POST https://app.opencomputer.dev/api/sandboxes \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "templateID": "my-custom-template",
      "timeout": 600,
      "cpuCount": 2,
      "memoryMB": 1024,
      "diskMB": 20480,
      "envs": {"NODE_ENV": "production"},
      "metadata": {"project": "my-app"}
    }'
  ```
</CodeGroup>

### Parameters

| Parameter     | Type   | Default  | Description                                                          |
| ------------- | ------ | -------- | -------------------------------------------------------------------- |
| `template`    | string | `"base"` | Template for the VM root filesystem                                  |
| `timeout`     | number | `300`    | Idle timeout in seconds (resets on every operation)                  |
| `envs`        | object | —        | Environment variables set inside the VM                              |
| `metadata`    | object | —        | Arbitrary key-value pairs stored with the sandbox                    |
| `cpuCount`    | number | —        | CPU cores. TypeScript and HTTP API only                              |
| `memoryMB`    | number | —        | Memory in MB. TypeScript and HTTP API only                           |
| `diskMB`      | number | `20480`  | Workspace disk size in MB (20GB–256GB). See disk sizing note below.  |
| `secretStore` | string | —        | Secret store name — resolves encrypted secrets and egress allowlist  |
| `image`       | Image  | —        | Declarative image definition (see [Templates](/sandboxes/templates)) |
| `snapshot`    | string | —        | Name of a pre-built snapshot for instant boot                        |
| `apiKey`      | string | —        | Defaults to `OPENCOMPUTER_API_KEY` env var                           |
| `apiUrl`      | string | —        | Defaults to `OPENCOMPUTER_API_URL` env var                           |

<Note>
  `cpuCount`, `memoryMB`, and `secretStore` are not available in the Python SDK. Use the [HTTP API](/reference/api#sandbox-lifecycle) directly for custom resources from Python.
</Note>

<Info>
  **Disk sizing (closed beta).** Every sandbox ships with a 20GB workspace on
  `/home/sandbox`. You can request up to 256GB via `diskMB`; any GB above the
  20GB baseline is metered per-second at a rate comparable to AWS EBS gp3.
  Larger disk limits are gated per-organization during the beta — [book a
  call](https://cal.com/team/digger/opencomputer-founder-chat) to have your
  org's ceiling raised.
</Info>

## Connecting to an Existing Sandbox

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sandbox = await Sandbox.connect("sb-abc123");
  ```

  ```python Python theme={null}
  sandbox = await Sandbox.connect("sb-abc123")
  ```
</CodeGroup>

## Lifecycle

Sandboxes have four states:

| Status       | Description                  |
| ------------ | ---------------------------- |
| `running`    | Active, accepting operations |
| `hibernated` | State saved, no compute cost |
| `stopped`    | Terminated                   |
| `error`      | Failed                       |

A rolling idle timeout (default 300s) resets on every operation — exec, file access, agent activity. When the timeout expires, the sandbox auto-hibernates if possible, otherwise stops.

## Hibernation & Wake

Hibernation snapshots the VM state and stops it — no cost while hibernated. Wake restores the sandbox, typically fast, with a cold-boot fallback if snapshot restore is unavailable.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.hibernate();
  // ... later ...
  await sandbox.wake({ timeout: 600 });
  ```

  ```http HTTP theme={null}
  POST /api/sandboxes/sb-abc123/hibernate

  POST /api/sandboxes/sb-abc123/wake
  Content-Type: application/json

  {"timeout": 600}
  ```
</CodeGroup>

<Note>
  `hibernate()` and `wake()` are available in the TypeScript SDK and [CLI](/cli/sandbox). Python SDK support is planned — use the [HTTP API](/reference/api#sandbox-lifecycle) directly.
</Note>

## Methods

| Method       | TypeScript                      | Python                           | Description                   |
| ------------ | ------------------------------- | -------------------------------- | ----------------------------- |
| Kill         | `await sandbox.kill()`          | `await sandbox.kill()`           | Terminate the sandbox         |
| Check status | `await sandbox.isRunning()`     | `await sandbox.is_running()`     | Returns boolean               |
| Set timeout  | `await sandbox.setTimeout(600)` | `await sandbox.set_timeout(600)` | Update idle timeout (seconds) |
| Hibernate    | `await sandbox.hibernate()`     | —                                | Snapshot and stop             |
| Wake         | `await sandbox.wake()`          | —                                | Resume from hibernation       |

## Properties

| Property   | TypeScript          | Python               | Description                                               |
| ---------- | ------------------- | -------------------- | --------------------------------------------------------- |
| Sandbox ID | `sandbox.sandboxId` | `sandbox.sandbox_id` | Unique identifier                                         |
| Status     | `sandbox.status`    | `sandbox.status`     | Current lifecycle state                                   |
| Domain     | `sandbox.domain`    | —                    | Preview URL domain for port 80                            |
| Agent      | `sandbox.agent`     | `sandbox.agent`      | [Agent sessions](/agent-sessions/overview)                |
| Exec       | `sandbox.exec`      | `sandbox.exec`       | [Command execution](/sandboxes/running-commands)          |
| Files      | `sandbox.files`     | `sandbox.files`      | [Filesystem](/sandboxes/working-with-files)               |
| PTY        | `sandbox.pty`       | `sandbox.pty`        | [Interactive terminals](/sandboxes/interactive-terminals) |

<Warning>
  `sandbox.commands` is a deprecated alias for `sandbox.exec`. Use `sandbox.exec` in all new code.
</Warning>

### Python Context Manager

The Python SDK supports `async with` for automatic cleanup:

```python theme={null}
async with await Sandbox.create() as sandbox:
    result = await sandbox.exec.run("echo hello")
    print(result.stdout)
# sandbox.kill() called automatically on exit
```

## Forking from Checkpoints

Create a sandbox from a saved checkpoint — useful for parallel testing from a known-good state:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const forked = await Sandbox.createFromCheckpoint("cp-abc123", { timeout: 600 });
  ```

  ```python Python theme={null}
  forked = await Sandbox.create_from_checkpoint("cp-abc123", timeout=600)
  ```
</CodeGroup>

See [Checkpoints](/sandboxes/checkpoints) for the full workflow.

## Related

<CardGroup>
  <Card title="Running Commands" href="/sandboxes/running-commands">
    Execute shell commands
  </Card>

  <Card title="Working with Files" href="/sandboxes/working-with-files">
    Read, write, and manage files
  </Card>

  <Card title="Interactive Terminals" href="/sandboxes/interactive-terminals">
    PTY sessions for interactive work
  </Card>

  <Card title="Checkpoints" href="/sandboxes/checkpoints">
    Snapshot, fork, and restore
  </Card>

  <Card title="Templates" href="/sandboxes/templates">
    Custom VM images
  </Card>

  <Card title="Preview URLs" href="/sandboxes/preview-urls">
    Expose ports to the internet
  </Card>
</CardGroup>

<Tip>
  CLI: [`oc sandbox`](/cli/sandbox) for lifecycle management. Full reference: [TypeScript SDK](/reference/typescript-sdk#sandbox) · [Python SDK](/reference/python-sdk#sandbox) · [HTTP API](/reference/api#sandbox-lifecycle).
</Tip>


# Patches
Source: https://docs.opencomputer.dev/sandboxes/patches

Scripts that run when forking from a checkpoint

A patch is a shell script attached to a checkpoint. Every time a sandbox is forked from that checkpoint, patches run automatically — inject configuration, update dependencies, or customize state without modifying the checkpoint itself.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  // Attach a patch to an existing checkpoint
  const result = await Sandbox.createCheckpointPatch(checkpointId, {
    script: 'echo "export API_KEY=$1" >> /root/.bashrc',
    description: "Inject API key at fork time",
  });
  console.log(result.patch.id, result.patch.sequence);

  // Fork — patch runs automatically
  const sandbox = await Sandbox.createFromCheckpoint(checkpointId);
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  result = await Sandbox.create_checkpoint_patch(
      checkpoint_id,
      script='echo "export API_KEY=$1" >> /root/.bashrc',
      description="Inject API key at fork time",
  )

  sandbox = await Sandbox.create_from_checkpoint(checkpoint_id)
  ```
</CodeGroup>

## API Reference

### Create Patch

Patch methods are **static** on the Sandbox class — they operate on checkpoints, not sandbox instances.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await Sandbox.createCheckpointPatch(checkpointId, {
    script: "apt-get update && apt-get install -y redis-server",
    description: "Install Redis",
  });
  // result.patch.id, result.patch.sequence
  ```

  ```python Python theme={null}
  result = await Sandbox.create_checkpoint_patch(
      checkpoint_id,
      script="apt-get update && apt-get install -y redis-server",
      description="Install Redis",
  )
  ```
</CodeGroup>

| Parameter      | Type   | Required | Description                    |
| -------------- | ------ | -------- | ------------------------------ |
| `checkpointId` | string | Yes      | Target checkpoint              |
| `script`       | string | Yes      | Bash script to execute on fork |
| `description`  | string | No       | Human-readable description     |

### List Patches

<CodeGroup>
  ```typescript TypeScript theme={null}
  const patches = await Sandbox.listCheckpointPatches(checkpointId);
  for (const p of patches) {
    console.log(p.sequence, p.description);
  }
  ```

  ```python Python theme={null}
  patches = await Sandbox.list_checkpoint_patches(checkpoint_id)
  ```
</CodeGroup>

### Delete Patch

<CodeGroup>
  ```typescript TypeScript theme={null}
  await Sandbox.deleteCheckpointPatch(checkpointId, patchId);
  ```

  ```python Python theme={null}
  await Sandbox.delete_checkpoint_patch(checkpoint_id, patch_id)
  ```
</CodeGroup>

## When Patches Run

Patches execute when a sandbox is **forked** from the checkpoint (via `Sandbox.createFromCheckpoint()` or `oc checkpoint spawn`). The strategy is always `on_wake`.

## Execution Order

Patches run in creation order (by `sequence` number). If you create three patches, they execute as patch 1 → patch 2 → patch 3 every time a sandbox is forked.

## PatchInfo

| Field          | Type   | Description                |
| -------------- | ------ | -------------------------- |
| `id`           | string | Patch UUID                 |
| `checkpointId` | string | Parent checkpoint          |
| `script`       | string | Bash script content        |
| `description`  | string | Human-readable description |
| `strategy`     | string | Always `"on_wake"`         |
| `sequence`     | number | Execution order            |
| `createdAt`    | string | Timestamp                  |

## Example: Environment-Specific Forks

Use patches to create different environments from one checkpoint:

```typescript theme={null}
// Base checkpoint has the app installed
const cpId = "cp-abc123";

// Patch for staging
await Sandbox.createCheckpointPatch(cpId, {
  script: `
    echo 'DATABASE_URL=postgres://staging-db/app' >> /app/.env
    echo 'LOG_LEVEL=debug' >> /app/.env
  `,
  description: "Staging environment config",
});

// Every fork now gets staging config
const staging = await Sandbox.createFromCheckpoint(cpId);
```

<Tip>
  CLI equivalent: [`oc patch`](/cli/patch). Full reference: [TypeScript SDK](/reference/typescript-sdk#sandbox) · [Python SDK](/reference/python-sdk#sandbox) · [HTTP API](/reference/api#checkpoint-patches).
</Tip>


# Preview URLs
Source: https://docs.opencomputer.dev/sandboxes/preview-urls

Expose sandbox ports to the internet

A preview URL is a public HTTPS endpoint that routes traffic to a port inside your sandbox. Start a web server and access it immediately via the sandbox's domain.

## Quick Access

Every sandbox has a built-in `domain` property that gives you instant access to port 80 without creating a preview URL explicitly:

```typescript theme={null}
const sandbox = await Sandbox.create();
await sandbox.exec.run("python3 -m http.server 80 &");

console.log(sandbox.domain);
// → sb-abc123-p80.workers.opencomputer.dev

// For other ports:
console.log(sandbox.getPreviewDomain(3000));
// → sb-abc123-p3000.workers.opencomputer.dev
```

The `domain` and `getPreviewDomain(port)` properties construct the preview hostname directly — no API call needed. Traffic is routed through the control plane proxy to the correct sandbox.

## Authentication

Preview URLs are public by default — anyone who can guess or learn the hostname can hit your sandbox's port. To require a bearer token in front of every request, opt in at create time with `previewAuth`.

When enabled, the control plane validates an `Authorization: Bearer <token>` (or `X-OC-Preview-Token: <token>`) header on every preview-URL request. Missing or wrong → 401. The check happens before traffic ever reaches your sandbox, so a brute-force run also can't wake a hibernated sandbox.

### Enable at create time

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sandbox = await Sandbox.create({
    previewAuth: { scheme: "bearer", token: "auto" },
  });

  // previewAuthToken is returned exactly once — store it somewhere durable.
  console.log(sandbox.previewAuthToken);
  // → "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
  ```

  ```python Python theme={null}
  sandbox = await Sandbox.create(
      preview_auth={"scheme": "bearer", "token": "auto"},
  )

  # preview_auth_token is returned exactly once — store it somewhere durable.
  print(sandbox.preview_auth_token)
  # → "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
  ```

  ```bash CLI theme={null}
  oc sandbox create --preview-auth
  # Created sandbox sb-abc123 (status: running)
  # Preview auth token (shown once): qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI
  ```
</CodeGroup>

`token: "auto"` (or omitting the field) tells the server to generate a 256-bit random token. To bring your own — useful when your gateway already has a secret it can share with both ends — pass an explicit string of at least 16 characters:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await Sandbox.create({
    previewAuth: { scheme: "bearer", token: process.env.GATEWAY_TOKEN! },
  });
  ```

  ```python Python theme={null}
  await Sandbox.create(
      preview_auth={"scheme": "bearer", "token": os.environ["GATEWAY_TOKEN"]},
  )
  ```

  ```bash CLI theme={null}
  oc sandbox create --preview-auth-token "$GATEWAY_TOKEN"
  ```
</CodeGroup>

### Making authenticated requests

Send the token on every request to the preview URL. Two header forms are accepted; pick whichever fits your client:

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" https://sb-abc123-p3000.workers.opencomputer.dev/
curl -H "X-OC-Preview-Token: $TOKEN"   https://sb-abc123-p3000.workers.opencomputer.dev/
```

The token gates **every port** on the sandbox — there's one token per sandbox, shared across all preview URLs you create on it.

### Rotation

When you need to roll the token — exposure, scheduled rotation, employee offboarding — call `rotate`. The old token stops working immediately and the new plaintext is returned exactly once:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const newToken = await sandbox.rotatePreviewAuthToken();
  // sandbox.previewAuthToken is also updated in place.
  ```

  ```python Python theme={null}
  new_token = await sandbox.rotate_preview_auth_token()
  # sandbox.preview_auth_token is also updated in place.
  ```

  ```bash CLI theme={null}
  oc preview rotate-auth sb-abc123
  # New preview auth token (shown once): <new token>
  ```
</CodeGroup>

There is no zero-downtime dual-token mode in v1 — roll out the new token to your caller before discarding the old one, or expect a brief window of 401s during the swap.

### What's stored and what's not

* Only the **SHA-256 hash** of the token is persisted. The server never sees the plaintext after the create or rotate response returns.
* There is no GET endpoint that returns the token. If you lose it, your only options are to rotate (mint a new one) or recreate the sandbox.
* A sandbox created **without** `previewAuth` has open preview URLs — exactly the same as before this feature existed. The feature is fully opt-in and backwards compatible.

### Where the check happens

Authentication is enforced by the cell's control plane immediately before the request is proxied to the worker. That means:

* **Hibernated sandboxes** stay hibernated on missing/wrong tokens — bad tokens can't burn wake capacity.
* **Self-hosted deployments** without the Cloudflare edge get the same gate for free — the check follows the sandbox, not the front door.

## Explicit Preview URLs

For tracking, custom domains, or auth configuration, use the preview URL API:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();
  await sandbox.exec.run("npx create-next-app@latest /app --yes", { timeout: 120 });
  sandbox.exec.start("npm run dev -- --port 3000", { cwd: "/app" });

  const preview = await sandbox.createPreviewURL({ port: 3000 });
  console.log(preview.hostname); // sb-abc123-p3000.workers.opencomputer.dev
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  sandbox = await Sandbox.create()
  await sandbox.exec.run("npx create-next-app@latest /app --yes", timeout=120)
  await sandbox.exec.start("npm run dev -- --port 3000", cwd="/app")

  preview = await sandbox.create_preview_url(port=3000)
  print(preview["hostname"])
  ```
</CodeGroup>

## API Reference

### Create Preview URL

<CodeGroup>
  ```typescript TypeScript theme={null}
  const preview = await sandbox.createPreviewURL({
    port: 3000,
    domain: "preview.myapp.com", // optional custom domain
  });
  ```

  ```python Python theme={null}
  preview = await sandbox.create_preview_url(
      port=3000,
      domain="preview.myapp.com",
  )
  ```
</CodeGroup>

| Parameter    | Type   | Required | Description                        |
| ------------ | ------ | -------- | ---------------------------------- |
| `port`       | number | Yes      | Container port to expose (1–65535) |
| `domain`     | string | No       | Custom domain                      |
| `authConfig` | object | No       | Authentication configuration       |

### List Preview URLs

<CodeGroup>
  ```typescript TypeScript theme={null}
  const previews = await sandbox.listPreviewURLs();
  for (const p of previews) {
    console.log(`Port ${p.port}: https://${p.hostname}`);
  }
  ```

  ```python Python theme={null}
  previews = await sandbox.list_preview_urls()
  for p in previews:
      print(f"Port {p['port']}: https://{p['hostname']}")
  ```
</CodeGroup>

### Delete Preview URL

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.deletePreviewURL(3000);
  ```

  ```python Python theme={null}
  await sandbox.delete_preview_url(3000)
  ```
</CodeGroup>

## Custom Domains

Pass a `domain` when creating a preview URL. SSL is provisioned automatically via Cloudflare. Custom domain verification is configured at the organization level through the dashboard — not through the SDK.

## Persistence

Preview URLs persist across hibernation and wake cycles. If you hibernate a sandbox and wake it later, the preview URLs are still active.

## Multiple Ports

Expose multiple services from the same sandbox:

```typescript theme={null}
// Frontend
await sandbox.createPreviewURL({ port: 3000 });
// API server
await sandbox.createPreviewURL({ port: 8080 });
// Database admin
await sandbox.createPreviewURL({ port: 5432 });
```

<Tip>
  CLI equivalent: [`oc preview`](/cli/preview). Full reference: [TypeScript SDK](/reference/typescript-sdk#sandbox) · [Python SDK](/reference/python-sdk#sandbox) · [HTTP API](/reference/api#preview-urls).
</Tip>


# Running Commands
Source: https://docs.opencomputer.dev/sandboxes/running-commands

Execute shell commands inside a sandbox

Three primitives, each tuned for a different shape of work:

| Use                                     | Primitive                            | Why                                                                                                                                                                                           |
| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One-shot command, wait for the result   | `exec.run()`                         | Simplest call. Returns once the command exits. Each call is isolated — no state carries between calls.                                                                                        |
| Long-running / streaming process        | `exec.start()` / `exec.background()` | Returns a session handle you can stream from, send stdin to, or reattach to later. Use for servers, builds, and any job you need to observe live.                                             |
| Multi-step workflow, state must persist | `exec.shell()`                       | Opens a long-lived `bash` whose `cwd`, exported env, and shell functions persist across `.run()` calls — the ergonomics of a terminal tab. Reconnectable via `exec.reattachShell(sessionId)`. |

Rules of thumb:

* Need a return value and don't care about streaming? → **`run()`**.
* Starting something that outlives the call (a server, a log tailer, a slow build)? → **`start()` / `background()`**.
* Doing a sequence of commands where one step's state (directory, env var, activated venv) affects the next? → **`shell()`**.

Under the hood `shell()` *is* an exec session — its `sessionId` shows up in `exec.list()` next to anything started via `start()`. The difference is purely how the SDK frames commands on top: a sentinel protocol per `.run()` call so you can treat one long-lived bash as many discrete calls.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();
  const result = await sandbox.exec.run("echo Hello, World!");
  console.log(result.stdout); // "Hello, World!\n"
  await sandbox.kill();
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  async with await Sandbox.create() as sandbox:
      result = await sandbox.exec.run("echo Hello, World!")
      print(result.stdout)  # "Hello, World!\n"
  ```
</CodeGroup>

## Quick Commands: `exec.run()`

Run a shell command and wait for the result. The command runs via `sh -c`, so pipes, redirects, and shell expansion work.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Working directory and environment variables
  const result = await sandbox.exec.run("npm run build", {
    cwd: "/app",
    env: { NODE_ENV: "production" },
    timeout: 120,
  });

  if (result.exitCode !== 0) {
    console.error("Build failed:", result.stderr);
  }
  ```

  ```python Python theme={null}
  result = await sandbox.exec.run(
      "npm run build",
      cwd="/app",
      env={"NODE_ENV": "production"},
      timeout=120,
  )

  if result.exit_code != 0:
      print("Build failed:", result.stderr)
  ```
</CodeGroup>

### Parameters

| Parameter | Type   | Default | Description                         |
| --------- | ------ | ------- | ----------------------------------- |
| `command` | string | —       | Shell command to run (**required**) |
| `timeout` | number | `60`    | Timeout in seconds                  |
| `env`     | object | —       | Environment variables               |
| `cwd`     | string | —       | Working directory                   |

### ProcessResult

| Field           | TypeScript | Python      | Type   |
| --------------- | ---------- | ----------- | ------ |
| Exit code       | `exitCode` | `exit_code` | number |
| Standard output | `stdout`   | `stdout`    | string |
| Standard error  | `stderr`   | `stderr`    | string |

## Async Commands: `exec.start()` / `exec.background()`

Start a command as an exec session for long-running processes or streaming output. Returns an `ExecSession` with callbacks for stdout, stderr, and exit. `exec.background()` is an alias for `exec.start()` — same options, same return type.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const session = await sandbox.exec.start("node server.js", {
    cwd: "/app",
    env: { PORT: "3000" },
    onStdout: (data) => process.stdout.write(data),
    onStderr: (data) => process.stderr.write(data),
    onExit: (code) => console.log("Server exited:", code),
    maxRunAfterDisconnect: 300, // keep running 5min after disconnect
  });

  // Send input
  session.sendStdin("some input\n");

  // Wait for completion (or kill)
  await session.kill();
  ```

  ```python Python theme={null}
  session = await sandbox.exec.start(
      "node", args=["server.js"],
      cwd="/app",
      env={"PORT": "3000"},
      on_stdout=lambda b: print(b.decode(), end=""),
      on_stderr=lambda b: print(b.decode(), end=""),
      on_exit=lambda code: print(f"Server exited: {code}"),
      max_run_after_disconnect=300,
  )

  # Send input
  await session.send_stdin("some input\n")

  # Wait for completion (or kill)
  await session.kill()
  ```
</CodeGroup>

### ExecStartOpts

| Parameter   | TypeScript              | Python                     | Description                              |
| ----------- | ----------------------- | -------------------------- | ---------------------------------------- |
| Arguments   | `args: string[]`        | `args: list[str]`          | Command arguments                        |
| Env         | `env: object`           | `env: dict`                | Environment variables                    |
| Working dir | `cwd: string`           | `cwd: str`                 | Working directory                        |
| Timeout     | `timeout: number`       | `timeout: int`             | Timeout in seconds                       |
| Keep-alive  | `maxRunAfterDisconnect` | `max_run_after_disconnect` | Seconds to keep running after disconnect |
| Stdout      | `onStdout`              | `on_stdout`                | Callback receiving raw bytes             |
| Stderr      | `onStderr`              | `on_stderr`                | Callback receiving raw bytes             |
| Exit        | `onExit`                | `on_exit`                  | Callback receiving the exit code         |

### ExecSession

| Member     | TypeScript              | Python                      | Description                                 |
| ---------- | ----------------------- | --------------------------- | ------------------------------------------- |
| Session ID | `sessionId`             | `session_id`                | Session identifier                          |
| Done       | `done: Promise<number>` | `done: asyncio.Future[int]` | Resolves with exit code                     |
| Send stdin | `sendStdin(data)`       | `send_stdin(data)`          | Write to the process                        |
| Kill       | `kill(signal?)`         | `kill(signal=9)`            | Kill the process                            |
| Detach     | `close()`               | `close()`                   | Close the WebSocket (process keeps running) |

## Stateful Shell: `exec.shell()`

Open a long-lived `bash` session whose state (`cwd`, exported env vars, shell functions) persists across `.run()` calls. Foreground-only: concurrent `.run()` rejects with `ShellBusyError`.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sh = await sandbox.exec.shell({ cwd: "/app" });

  await sh.run("npm install");
  await sh.run("export NODE_ENV=test");
  const r = await sh.run("npm test", {
    onStdout: (b) => process.stdout.write(b),
  });
  console.log(r.exitCode);

  await sh.close();
  ```

  ```python Python theme={null}
  sh = await sandbox.exec.shell(cwd="/app")

  await sh.run("npm install")
  await sh.run("export NODE_ENV=test")
  r = await sh.run("npm test", on_stdout=lambda b: print(b.decode(), end=""))
  print(r.exit_code)

  await sh.close()
  ```
</CodeGroup>

### Reattaching to an open shell

The shell is just an exec session, so its `sessionId` is stable across SDK invocations. Keep the id and revisit the same shell later — cwd, env, and shell functions are still there because the bash process never went anywhere.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sh = await sandbox.exec.shell();
  await sh.run("cd /srv && export DEPLOY=canary");
  const id = sh.sessionId; // persist this somewhere

  // ...later, possibly a different process...

  const sh2 = await sandbox.exec.reattachShell(id);
  const r = await sh2.run("pwd; echo $DEPLOY");
  // → "/srv\ncanary\n"
  ```

  ```python Python theme={null}
  sh = await sandbox.exec.shell()
  await sh.run("cd /srv && export DEPLOY=canary")
  sid = sh.session_id  # persist this somewhere

  # ...later, possibly a different process...

  sh2 = await sandbox.exec.reattach_shell(sid)
  r = await sh2.run("pwd; echo $DEPLOY")
  # → "/srv\ncanary\n"
  ```
</CodeGroup>

<Note>
  Reattach assumes the shell is idle (no in-flight `.run()` from another client). If two clients try to drive the same shell concurrently, their output will interleave — coordinate at the application level.
</Note>

### Terminal-tab semantics

Running `exit` (or `exit N`) inside `sh.run()` closes the shell — same as closing a terminal tab. The pending `.run()` rejects with `ShellClosedError` and any subsequent `.run()` on the same `Shell` also rejects. Start a fresh `shell()` if you need another one.

### Streaming output

Pass `onStdout`/`onStderr` to `sh.run()` and they fire as bytes arrive, before the promise resolves. Two caveats worth knowing:

* **bash builtin output is block-buffered.** `echo`, `printf`, and other builtins go through glibc `stdio`, which only flushes when the buffer fills (\~4 KB) or bash exits. If you want live output from a simple loop, use an external binary (`/bin/echo`) or a tool that flushes explicitly (`python -u`, `stdbuf -oL <cmd>`).
* **Upstream hops may coalesce small frames.** Chunks travel bash → agent → worker (gRPC) → WS → CDN → client. Any of those hops is allowed to combine small frames under light load, so a short command may arrive as one chunk even if its output was produced incrementally. Real workloads (builds, installs, servers) produce enough output that streaming is visible in practice.

See `sdks/typescript/examples/stream-demo.ts` / `sdks/python/examples/stream_demo.py` for a \~6-second apt-install simulation that prints per-chunk arrival timestamps — a good way to eyeball streaming behavior against your deployment.

<Note>
  Per-call `cwd`, `env`, and `timeout` are intentionally not supported in v1. Use inline shell syntax (`cd /x && cmd`, `FOO=bar cmd`) — the shell state carries across calls. Use `exec.background()` for fire-and-forget processes.
</Note>

## Managing Sessions

### List Sessions

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sessions = await sandbox.exec.list();
  for (const s of sessions) {
    console.log(s.sessionID, s.running ? "running" : `exited (${s.exitCode})`);
    console.log(`  command: ${s.command}, clients: ${s.attachedClients}`);
  }
  ```

  ```python Python theme={null}
  sessions = await sandbox.exec.list()
  for s in sessions:
      status = "running" if s.running else f"exited ({s.exit_code})"
      print(s.session_id, status, f"clients: {s.attached_clients}")
  ```
</CodeGroup>

### Attach to Running Session

Reconnect to a running exec session to resume streaming output:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const session = await sandbox.exec.attach(sessionId, {
    onStdout: (data) => process.stdout.write(data),
    onStderr: (data) => process.stderr.write(data),
    onExit: (code) => console.log("Exited:", code),
    onScrollbackEnd: () => console.log("--- live output ---"),
  });
  ```

  ```python Python theme={null}
  session = await sandbox.exec.attach(
      session_id,
      on_stdout=lambda b: print(b.decode(), end=""),
      on_stderr=lambda b: print(b.decode(), end=""),
      on_exit=lambda code: print(f"Exited: {code}"),
      on_scrollback_end=lambda: print("--- live output ---"),
  )
  ```
</CodeGroup>

On attach, the server replays the scrollback buffer (historical output), sends a scrollback-end marker, then streams live output.

### Kill a Session

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.exec.kill(sessionId);
  await sandbox.exec.kill(sessionId, 15); // SIGTERM
  ```

  ```python Python theme={null}
  await sandbox.exec.kill(session_id)
  await sandbox.exec.kill(session_id, signal=15)  # SIGTERM
  ```
</CodeGroup>

<Warning>
  `sandbox.commands` is a deprecated alias for `sandbox.exec`. Use `sandbox.exec` in all new code.
</Warning>

<Tip>
  CLI equivalent: [`oc exec`](/cli/exec). Full reference: [TypeScript SDK](/reference/typescript-sdk#exec) · [Python SDK](/reference/python-sdk#exec) · [HTTP API](/reference/api#commands-exec).
</Tip>


# Secrets
Source: https://docs.opencomputer.dev/sandboxes/secrets

Inject encrypted secrets into sandboxes without exposing them to the VM

Secrets let you pass API keys, tokens, and credentials into sandboxes without the real values ever entering the VM. They are encrypted at rest, sealed into opaque tokens at boot, and only revealed by a host-side proxy on outbound HTTPS requests.

## How it works

```mermaid theme={null}
sequenceDiagram
    participant You as Your Code
    participant S as Server
    participant W as Worker
    participant VM as Sandbox VM
    participant P as MITM Proxy
    participant API as External API

    You->>S: Store secret (sk-ant-...)
    Note over S: Encrypted with AES-256-GCM<br/>in Postgres

    You->>S: Create sandbox with secret store
    S->>S: Decrypt secrets
    S->>W: Send decrypted secrets

    W->>W: Seal into opaque tokens
    Note over W: sk-ant-... → osb_sealed_7f3a9c...

    W->>VM: Inject sealed env vars
    Note over VM: $API_KEY = osb_sealed_7f3a9c...<br/>Real secret NEVER in VM memory

    VM->>P: HTTPS request with sealed token
    P->>P: Replace sealed token with real secret
    P->>API: Request with real API key
    API-->>VM: Response
```

<Info>
  The real secret value only exists in the host-side proxy's memory — it is never written to disk, never sent to the VM, and never visible via `env` or `/proc` inside the sandbox.
</Info>

## Quick start

Create a secret store, add a secret, and launch a sandbox that uses it:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox, SecretStore } from '@opencomputer/sdk';

  // 1. Create a secret store with egress restrictions
  const store = await SecretStore.create({
    name: 'my-agent-secrets',
    egressAllowlist: ['api.anthropic.com'],
  });

  // 2. Add an encrypted secret
  await SecretStore.setSecret(store.id, 'ANTHROPIC_API_KEY', 'sk-ant-...');

  // 3. Create a sandbox — secrets are injected as sealed tokens
  const sandbox = await Sandbox.create({
    secretStore: 'my-agent-secrets',
    timeout: 600,
  });

  // Inside the VM, the env var is sealed — not the real key
  const result = await sandbox.exec.run('echo $ANTHROPIC_API_KEY');
  console.log(result.stdout); // "osb_sealed_7f3a9c..."

  // But HTTPS requests to allowed hosts get the real value via the proxy
  const apiResult = await sandbox.exec.run(`
    curl -s https://api.anthropic.com/v1/messages \\
      -H "x-api-key: $ANTHROPIC_API_KEY" \\
      -H "anthropic-version: 2023-06-01" \\
      -H "content-type: application/json" \\
      -d '{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
  `);
  console.log(apiResult.stdout); // 200 OK — real key was substituted by the proxy
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox, SecretStore

  # 1. Create a secret store with egress restrictions
  store = await SecretStore.create(
      name='my-agent-secrets',
      egress_allowlist=['api.anthropic.com'],
  )

  # 2. Add an encrypted secret
  await SecretStore.set_secret(store['id'], 'ANTHROPIC_API_KEY', 'sk-ant-...')

  # 3. Create a sandbox — secrets are injected as sealed tokens
  sandbox = await Sandbox.create(
      secret_store='my-agent-secrets',
      timeout=600,
  )

  # Inside the VM, the env var is sealed — not the real key
  result = await sandbox.exec.run('echo $ANTHROPIC_API_KEY')
  print(result.stdout)  # "osb_sealed_7f3a9c..."

  # But HTTPS requests to allowed hosts get the real value via the proxy
  api_result = await sandbox.exec.run(
      'curl -s https://api.anthropic.com/v1/messages '
      '-H "x-api-key: $ANTHROPIC_API_KEY" '
      '-H "anthropic-version: 2023-06-01" '
      '-H "content-type: application/json" '
      '-d \'{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}\''
  )
  print(api_result.stdout)  # 200 OK — real key was substituted by the proxy
  ```
</CodeGroup>

## Per-secret host restrictions

You can restrict individual secrets so they are only substituted in requests to specific hosts. This prevents a compromised dependency from exfiltrating secrets to an attacker-controlled server.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // This secret will only be substituted in requests to api.anthropic.com
  await SecretStore.setSecret(store.id, 'ANTHROPIC_API_KEY', 'sk-ant-...', {
    allowedHosts: ['api.anthropic.com'],
  });

  // This secret works on any allowed egress host
  await SecretStore.setSecret(store.id, 'GENERIC_TOKEN', 'tok-...');
  ```

  ```python Python theme={null}
  # This secret will only be substituted in requests to api.anthropic.com
  await SecretStore.set_secret(
      store['id'], 'ANTHROPIC_API_KEY', 'sk-ant-...',
      allowed_hosts=['api.anthropic.com'],
  )

  # This secret works on any allowed egress host
  await SecretStore.set_secret(store['id'], 'GENERIC_TOKEN', 'tok-...')
  ```
</CodeGroup>

## Egress allowlists

Secret stores can restrict which hosts the sandbox can make HTTPS requests to. Requests to hosts not on the list are blocked by the proxy.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const store = await SecretStore.create({
    name: 'restricted-store',
    egressAllowlist: ['api.anthropic.com', '*.openai.com'],
  });
  ```

  ```python Python theme={null}
  store = await SecretStore.create(
      name='restricted-store',
      egress_allowlist=['api.anthropic.com', '*.openai.com'],
  )
  ```
</CodeGroup>

Supports exact matches (`api.anthropic.com`) and wildcards (`*.openai.com`). An empty allowlist means all hosts are allowed.

## Managing secrets

<CodeGroup>
  ```typescript TypeScript theme={null}
  // List all secret stores
  const stores = await SecretStore.list();

  // List secrets in a store (metadata only — values are never returned)
  const entries = await SecretStore.listSecrets(store.id);

  // Delete a secret
  await SecretStore.deleteSecret(store.id, 'OLD_KEY');

  // Delete a store and all its secrets
  await SecretStore.delete(store.id);
  ```

  ```python Python theme={null}
  # List all secret stores
  stores = await SecretStore.list()

  # List secrets in a store (metadata only — values are never returned)
  entries = await SecretStore.list_secrets(store['id'])

  # Delete a secret
  await SecretStore.delete_secret(store['id'], 'OLD_KEY')

  # Delete a store and all its secrets
  await SecretStore.delete(store['id'])
  ```
</CodeGroup>

## Secrets with snapshots and checkpoints

You can attach a secret store when creating a sandbox from a snapshot or checkpoint, even if the original didn't have one. This is useful for baking a base environment (e.g., installed dependencies) and then giving each fork its own scoped credentials.

### Snapshot template with secrets

Pre-build a snapshot once, then create sandboxes from it with different credentials:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox, Snapshots, Image } from '@opencomputer/sdk/node';

  // Pre-build a reusable snapshot
  const snapshots = new Snapshots();
  await snapshots.create({
    name: 'data-pipeline',
    image: Image.base().aptInstall(['python3-pip']).pipInstall(['pandas']),
  });

  // Create sandboxes from the snapshot, each with their own credentials
  const worker1 = await Sandbox.create({
    snapshot: 'data-pipeline',
    secretStore: 'worker-1-keys',
  });
  const worker2 = await Sandbox.create({
    snapshot: 'data-pipeline',
    secretStore: 'worker-2-keys',
  });
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox, Snapshots, Image

  # Pre-build a reusable snapshot
  snapshots = Snapshots()
  await snapshots.create(
      name='data-pipeline',
      image=Image.base().apt_install(['python3-pip']).pip_install(['pandas']),
  )

  # Create sandboxes from the snapshot, each with their own credentials
  worker1 = await Sandbox.create(
      snapshot='data-pipeline',
      secret_store='worker-1-keys',
  )
  worker2 = await Sandbox.create(
      snapshot='data-pipeline',
      secret_store='worker-2-keys',
  )
  ```
</CodeGroup>

### Checkpoint fork with secrets

Layer a new secret store on top of an existing checkpoint's store:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Bake a base snapshot with git credentials
  const base = await Sandbox.create({ secretStore: 'git-creds' });
  await base.exec.run('git clone https://github.com/org/repo /app');
  const cp = await base.createCheckpoint('repo-cloned');

  // Fork with sandbox-specific API credentials (layered on top of git-creds)
  const worker1 = await Sandbox.createFromCheckpoint(cp.id, {
    secretStore: 'worker-1-keys',
  });
  const worker2 = await Sandbox.createFromCheckpoint(cp.id, {
    secretStore: 'worker-2-keys',
  });
  ```

  ```python Python theme={null}
  # Bake a base snapshot with git credentials
  base = await Sandbox.create(secret_store='git-creds')
  await base.exec.run('git clone https://github.com/org/repo /app')
  cp = await base.create_checkpoint('repo-cloned')

  # Fork with sandbox-specific API credentials (layered on top of git-creds)
  worker1 = await Sandbox.create_from_checkpoint(cp['id'],
      secret_store='worker-1-keys',
  )
  worker2 = await Sandbox.create_from_checkpoint(cp['id'],
      secret_store='worker-2-keys',
  )
  ```
</CodeGroup>

### Layering rules

When a checkpoint already has a secret store and you attach another at fork time, the stores are **merged**:

* **Secrets**: Both stores' secrets are available. On name collision, the fork's store wins.
* **Egress allowlists**: Aggregated (union of both stores' lists).
* **Per-secret host restrictions**: Follow the winning secret's store.

This means a base snapshot can provide broad credentials (e.g., git access) while each fork adds its own scoped credentials (e.g., limited API keys).

On a fork-of-fork, the checkpoint's merged result becomes the new base — there's no unbounded chain of stores to resolve.

## Security properties

| Property                  | Detail                                                               |
| ------------------------- | -------------------------------------------------------------------- |
| **Encryption at rest**    | AES-256-GCM in Postgres, key via `OPENSANDBOX_SECRET_ENCRYPTION_KEY` |
| **Never in VM memory**    | Env vars contain opaque `osb_sealed_*` tokens                        |
| **Host-side only**        | Real values exist only in the MITM proxy process on the worker host  |
| **Egress control**        | Allowlists restrict which domains receive secrets                    |
| **Per-secret scoping**    | Individual secrets can be locked to specific hosts                   |
| **Values never returned** | The API only returns secret names and metadata, never values         |

## Next steps

* [CLI reference](/cli/secrets) — manage secret stores and secrets from the command line
* [TypeScript SDK reference](/reference/typescript-sdk#secret-stores) — full API reference
* [Python SDK reference](/reference/python-sdk#secret-stores) — full API reference


# Signed URLs
Source: https://docs.opencomputer.dev/sandboxes/signed-urls

Generate pre-signed URLs for direct file uploads and downloads without API keys

Signed URLs let you upload or download files from a sandbox without exposing your API key. This is useful for:

* Letting browsers download files directly from a sandbox
* Sharing temporary download links with users
* Uploading files from untrusted clients (e.g. a frontend app)

## How It Works

1. Your backend generates a signed URL using your API key
2. The URL contains an HMAC signature and expiry timestamp
3. Anyone with the URL can upload/download — no API key needed
4. The URL expires automatically (default: 1 hour, max: 24 hours)

## Generating URLs

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();

  // Generate a download URL (default: 1 hour expiry)
  const downloadUrl = await sandbox.downloadUrl("/app/output.zip");

  // Generate an upload URL
  const uploadUrl = await sandbox.uploadUrl("/app/input.csv");

  // Custom expiry (in seconds)
  const shortUrl = await sandbox.downloadUrl("/app/output.zip", { expiresIn: 300 }); // 5 minutes
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  sandbox = await Sandbox.create()

  # Generate a download URL (default: 1 hour expiry)
  download_url = await sandbox.download_url("/app/output.zip")

  # Generate an upload URL
  upload_url = await sandbox.upload_url("/app/input.csv")

  # Custom expiry (in seconds)
  short_url = await sandbox.download_url("/app/output.zip", expires_in=300)  # 5 minutes
  ```
</CodeGroup>

## Downloading Files

Use the signed download URL with a plain GET request — no headers required:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const url = await sandbox.downloadUrl("/app/results.csv");

  // Fetch from browser or server — no API key needed
  const resp = await fetch(url);
  const data = await resp.arrayBuffer();
  ```

  ```python Python theme={null}
  import httpx

  url = await sandbox.download_url("/app/results.csv")

  async with httpx.AsyncClient() as http:
      resp = await http.get(url)
      data = resp.content
  ```

  ```bash cURL theme={null}
  # The URL is self-contained — just GET it
  curl -o results.csv "https://app.opencomputer.dev/api/sandboxes/sb-xxx/files/download?path=%2Fapp%2Fresults.csv&expires=1773906434&signature=abc123"
  ```
</CodeGroup>

## Uploading Files

Use the signed upload URL with a PUT request:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const url = await sandbox.uploadUrl("/app/data.csv");

  // Upload from browser or server — no API key needed
  await fetch(url, {
    method: "PUT",
    body: fileContent, // string, Uint8Array, Blob, etc.
  });
  ```

  ```python Python theme={null}
  import httpx

  url = await sandbox.upload_url("/app/data.csv")

  async with httpx.AsyncClient() as http:
      await http.put(url, content=file_bytes)
  ```

  ```bash cURL theme={null}
  curl -X PUT --data-binary @data.csv "https://app.opencomputer.dev/api/sandboxes/sb-xxx/files/upload?path=%2Fapp%2Fdata.csv&expires=1773906434&signature=abc123"
  ```
</CodeGroup>

## Large Files

Signed URLs support files of any size — the entire pipeline streams data in 256KB chunks without buffering. Files up to 200MB+ have been tested at \~20 MB/s throughput.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Upload a 100MB file via signed URL
  const data = new Uint8Array(100 * 1024 * 1024);
  const uploadUrl = await sandbox.uploadUrl("/data/model.bin");
  await fetch(uploadUrl, { method: "PUT", body: data });

  // Download it back
  const downloadUrl = await sandbox.downloadUrl("/data/model.bin");
  const resp = await fetch(downloadUrl);
  const downloaded = new Uint8Array(await resp.arrayBuffer());
  ```

  ```python Python theme={null}
  import httpx

  # Upload a 100MB file via signed URL
  data = b"\x00" * (100 * 1024 * 1024)
  upload_url = await sandbox.upload_url("/data/model.bin")
  async with httpx.AsyncClient(timeout=120.0) as http:
      await http.put(upload_url, content=data)

  # Download it back
  download_url = await sandbox.download_url("/data/model.bin")
  async with httpx.AsyncClient(timeout=120.0) as http:
      resp = await http.get(download_url)
      downloaded = resp.content
  ```
</CodeGroup>

## Security

* **Tamper-proof:** URLs are signed with HMAC-SHA256. Changing the path, sandbox ID, or expiry invalidates the signature.
* **Time-limited:** URLs expire after the specified duration (default 1 hour, max 24 hours). Expired URLs return `403`.
* **Operation-scoped:** Download URLs cannot be used for uploads and vice versa.
* **Path-scoped:** Each URL is bound to a specific file path. Changing the path in the URL returns `403`.

<Tip>
  Full reference: [TypeScript SDK](/reference/typescript-sdk#filesystem) · [Python SDK](/reference/python-sdk#filesystem) · [HTTP API](/api-reference/files/generate-download-url).
</Tip>


# Templates
Source: https://docs.opencomputer.dev/sandboxes/templates

Define sandbox environments programmatically with the Image builder and Snapshots

<Warning>Templates are an alpha, experimental feature. APIs, behavior, and manifest formats may change without notice.</Warning>

Templates provide a code-first approach to defining sandbox environments. Instead of configuring images manually, you define them programmatically using the SDK.

The system supports two workflows:

1. **Declarative images** — build images with varying dependencies *on demand* when creating sandboxes
2. **Pre-built snapshots** — create and register *ready-to-use* snapshots that can be shared across multiple sandboxes

## Declarative image building

Build images on-the-fly when creating sandboxes. Ideal for iterating quickly without creating separate snapshots.

Declarative images are **cached by content hash** — identical manifests produce the same image. Subsequent runs reuse the cached image instantly.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from '@opencomputer/sdk';
  import { Image } from '@opencomputer/sdk/node';

  // Define an image with packages, env vars, and files
  const image = Image.base()
    .aptInstall(['curl', 'jq'])
    .pipInstall(['requests', 'pandas'])
    .env({ PROJECT_ROOT: '/workspace' })
    .workdir('/workspace');

  // Create a sandbox — the image is built on first run, cached after
  const sandbox = await Sandbox.create({
    image,
    timeout: 300,
    onBuildLog: (log) => console.log(`build: ${log}`),
  });

  const result = await sandbox.exec.run('which curl');
  console.log(result.exitCode); // 0
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox, Image

  # Define an image with packages, env vars, and files
  image = (
      Image.base()
      .apt_install(["curl", "jq"])
      .pip_install(["requests", "pandas"])
      .env({"PROJECT_ROOT": "/workspace"})
      .workdir("/workspace")
  )

  # Create a sandbox — the image is built on first run, cached after
  sandbox = await Sandbox.create(
      image=image,
      timeout=300,
      on_build_log=lambda log: print(f"build: {log}"),
  )

  result = await sandbox.exec.run("which curl")
  print(result.exit_code)  # 0
  ```

  ```bash curl theme={null}
  curl -X POST https://app.opencomputer.dev/api/sandboxes \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "image": {
        "steps": [
          {"type": "apt_install", "packages": ["curl", "jq"]},
          {"type": "pip_install", "packages": ["requests", "pandas"]},
          {"type": "env", "vars": {"PROJECT_ROOT": "/workspace"}},
          {"type": "workdir", "path": "/workspace"}
        ]
      },
      "timeout": 300
    }'
  ```
</CodeGroup>

When you pass an `image` to `Sandbox.create()`, the server:

1. Hashes the image manifest to compute a **cache key**
2. If cached, creates the sandbox from the existing checkpoint instantly
3. If not cached, boots a build sandbox, executes each step, checkpoints the result, then creates your sandbox from it

### Build memory

Images build in a **4 GB** sandbox by default. If a build runs out of memory (heavy `apt`/`pip`/`npm`, compiling a large toolchain), raise the build-phase RAM with **`.builderMemory(mb)` / `.builder_memory(mb)`**.

This only affects the build. The resulting image is unchanged — you size the actual sandbox when you create it, via `memoryMB`:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // 8 GB to build…
  const image = Image.base()
    .aptInstall(['build-essential', 'cmake'])
    .runCommands('make -j')
    .builderMemory(8192);

  // …but the sandbox runs at whatever you ask for
  const sandbox = await Sandbox.create({ image, memoryMB: 4096 });
  ```

  ```python Python theme={null}
  image = (
      Image.base()
      .apt_install(["build-essential", "cmake"])
      .run_commands("make -j")
      .builder_memory(8192)
  )
  sandbox = await Sandbox.create(image=image)  # size via the HTTP API's memoryMB
  ```
</CodeGroup>

`builderMemory` doesn't change the cache key — it's a build resource, not image content.

## Creating pre-built snapshots

Create named snapshots that persist permanently and can be shared across sandboxes. Snapshots are visible in the dashboard and don't need to be rebuilt.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Image, Snapshots } from '@opencomputer/sdk/node';

  const snapshots = new Snapshots();

  // Define the image
  const image = Image.base()
    .aptInstall(['python3-pip'])
    .pipInstall(['pandas', 'numpy', 'scikit-learn'])
    .workdir('/workspace');

  // Create a named snapshot with build log streaming
  await snapshots.create({
    name: 'data-science',
    image,
    onBuildLogs: (log) => console.log(`build: ${log}`),
  });

  // Now create sandboxes from the snapshot — instant, no build step
  const sandbox = await Sandbox.create({ snapshot: 'data-science' });
  ```

  ```python Python theme={null}
  from opencomputer import Image, Snapshots

  snapshots = Snapshots()

  # Define the image
  image = (
      Image.base()
      .apt_install(["python3-pip"])
      .pip_install(["pandas", "numpy", "scikit-learn"])
      .workdir("/workspace")
  )

  # Create a named snapshot with build log streaming
  await snapshots.create(
      name="data-science",
      image=image,
      on_build_logs=lambda log: print(f"build: {log}"),
  )

  # Now create sandboxes from the snapshot — instant, no build step
  sandbox = await Sandbox.create(snapshot="data-science")
  ```

  ```bash curl theme={null}
  # Create a named snapshot
  curl -X POST https://app.opencomputer.dev/api/snapshots \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "data-science",
      "image": {
        "steps": [
          {"type": "apt_install", "packages": ["python3-pip"]},
          {"type": "pip_install", "packages": ["pandas", "numpy", "scikit-learn"]},
          {"type": "workdir", "path": "/workspace"}
        ]
      }
    }'

  # Create sandbox from the snapshot — instant
  curl -X POST https://app.opencomputer.dev/api/sandboxes \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"snapshot": "data-science"}'
  ```
</CodeGroup>

### Sizing a fork's memory

A sandbox created from a snapshot inherits the snapshot's memory by default. Pass `memoryMB` to give it more RAM — useful when one branch needs more headroom than the base.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Fork the snapshot with 8 GB instead of its captured size
  const sandbox = await Sandbox.create({ snapshot: 'data-science', memoryMB: 8192 });
  ```

  ```python Python theme={null}
  # Fork the snapshot with 8 GB instead of its captured size
  sandbox = await Sandbox.create(snapshot="data-science", memory_mb=8192)
  ```

  ```bash curl theme={null}
  curl -X POST https://app.opencomputer.dev/api/sandboxes \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"snapshot": "data-science", "memoryMB": 8192}'
  ```
</CodeGroup>

`memoryMB` is clamped to a valid range, and the response's `memoryMB` reports the effective value:

* **Floor — the snapshot's own memory.** A smaller request is ignored; a fork can't start smaller than the snapshot it restores. A 4 GB snapshot forked with `memoryMB: 1024` still boots at \~4 GB.
* **Ceiling.** Larger requests are capped to the maximum platform tier.

The same `memoryMB` field works when [forking from a checkpoint](/api-reference/checkpoints/fork).

### Managing snapshots

<CodeGroup>
  ```typescript TypeScript theme={null}
  const snapshots = new Snapshots();

  // List all snapshots
  const list = await snapshots.list();
  for (const s of list) {
    console.log(`${s.name} — ${s.status}`);
  }

  // Get a specific snapshot
  const snapshot = await snapshots.get('data-science');
  console.log(snapshot.status); // "ready"

  // Delete a snapshot
  await snapshots.delete('data-science');
  ```

  ```python Python theme={null}
  snapshots = Snapshots()

  # List all snapshots
  snapshot_list = await snapshots.list()
  for s in snapshot_list:
      print(f"{s['name']} — {s['status']}")

  # Get a specific snapshot
  snapshot = await snapshots.get("data-science")
  print(snapshot["status"])  # "ready"

  # Delete a snapshot
  await snapshots.delete("data-science")
  ```

  ```bash curl theme={null}
  # List all snapshots
  curl https://app.opencomputer.dev/api/snapshots \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY"

  # Get a specific snapshot
  curl https://app.opencomputer.dev/api/snapshots/data-science \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY"

  # Delete a snapshot
  curl -X DELETE https://app.opencomputer.dev/api/snapshots/data-science \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY"
  ```
</CodeGroup>

***

## Default template

Sandboxes use the default template when no image or snapshot is specified. It includes:

* **Ubuntu 22.04**
* **Python 3** with pip, venv, setuptools
* **Node.js 20 LTS** with npm
* **Build tools:** build-essential, cmake, pkg-config
* **CLI tools:** git, git-lfs, curl, wget, jq, rsync, htop, tree
* **Editors:** nano, vim-tiny
* **Database:** sqlite3
* **Networking:** openssh-client, iproute2, net-tools, dnsutils
* **Claude Agent SDK** and claude-code (pre-installed for agent sessions)

***

## Image configuration

The `Image` class provides a fluent, immutable API for defining sandbox environments. Each method returns a **new** `Image` instance — the original is never modified.

| Method                                                            | Description                                                                  |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `Image.base()`                                                    | Start from the default OpenSandbox environment                               |
| `.aptInstall(packages)` / `.apt_install(packages)`                | Install system packages via apt-get                                          |
| `.pipInstall(packages)` / `.pip_install(packages)`                | Install Python packages via pip                                              |
| `.runCommands(...cmds)` / `.run_commands(*cmds)`                  | Run shell commands during build                                              |
| `.env(vars)`                                                      | Set environment variables (written to `/etc/environment`)                    |
| `.workdir(path)`                                                  | Set default working directory                                                |
| `.addFile(path, content)` / `.add_file(path, content)`            | Embed a file with inline content                                             |
| `.addLocalFile(local, remote)` / `.add_local_file(local, remote)` | Read a local file into the image                                             |
| `.addLocalDir(local, remote)` / `.add_local_dir(local, remote)`   | Read a local directory into the image                                        |
| `.builderMemory(mb)` / `.builder_memory(mb)`                      | RAM for the build phase (default 4 GB; doesn't affect the resulting sandbox) |
| `.toJSON()` / `.to_dict()`                                        | Return the image manifest                                                    |
| `.cacheKey()` / `.cache_key()`                                    | Compute SHA-256 content hash                                                 |

## SnapshotInfo

| Field          | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| `id`           | string | Unique snapshot identifier             |
| `name`         | string | Snapshot name                          |
| `status`       | string | `"building"`, `"ready"`, or `"failed"` |
| `contentHash`  | string | SHA-256 hash of the image manifest     |
| `checkpointId` | string | Linked checkpoint ID                   |
| `manifest`     | object | The declarative image manifest         |
| `createdAt`    | string | ISO 8601 creation timestamp            |
| `lastUsedAt`   | string | ISO 8601 last usage timestamp          |

<Tip>
  Full SDK reference: [TypeScript SDK](/sdks/typescript/templates) · [Python SDK](/sdks/python/templates) · [HTTP API](/reference/api#snapshots).
</Tip>


# Timeout & Hibernation
Source: https://docs.opencomputer.dev/sandboxes/timeout

Control how long a sandbox stays alive when idle

Sandboxes have a rolling **idle timeout** that determines when they auto-hibernate to save cost. The timeout is what you'd expect from a "laptop lid" — the sandbox sleeps when nothing is happening and wakes the moment you talk to it again.

## Default: persistent (no auto-hibernate)

By default the timeout is `0`, which means **never auto-hibernate**. The sandbox stays running until you explicitly kill or hibernate it.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  // No `timeout` — sandbox is persistent (stays alive until killed).
  const sandbox = await Sandbox.create();
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  # No `timeout` — sandbox is persistent (stays alive until killed).
  sandbox = await Sandbox.create()
  ```

  ```bash CLI theme={null}
  # --timeout defaults to 0 (never hibernate).
  oc sandbox create
  ```
</CodeGroup>

<Note>
  Persistent sandboxes keep accruing compute cost for as long as they're running. If you only need the sandbox to respond to occasional requests, set a timeout so it hibernates between them — see below.
</Note>

## Setting a timeout

Pass `timeout` in seconds to have the sandbox auto-hibernate after N seconds of **idle** time. The timer resets on every operation — exec, file access, agent activity — so a busy sandbox never hits the timeout.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Auto-hibernate after 5 minutes of inactivity.
  const sandbox = await Sandbox.create({ timeout: 300 });
  ```

  ```python Python theme={null}
  # Auto-hibernate after 5 minutes of inactivity.
  sandbox = await Sandbox.create(timeout=300)
  ```

  ```bash CLI theme={null}
  oc sandbox create --timeout 300
  ```
</CodeGroup>

### Update on a running sandbox

You can change the timeout at any time:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.setTimeout(600); // 10 minutes
  await sandbox.setTimeout(0);   // make it persistent
  ```

  ```python Python theme={null}
  await sandbox.set_timeout(600)
  await sandbox.set_timeout(0)
  ```

  ```bash CLI theme={null}
  oc sandbox set-timeout sb-abc123 600
  oc sandbox set-timeout sb-abc123 0
  ```
</CodeGroup>

## What happens when the timeout expires

When an idle sandbox hits its timeout, the platform:

1. Snapshots the VM state (memory + disk) and stops the VM — no compute cost while hibernated.
2. Marks the sandbox `hibernated`. Its ID, files, and configuration are preserved.

You don't pay for CPU/memory while a sandbox is hibernated — only for the stored snapshot.

## Waking up

**Any operation from the SDK automatically wakes a hibernated sandbox.** You don't need to call `wake()` yourself — calling `sandbox.exec.run(...)`, reading a file, or any other operation transparently restores the VM and then performs the requested action.

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Earlier: sandbox auto-hibernated after 5 minutes of idleness.
  // Now, hours later — this call just works. The SDK wakes it first.
  const result = await sandbox.exec.run("echo hello");
  ```

  ```python Python theme={null}
  # Same behavior in Python.
  result = await sandbox.exec.run("echo hello")
  ```
</CodeGroup>

Wake is typically sub-second thanks to snapshot restore, with a cold-boot fallback if the snapshot isn't available. Once woken, the idle timer restarts with the sandbox's configured timeout.

<Note>
  You can still call `sandbox.wake()` explicitly if you want to pre-warm a sandbox before routing user traffic to it.
</Note>

## Choosing a timeout

| Use case                                          | Suggested `timeout`          |
| ------------------------------------------------- | ---------------------------- |
| Always-on agent / bot that must respond instantly | `0` (persistent)             |
| Interactive dev sandbox, keep for the session     | `600`–`3600` (10 min – 1 hr) |
| Short-lived batch or test run                     | `60`–`300` (1–5 min)         |
| One-off exec — kill it yourself when done         | `0` + explicit `kill()`      |

The tradeoff is latency vs cost: a lower timeout saves money but adds wake latency on the next request after idleness.

## See also

* [Lifecycle overview](/sandboxes/overview#lifecycle) — all sandbox states
* [Set timeout API](/api-reference/sandboxes/set-timeout)
* [Hibernate API](/api-reference/sandboxes/hibernate) / [Wake API](/api-reference/sandboxes/wake)


# Usage Monitoring
Source: https://docs.opencomputer.dev/sandboxes/usage

Inspect a sandbox's memory allocation and actual utilization over time

[`GET /api/sandboxes/:id/usage`](/api-reference/usage/get-sandbox-usage)
returns a per-minute time series of a sandbox's memory — both the
tier you provisioned and what the process actually consumed —
together with envelope totals. Use it to answer "am I over-paying for
this sandbox" or "when did memory spike?" For cross-sandbox
leaderboards (rank by usage, group by tag) see the aggregator at
[`GET /api/usage`](/api-reference/usage/get-usage) instead.

<Note>
  **Preview:** Usage and tag APIs are new. Endpoints, response fields,
  and SDK method names may change before GA; temporary inaccuracies or
  rough edges are possible while the surface settles.
</Note>

## Example

Allocated tier as a step line (it changes only on resize), measured
usage as a smooth curve. The gap between them is paid-for headroom.

<svg aria-label="Example chart: a sandbox's allocated and used memory over 24 hours, showing a mid-day resize event, a load-test peak, and a brief stop">
  <g>
    <line />

    <line />

    <line />

    <line />

    <line />

    <line />
  </g>

  <g>
    <text>2500</text>
    <text>2000</text>
    <text>1500</text>
    <text>1000</text>
    <text>500</text>
    <text>0</text>
  </g>

  <g>
    <text>00:00</text>
    <text>04:00</text>
    <text>08:00</text>
    <text>12:00</text>
    <text>16:00</text>
    <text>20:00</text>
    <text>24:00</text>
  </g>

  <text>Memory (MiB)</text>

  <path />

  <path />

  <path />

  <g>
    <circle />

    <line />

    <text>Resize 1 → 2 GiB</text>
  </g>

  <g>
    <circle />

    <line />

    <text>Load-test peak (1500 MiB)</text>
  </g>

  <g>
    <line />

    <text>Stopped briefly</text>
  </g>

  <g>
    <line />

    <text>allocatedMemoryMb</text>

    <line />

    <text>usedMemoryMbAvg</text>
  </g>
</svg>

Everything on the chart — the resize step, the peak, the brief gap —
falls out of `points[]` directly: `allocatedMemoryMb` is the step,
`usedMemoryMbPeak` finds the peak, `uptimeSeconds: 0` marks downtime.

## Request

```http theme={null}
GET /api/sandboxes/sb-abc/usage?from=2026-05-27T00:00:00Z&to=2026-05-27T01:00:00Z
```

Path carries the sandbox ID. `from` and `to` are optional and accept
ISO dates (`YYYY-MM-DD`, interpreted as UTC midnight) or RFC3339
timestamps; omit them for the last hour. Max window is **30 days**.
Full param reference: the
[API page](/api-reference/usage/get-sandbox-usage).

## Response

```json theme={null}
{
  "sandboxId": "sb-abc",
  "alias": "my-agent",
  "from": "2026-05-27T00:00:00Z",
  "to":   "2026-05-27T01:00:00Z",
  "totals": {
    "memoryAllocatedGbSeconds": 3600,
    "memoryUsedGbSeconds":      2180,
    "uptimeSeconds":            3600,
    "memoryAllocatedPeakMb":    1024,
    "memoryUsedPeakMb":          742
  },
  "points": [
    { "ts": "2026-05-27T00:00:00Z", "memoryAllocatedGbSeconds": 60, "memoryUsedGbSeconds": 35.86, "uptimeSeconds": 60, "allocatedMemoryMb": 1024, "usedMemoryMbAvg": 612, "usedMemoryMbPeak": 720 },
    { "ts": "2026-05-27T00:01:00Z", "memoryAllocatedGbSeconds": 60, "memoryUsedGbSeconds": 40.02, "uptimeSeconds": 60, "allocatedMemoryMb": 1024, "usedMemoryMbAvg": 683, "usedMemoryMbPeak": 742 }
  ]
}
```

`totals` is the server-side sum of `points[]` — summing any
additive field across the array reproduces the matching `totals.*`
exactly. Full field semantics live in the
[API reference](/api-reference/usage/get-sandbox-usage).

## Allocated vs used

* **`memoryAllocatedGbSeconds`** — the tier you provisioned, integrated
  over time. Same physical quantity the bill is computed from.
  Resize mid-window shows up as a time-weighted blend in the affected
  bucket.
* **`memoryUsedGbSeconds`** — measured resident memory, sampled every
  60s and integrated. The headroom signal: low ratio of used over
  allocated means you're over-provisioned.

Both are in **GiB-seconds** (binary, 2<sup>30</sup> bytes/GiB), so
`used / allocated` gives a clean utilization fraction.

## Calling it

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Usage } from "@opencomputer/sdk";

  const usage = new Usage(
    "https://app.opencomputer.dev",
    process.env.OPENCOMPUTER_API_KEY!,
  );

  // Default window = last 1 hour. Pass `from`/`to` for up to 30 days.
  const r = await usage.forSandbox("sb-abc");
  const pct = 100 * r.totals.memoryUsedGbSeconds / r.totals.memoryAllocatedGbSeconds;
  console.log(`${pct.toFixed(0)}% utilization`);

  for (const p of r.points) {
    // p.ts, p.usedMemoryMbAvg, p.allocatedMemoryMb — ready to chart
  }
  ```

  ```bash cURL theme={null}
  curl -s "$OPENCOMPUTER_API_URL/api/sandboxes/sb-abc/usage?from=2026-05-27T00:00:00Z&to=2026-05-27T01:00:00Z" \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" | jq '.totals'
  ```
</CodeGroup>

Full TypeScript SDK reference: [Usage & Tags](/reference/typescript-sdk/usage).

## Bucket semantics

* Buckets are **1 minute, UTC-aligned**; boundary buckets clamp to
  the original window so a mid-minute `from` doesn't over-report.
* Minutes where the sandbox isn't running emit zero-points — gaps
  read as continuous flat zero on a chart, not nulls.
* If a measurement is missed, `uptimeSeconds` still reads 60 (the
  sandbox was running) but `usedMemoryMbAvg` reads 0 — visible as a
  brief dip under an otherwise continuous allocated line.
* The first non-zero `usedMemoryMbAvg` for a freshly-created sandbox
  appears a few minutes in. Workloads that finish faster than that
  may not register any measured usage even though they ran.
* Window max is **30 days**.


# Webhooks
Source: https://docs.opencomputer.dev/sandboxes/webhooks

Subscribe to sandbox lifecycle events — signed, retried, and redeliverable

<Note>**Preview** — sandbox webhooks are newly available and still evolving; the shape may change. We'd love your feedback.</Note>

Register a **destination** and OpenComputer delivers a sandbox's lifecycle events to it as a small, signed **delivery envelope** — signed, retried, and redeliverable. Use it to react when a sandbox boots, hibernates, stops, or scales, without polling.

The envelope is camelCase, with top-level routing fields and the full event nested under `event`:

```json theme={null}
{
  "type": "sandbox.stopped",
  "sandboxId": "sb-3f9a…",
  "eventId": "sb-3f9a…:3:142",
  "event": {
    "id": "sb-3f9a…:3:142", "ts": "2026-06-24T12:00:00Z",
    "orgId": "…", "sandboxId": "sb-3f9a…",
    "type": "sandbox.stopped", "data": { "reason": "user_requested" }
  }
}
```

Dedupe on **`deliveryId`** — `verifyWebhook` sets it from the `svix-id` header (stable across retries and redelivery). Need to route on your own metadata? Attach `metadata` when you register the destination and it rides as **custom HTTP headers** on every request — there's no metadata in the body.

## Events

Subscribe to all events, or filter with `eventTypes` (exact like `sandbox.stopped`, or a prefix like `sandbox.*`).

| Event                         | When                                            | `event.data`                                                 |
| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------ |
| `sandbox.created`             | the sandbox resource is accepted                | `template`                                                   |
| `sandbox.ready`               | the VM has booted and can run commands          | —                                                            |
| `sandbox.hibernated`          | the sandbox was paused (disk persisted)         | —                                                            |
| `sandbox.resumed`             | a hibernated sandbox woke                       | —                                                            |
| `sandbox.stopped`             | the sandbox stopped                             | `reason`: `user_requested` \| `expired` \| `crash`           |
| `sandbox.migrated`            | the sandbox moved to new infrastructure         | —                                                            |
| `sandbox.checkpoint.created`  | a checkpoint was taken                          | `checkpointId`                                               |
| `sandbox.forked`              | a sandbox was forked from a checkpoint          | `parentId`                                                   |
| `sandbox.scaled`              | the sandbox's resources changed                 | `cpuCount`, `memoryMB`                                       |
| `sandbox.preview_url.changed` | a preview-URL port mapping was added or removed | `port`, `url` (`url` is `null` when the mapping was removed) |

## Destinations

A destination is **org-scoped** by default (all your sandboxes), or pinned to one sandbox with `sandboxId`. Set `enabled: false` to **pause** a destination — it stops receiving deliveries until you re-enable it; events that occur while it's paused aren't backfilled.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  import { Webhooks } from "@opencomputer/sdk";

  const webhooks = new Webhooks({ apiKey: process.env.OPENCOMPUTER_API_KEY! });

  const { id, secret } = await webhooks.create({
    url: "https://app.example.com/oc-webhook",
    eventTypes: ["sandbox.stopped", "sandbox.ready"],
    name: "prod",            // optional display name
  });
  // `secret` (whsec_…) verifies deliveries — returned here and re-fetchable via webhooks.getSecret(id).
  ```

  ```http REST API theme={null}
  POST https://app.opencomputer.dev/api/webhooks
  X-API-Key: $OPENCOMPUTER_API_KEY
  Content-Type: application/json

  {
    "url": "https://app.example.com/oc-webhook",
    "eventTypes": ["sandbox.stopped", "sandbox.ready"],
    "name": "prod"
  }
  ```
</CodeGroup>

Every destination is **signed**. If you don't pass a `secret`, OpenComputer generates one (`whsec_…`) and returns it on create. The secret is re-fetchable any time via `webhooks.getSecret(id)` (`GET /api/webhooks/:id/secret`), and rotatable via `webhooks.update(id, { rotateSecret: true })`.

<Tabs>
  <Tab title="TypeScript SDK">
    | Call                          | Purpose                                                                         |
    | ----------------------------- | ------------------------------------------------------------------------------- |
    | `webhooks.create(params)`     | Register a new destination (returns the `secret`).                              |
    | `webhooks.list()`             | List destinations.                                                              |
    | `webhooks.get(id)`            | Fetch one (`hasSecret`, not the secret value).                                  |
    | `webhooks.getSecret(id)`      | Fetch the current signing secret (`whsec_…`).                                   |
    | `webhooks.update(id, params)` | Pause/resume (`enabled`), retune `eventTypes`, change `url`, or `rotateSecret`. |
    | `webhooks.delete(id)`         | Delete — removes the endpoint; deleted history isn't queryable.                 |
    | `webhooks.test(id)`           | Enqueue a sample event (delivered asynchronously).                              |
  </Tab>

  <Tab title="REST API">
    | Method · Path                  | Purpose                                                             |
    | ------------------------------ | ------------------------------------------------------------------- |
    | `POST /api/webhooks`           | Register a new destination.                                         |
    | `GET /api/webhooks`            | List destinations.                                                  |
    | `GET /api/webhooks/:id`        | Fetch one.                                                          |
    | `GET /api/webhooks/:id/secret` | Fetch the current signing secret.                                   |
    | `PATCH /api/webhooks/:id`      | Pause/resume, retune `eventTypes`, change `url`, or `rotateSecret`. |
    | `DELETE /api/webhooks/:id`     | Delete (history not queryable afterward).                           |
    | `POST /api/webhooks/:id/test`  | Enqueue a sample event (delivered asynchronously).                  |
  </Tab>
</Tabs>

### Subscribe at create

`sandbox.created` and `sandbox.ready` fire before a separate `webhooks.create` call could know the sandbox id. To capture a sandbox's **full** lifecycle, register the webhook **with** the sandbox — it's pinned to that sandbox and gets every event from `created` on:

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create({
    webhooks: [{ url: "https://app.example.com/oc-webhook" }],
  });
  // the generated signing secret is on the create response: sandbox.webhooks[0].secret
  ```

  ```http REST API theme={null}
  POST https://app.opencomputer.dev/api/sandboxes
  X-API-Key: $OPENCOMPUTER_API_KEY
  Content-Type: application/json

  { "template": "base", "webhooks": [{ "url": "https://app.example.com/oc-webhook" }] }
  ```
</CodeGroup>

## Deliveries

Every send and its outcome — the data behind a deliveries dashboard.

<Tabs>
  <Tab title="TypeScript SDK">
    | Call                                           | Purpose                                   |
    | ---------------------------------------------- | ----------------------------------------- |
    | `webhooks.deliveries.list(id)`                 | List recent delivery attempts (up to 50). |
    | `webhooks.deliveries.get(id, messageId)`       | One delivered message, in detail.         |
    | `webhooks.deliveries.redeliver(id, messageId)` | Re-send a message (same `svix-id`).       |
  </Tab>

  <Tab title="REST API">
    | Method · Path                                            | Purpose                           |
    | -------------------------------------------------------- | --------------------------------- |
    | `GET /api/webhooks/:id/deliveries`                       | List recent attempts (up to 50).  |
    | `GET /api/webhooks/:id/deliveries/:messageId`            | One delivered message, in detail. |
    | `POST /api/webhooks/:id/deliveries/:messageId/redeliver` | Re-send a message.                |
  </Tab>
</Tabs>

Each record is a Svix delivery attempt with its `status` and the consumer's `responseStatusCode`; Svix retries failed attempts on its managed schedule and retains recent attempt history (the attempt index lags a send by a few seconds). A deleted destination's history is no longer queryable.

```
Delivery = { id, status: "success" | "pending" | "failed", responseStatusCode?, timestamp }
```

Redelivery re-sends the **same** message to the endpoint (same `svix-id`) — for when the original never landed. A receiver that dedupes on `svix-id` treats it as the same message.

## Signing, retries, and dedupe

* **HTTPS only**, checked at registration. The delivery layer (Svix) additionally blocks private, loopback, link-local, and cloud-metadata addresses at send time.
* **Always signed** with [Standard Webhooks](https://www.standardwebhooks.com) (delivery is by [Svix](https://www.svix.com)). Every request carries `svix-id`, `svix-timestamp`, and `svix-signature` = `v1,<base64(HMAC-SHA256(secret, "{svix-id}.{svix-timestamp}.{rawBody}"))>`. Verify against the **raw request body, before parsing it**; the timestamp guards replay. Any custom headers you attached as destination `metadata` ride along too. Your signing `secret` is re-fetchable any time via `GET /api/webhooks/{id}/secret` and rotatable via update (`rotateSecret: true`).
* **At-least-once.** Once an event is handed off it's retried until it succeeds or the delivery layer gives up. A duplicate can still arrive, so **dedupe on `svix-id`** (the verifier exposes it as both `deliveryId` and `dedupeId`).
* **Not strictly ordered.** Events for one sandbox can arrive out of order (e.g. `sandbox.ready` before `sandbox.created`). Treat each event independently and key off `event.type`; don't assume an ordering.
* **Success / retry / give-up.** A delivery succeeds on HTTP `2xx`. Failures are retried on Svix's managed backoff (immediately, then 5s, 5m, 30m, 2h, 5h, 10h, 10h); an endpoint that keeps failing for \~5 days is auto-disabled. Inspect attempts and recover failed messages via the [deliveries API](#deliveries). Unsafe targets (private / loopback / cloud-metadata addresses) are blocked by the delivery layer.

### Verify a webhook

The SDK ships a verifier — no extra dependency, runs in Node / Cloudflare Workers / browsers — that checks the signature and returns the parsed envelope. It's the **same `verifyWebhook`** used for [session webhooks](/agent-sessions/webhooks); pass `SandboxLifecycleEvent` to type the nested event:

```ts theme={null}
import { verifyWebhook, type SandboxLifecycleEvent } from "@opencomputer/sdk";

// rawBody = the RAW request body string, read BEFORE JSON.parse.
// Throws on a missing / expired / invalid signature.
const delivery = await verifyWebhook<SandboxLifecycleEvent>(rawBody, request.headers, process.env.OC_WEBHOOK_SECRET!);

if (delivery.type === "sandbox.stopped") {
  console.log(delivery.sandboxId, delivery.event.data.reason); // event.data is typed per event
}
```

Or verify with any [Standard Webhooks](https://www.standardwebhooks.com) / Svix library directly, against the raw body and the `svix-id` / `svix-timestamp` / `svix-signature` headers.

<Note>Webhooks here cover **sandbox lifecycle**. To deliver an agent's *session* events (turns, messages, results), see [Agent Sessions webhooks](/agent-sessions/webhooks) — verified with the same `verifyWebhook` helper. Session webhooks differ in a couple of specifics today: their `webhook-id` is the event id, and signing is opt-in (set a `secret`).</Note>


# Working with Files
Source: https://docs.opencomputer.dev/sandboxes/working-with-files

Read, write, and manage files inside a sandbox

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();

  await sandbox.files.write("/app/hello.txt", "Hello, World!");
  const content = await sandbox.files.read("/app/hello.txt");
  console.log(content); // "Hello, World!"

  await sandbox.kill();
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  async with await Sandbox.create() as sandbox:
      await sandbox.files.write("/app/hello.txt", "Hello, World!")
      content = await sandbox.files.read("/app/hello.txt")
      print(content)  # "Hello, World!"
  ```
</CodeGroup>

## Reading Files

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Read as string
  const text = await sandbox.files.read("/app/config.json");

  // Read as bytes
  const bytes = await sandbox.files.readBytes("/app/image.png");
  ```

  ```python Python theme={null}
  # Read as string
  text = await sandbox.files.read("/app/config.json")

  # Read as bytes
  data = await sandbox.files.read_bytes("/app/image.png")
  ```
</CodeGroup>

## Writing Files

Content can be a string or binary data:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Write text
  await sandbox.files.write("/app/config.json", JSON.stringify({ port: 3000 }));

  // Write binary
  const imageData = new Uint8Array([...]);
  await sandbox.files.write("/app/logo.png", imageData);
  ```

  ```python Python theme={null}
  # Write text
  await sandbox.files.write("/app/config.json", '{"port": 3000}')

  # Write binary
  await sandbox.files.write("/app/logo.png", image_bytes)
  ```
</CodeGroup>

## Listing Directories

<CodeGroup>
  ```typescript TypeScript theme={null}
  const entries = await sandbox.files.list("/app");
  for (const entry of entries) {
    console.log(entry.isDir ? "📁" : "📄", entry.name, entry.size);
  }
  ```

  ```python Python theme={null}
  entries = await sandbox.files.list("/app")
  for entry in entries:
      kind = "dir" if entry.is_dir else "file"
      print(f"{kind}: {entry.name} ({entry.size} bytes)")
  ```
</CodeGroup>

### EntryInfo

| Field         | TypeScript | Python   | Type    |
| ------------- | ---------- | -------- | ------- |
| Name          | `name`     | `name`   | string  |
| Is directory  | `isDir`    | `is_dir` | boolean |
| Full path     | `path`     | `path`   | string  |
| Size in bytes | `size`     | `size`   | number  |

## Managing Files

### Create Directory

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.files.makeDir("/app/data");
  ```

  ```python Python theme={null}
  await sandbox.files.make_dir("/app/data")
  ```
</CodeGroup>

### Remove

Deletes a file or directory:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.files.remove("/app/temp");
  ```

  ```python Python theme={null}
  await sandbox.files.remove("/app/temp")
  ```
</CodeGroup>

### Check Existence

<CodeGroup>
  ```typescript TypeScript theme={null}
  if (await sandbox.files.exists("/app/config.json")) {
    const config = await sandbox.files.read("/app/config.json");
  }
  ```

  ```python Python theme={null}
  if await sandbox.files.exists("/app/config.json"):
      config = await sandbox.files.read("/app/config.json")
  ```
</CodeGroup>

<Note>
  `exists()` is a client-side convenience — it attempts a file read and returns `false` on error. There is no dedicated HTTP endpoint for existence checks.
</Note>

## Large Files

All file operations are streamed end-to-end using 256KB chunks — there is no file size limit beyond available disk space. Files up to 200MB+ transfer reliably at \~20 MB/s.

The standard `read()`, `readBytes()`, and `write()` methods work for large files, but they buffer the full content in memory on the client side. For very large files, use the streaming methods to avoid high memory usage:

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Stream a large file download — returns a ReadableStream, not a buffer
  const stream = await sandbox.files.readStream("/data/model.bin");

  // Pipe to a file, or process chunks incrementally
  const reader = stream.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    // process each Uint8Array chunk...
  }

  // Stream a large file upload — accepts ReadableStream or Uint8Array
  const fileStream = someReadableStream; // e.g. from fs.createReadStream
  await sandbox.files.writeStream("/data/model.bin", fileStream);

  // Uint8Array also works (sent without buffering a copy)
  await sandbox.files.writeStream("/data/output.bin", largeUint8Array);
  ```

  ```python Python theme={null}
  # Stream a large file download — returns an async byte iterator
  stream = await sandbox.files.read_stream("/data/model.bin")
  async for chunk in stream:
      # process each bytes chunk...
      pass

  # Stream a large file upload — accepts an async iterator
  async def file_chunks():
      with open("local_model.bin", "rb") as f:
          while chunk := f.read(256 * 1024):
              yield chunk

  await sandbox.files.write_stream("/data/model.bin", file_chunks())
  ```
</CodeGroup>

## Examples

### Upload and Run a Script

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.files.write("/tmp/setup.sh", `#!/bin/bash
  apt-get update && apt-get install -y redis-server
  redis-server --daemonize yes
  `);
  await sandbox.exec.run("chmod +x /tmp/setup.sh && /tmp/setup.sh");
  ```

  ```python Python theme={null}
  await sandbox.files.write("/tmp/setup.sh", """#!/bin/bash
  apt-get update && apt-get install -y redis-server
  redis-server --daemonize yes
  """)
  await sandbox.exec.run("chmod +x /tmp/setup.sh && /tmp/setup.sh")
  ```
</CodeGroup>

<Tip>
  Full reference: [TypeScript SDK](/reference/typescript-sdk#filesystem) · [Python SDK](/reference/python-sdk#filesystem) · [HTTP API](/reference/api#filesystem).
</Tip>


# GCP development cell
Source: https://docs.opencomputer.dev/self-hosting/gcp-development

Run a complete OpenComputer development environment on a nested-KVM Compute Engine VM.

This guide deploys a complete OpenComputer development cell to one Google
Compute Engine VM. The VM runs the control plane, worker, PostgreSQL, Redis, and
QEMU/KVM sandboxes together.

<Warning>
  This topology is for development and performance testing. It has one host, no
  high availability, an HTTP API, and ephemeral Local SSD storage. For the
  production shape, start with the [self-hosting architecture](/self-hosting/overview).
</Warning>

## What gets created

```text theme={null}
Developer machine
   |
   | SSH and HTTP, restricted by a GCP firewall rule
   v
+------------------------------------------------------+
| Compute Engine VM                                    |
|                                                      |
| opensandbox-server :8080                             |
| opensandbox-worker                                   |
| PostgreSQL + Redis                                   |
| QEMU/KVM sandbox VMs                                 |
|                                                      |
| 50 GB persistent boot disk                           |
| 375 GiB Local NVMe SSD mounted at /data              |
+------------------------------------------------------+
```

The default configuration uses:

| Resource          | Default                                |
| ----------------- | -------------------------------------- |
| Machine type      | `n2-standard-8`                        |
| CPU and memory    | 8 vCPU, 32 GiB                         |
| Operating system  | Ubuntu 24.04 LTS                       |
| Boot disk         | 50 GB `pd-ssd`                         |
| Sandbox data disk | One 375 GiB Local SSD over NVMe        |
| Sandbox runtime   | QEMU with nested KVM                   |
| Sandbox default   | 2 vCPU with dynamically managed memory |
| API port          | `8080`                                 |

Google documents the supported machine families and expected overhead in its
[nested virtualization overview](https://cloud.google.com/compute/docs/instances/nested-virtualization/overview).
Do not substitute an E2, AMD, or Arm machine for this guide.

## Prerequisites

You need:

* A GCP project with billing enabled.
* Permission to enable APIs and create Compute Engine instances and firewall
  rules.
* The current [Google Cloud CLI](https://cloud.google.com/sdk/docs/install-sdk).
* `git`, `curl`, `jq`, `ssh`, `rsync`, and `openssl` on your development
  machine.
* A clone of the OpenComputer repository.

Authenticate and enable Compute Engine:

```bash theme={null}
export GCP_PROJECT="<your-project-id>"
export GCP_ZONE="us-east4-c"

gcloud auth login
gcloud config set project "$GCP_PROJECT"
gcloud services enable compute.googleapis.com
```

Run the remaining commands from the OpenComputer repository root.

## Configure the deployment

Choose a machine and instance name, then generate a development API key:

```bash theme={null}
export MACHINE_TYPE="n2-standard-8"
export INSTANCE_NAME="opensandbox-qemu-dev"
export API_KEY="$(openssl rand -hex 32)"

printf 'Save this development API key now: %s\n' "$API_KEY"
```

Keep the API key in a password manager or a local secret file outside the
repository. The deploy script stores only its hash in PostgreSQL.

### Restrict ingress before creating the VM

The deployment script looks for a firewall rule named
`opensandbox-dev-allow`. Create that rule first so the development API and SSH
are not exposed to the internet.

Replace the CIDR below with your current public IP:

```bash theme={null}
export ADMIN_CIDR="<your-public-ip>/32"

gcloud compute firewall-rules create opensandbox-dev-allow \
  --direction=INGRESS \
  --action=ALLOW \
  --rules=tcp:22,tcp:8080 \
  --source-ranges="$ADMIN_CIDR" \
  --target-tags=opensandbox-dev \
  --description="OpenComputer development cell: SSH and API"
```

If the rule already exists, inspect and tighten it:

```bash theme={null}
gcloud compute firewall-rules update opensandbox-dev-allow \
  --rules=tcp:22,tcp:8080 \
  --source-ranges="$ADMIN_CIDR"
```

<Warning>
  The cell serves plain HTTP. Keep port `8080` restricted to trusted source
  addresses. Do not expose worker port `8081`, PostgreSQL, Redis, or worker RPC.
</Warning>

## Create the host

Create the VM, enable nested virtualization, format the Local SSD as
reflink-enabled XFS, and install the host dependencies:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh create
```

The first run:

1. Creates an SSH key if the configured key does not exist.
2. Creates an Ubuntu N2 instance with nested virtualization enabled.
3. Attaches one Local NVMe SSD.
4. Mounts the SSD at `/data`.
5. Installs QEMU/KVM, Docker, Go, PostgreSQL, Redis, and the systemd units.

Confirm KVM before deploying:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh ssh -- \
  sh -lc 'test -c /dev/kvm && echo "KVM ready" || echo "KVM missing"'
```

Expected output:

```text theme={null}
KVM ready
```

## Deploy OpenComputer

Build the server, worker, and in-VM agent; build the rootfs images; install the
environment files; start the services; and seed the development API key:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh deploy
```

The first rootfs build takes several minutes. It emits:

* `default.ext4`: the legacy 4 GiB split-disk base.
* `default-merged.ext4`: the unified 20 GiB base used by new sandboxes.

The unified layout keeps `/`, `/home/sandbox`, and `/workspace` on one virtual
disk. The underlying image is sparse, so its logical 20 GiB size does not
consume 20 GiB of Local SSD space immediately.

### Wait for worker registration

The HTTP health endpoint can become ready before the worker has created its
golden snapshot and registered with the control plane. On a fresh host, allow
approximately one minute after deployment.

Inspect the server log:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh ssh -- \
  sudo journalctl -u opensandbox-server -n 100 --no-pager
```

Continue after you see a message similar to:

```text theme={null}
new worker registered: w-qemu-dev-1
```

If sandbox creation returns `503 no workers available`, wait for registration
and retry.

## Validate the cell

Get the public IP and configure your shell:

```bash theme={null}
export PUBLIC_IP="$(
  gcloud compute instances describe "$INSTANCE_NAME" \
    --zone="$GCP_ZONE" \
    --format='value(networkInterfaces[0].accessConfigs[0].natIP)'
)"
export OPENCOMPUTER_URL="http://${PUBLIC_IP}:8080"
export OPENCOMPUTER_API_KEY="$API_KEY"
```

Check control-plane health:

```bash theme={null}
curl -fsS "$OPENCOMPUTER_URL/health"
```

Create a sandbox:

```bash theme={null}
export SANDBOX_ID="$(
  curl -fsS -X POST "$OPENCOMPUTER_URL/api/sandboxes" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
    -d '{"templateID":"default"}' |
  jq -r .sandboxID
)"

printf 'Sandbox: %s\n' "$SANDBOX_ID"
```

Run a command inside the VM and verify the unified disk:

```bash theme={null}
curl -fsS -X POST \
  "$OPENCOMPUTER_URL/api/sandboxes/$SANDBOX_ID/exec/run" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
  -d '{
    "cmd": "sh",
    "args": [
      "-lc",
      "uname -a; nproc; free -h; df -h / /home/sandbox /workspace; lsblk"
    ],
    "timeout": 30
  }' |
jq
```

For the default unified rootfs, `lsblk` should show one approximately 20 GiB
`vda`, and all three paths should resolve to the same root filesystem.

## Use the dashboard during development

The development deployment enables the explicit `single-tenant` dashboard
mode. On startup, the control plane creates or reuses one local organization
and administrator in PostgreSQL and keeps that development organization on the
Pro plan so hosted free-tier size gates do not restrict local testing. The
dashboard therefore shows the live cell's sandboxes without requiring an
external identity provider.

<Warning>
  Single-tenant mode supplies a persistent local identity but does not
  authenticate individual browser users. Reach the development UI through SSH
  port forwarding and do not expose the Vite port publicly.
</Warning>

### Start the development UI

The deploy command syncs the dashboard source to the VM. In one terminal, run
Vite there through the existing Docker installation:

```bash theme={null}
gcloud compute ssh "$INSTANCE_NAME" \
  --project="$GCP_PROJECT" \
  --zone="$GCP_ZONE" \
  --command='
    sudo docker run --rm --network host \
      -v "$HOME/opensandbox/web:/app" \
      -w /app \
      node:22-bookworm-slim \
      sh -lc "npm ci && npm run dev -- --host 127.0.0.1"
  '
```

Vite's development proxy reaches the control plane at `localhost:8080` on the
VM, so UI requests use the single-tenant identity and operate on the live
development cell.

### Forward it to your machine

Keep Vite running. In a second local terminal, forward the VM's loopback-only
UI port to port `3000` on your machine:

```bash theme={null}
gcloud compute ssh "$INSTANCE_NAME" \
  --project="$GCP_PROJECT" \
  --zone="$GCP_ZONE" \
  -- -N \
  -L 127.0.0.1:3000:127.0.0.1:3000 \
  -o ExitOnForwardFailure=yes \
  -o ServerAliveInterval=30
```

Open [http://127.0.0.1:3000](http://127.0.0.1:3000).

Every dashboard action is attributed to the development administrator. You can
customize that identity before deploying:

```bash theme={null}
export OPENSANDBOX_DASHBOARD_AUTH_MODE="single-tenant"
export OPENSANDBOX_DASHBOARD_USER_EMAIL="admin@example.internal"
export OPENSANDBOX_DASHBOARD_USER_NAME="Development Admin"
export OPENSANDBOX_DASHBOARD_TENANT_NAME="Development"
export OPENSANDBOX_DASHBOARD_TENANT_SLUG="development"

./deploy/gcp/deploy-qemu-dev.sh deploy
```

## Operations

Check status:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh status
```

Follow logs:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh ssh -- \
  sudo journalctl -u opensandbox-worker -f
```

Redeploy the current checkout:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh deploy
```

The deploy command synchronizes the current local checkout to the VM and
restarts the services.

### Rebuild the rootfs

Normal deploys reuse existing rootfs images. When you intentionally need to
test a rootfs change, remove both cached bases and deploy again:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh ssh -- \
  sudo rm -f \
    /data/firecracker/images/default.ext4 \
    /data/firecracker/images/default-merged.ext4

./deploy/gcp/deploy-qemu-dev.sh deploy
```

This affects only future sandboxes. Delete or recreate existing development
sandboxes separately if you need them to use the new base.

## Storage and shutdown

The 50 GB boot disk is a persistent block disk. The 375 GiB Local SSD mounted
at `/data` holds active sandbox disks and rootfs images.

Google documents that Local SSD data is discarded by default when an instance
is stopped and recommends durable block storage for data that must survive
host replacement. See [About Local SSD disks](https://cloud.google.com/compute/docs/disks/local-ssd).

<Warning>
  Treat `stop`, instance deletion, and host replacement as destructive for
  everything under `/data`. Configure object storage before testing durable
  checkpoints or hibernation, and never keep the only copy of important data on
  the Local SSD.
</Warning>

Delete the development VM when you are finished:

```bash theme={null}
./deploy/gcp/deploy-qemu-dev.sh destroy
```

The script asks for confirmation before deleting the instance.

## Troubleshooting

### `no workers available`

The server became healthy before worker registration completed. Wait for the
worker registration log, then retry sandbox creation.

### `/dev/kvm` is missing

Confirm that the VM is using a supported Intel machine type, nested
virtualization was enabled at instance creation, and your organization policy
allows nested virtualization.

```bash theme={null}
gcloud compute instances describe "$INSTANCE_NAME" \
  --zone="$GCP_ZONE" \
  --format='yaml(machineType,advancedMachineFeatures)'
```

### The control-plane root redirects to `localhost:3000`

No built dashboard bundle is installed. Run Vite using one of the dashboard
modes above, or build `web/dist` before packaging the control plane.

### API requests return `401`

Use the same API key that was passed to `deploy`:

```bash theme={null}
curl -fsS "$OPENCOMPUTER_URL/api/sandboxes" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY"
```

### The public IP changed

Run `status` to refresh the deployment state, update
`OPENCOMPUTER_URL`, and confirm that the firewall still allows your current
source address.


# Self-hosting
Source: https://docs.opencomputer.dev/self-hosting/overview

Understand the OpenComputer architecture and choose a development or scalable deployment shape.

OpenComputer can run inside your own cloud account. A self-hosted deployment
combines an API control plane with Linux hosts that use QEMU/KVM to run isolated
sandbox VMs.

Self-hosting is an operator workflow. You are responsible for provisioning the
cloud resources, securing the API, operating the data stores, and upgrading the
OpenComputer services.

<CardGroup>
  <Card title="GCP development cell" icon="google" href="/self-hosting/gcp-development">
    Run a complete single-cell development environment on one nested-KVM Compute Engine VM.
  </Card>

  <Card title="Configuration reference" icon="sliders" href="https://github.com/diggerhq/opencomputer/blob/main/deploy/server.env.example">
    Review the control-plane environment-variable shape.
  </Card>
</CardGroup>

## Architecture

OpenComputer has three runtime tiers:

```text theme={null}
Client, SDK, CLI, or dashboard
                |
                | HTTP
                v
+---------------+----------------+
| Control plane                  |
|                                |
| API and authentication         |
| Sandbox lifecycle and routing  |
| Worker coordination            |
+---------------+----------------+
                |
                | worker RPC
                v
+---------------+----------------+
| Data plane worker              |
|                                |
| QEMU/KVM VM lifecycle          |
| Networking and storage         |
| Checkpoint and hibernation     |
+---------------+----------------+
                |
                | virtio serial / vsock
                v
+---------------+----------------+
| Sandbox VM                     |
|                                |
| Full Linux filesystem          |
| OpenComputer in-VM agent       |
| User commands and processes    |
+--------------------------------+
```

### Control plane

The control plane exposes the OpenComputer HTTP API. It authenticates requests,
tracks sandbox state, chooses a worker, and routes operations to the worker that
owns each sandbox.

The control-plane binary is named `opensandbox-server`. The historical
`opensandbox` name also appears in environment variables as the
`OPENSANDBOX_*` prefix.

### Data plane

Data-plane workers run on Linux machines with KVM. Each worker starts QEMU
microVMs, configures their networking and disks, and maintains the connection
to the agent inside each VM.

The worker binary is named `opensandbox-worker`. A worker registers itself with
the control plane through Redis and advertises its capacity and RPC address.

### In-VM agent

Every sandbox image contains `osb-agent`. It receives command, file, terminal,
and process operations from the worker over a VM-local transport. User
workloads do not need direct access to the worker host.

## Request lifecycle

When a client creates a sandbox:

1. The control plane authenticates the request and selects a worker with
   capacity.
2. The worker creates a copy-on-write disk from the selected rootfs image.
3. QEMU starts the sandbox with KVM acceleration.
4. The worker waits for `osb-agent`, applies sandbox networking and environment
   configuration, and reports the sandbox as running.
5. Subsequent API calls are routed to the owning worker and then to the
   in-VM agent.

OpenComputer can keep paused VMs in a warm pool. Claiming a prepared VM avoids
most cold-start work while preserving VM isolation.

## Deployment shapes

### Single-cell development

A development cell can run every component on one VM:

```text theme={null}
+--------------------------------------------------+
| One development VM                               |
|                                                  |
| opensandbox-server :8080                         |
| opensandbox-worker                               |
| PostgreSQL + Redis                               |
| QEMU/KVM sandbox VMs                             |
| local rootfs images and sandbox disks            |
+--------------------------------------------------+
```

This is the fastest way to test real VM behavior. It is not highly available,
and local storage can be ephemeral. Use the
[GCP development guide](/self-hosting/gcp-development) for this topology.

### Scalable hosting

A scalable deployment separates the control plane from a pool of worker
machines:

```text theme={null}
                         +----------------------+
                         | HTTPS load balancer  |
                         +----------+-----------+
                                    |
                         +----------v-----------+
                         | Control plane        |
                         | one or more replicas |
                         +----+-------------+---+
                              |             |
                    +---------v--+       +--v-----------+
                    | PostgreSQL |       | Redis        |
                    +------------+       +--------------+
                              |
                    +---------v-------------------------+
                    | Worker pool                       |
                    | KVM host | KVM host | KVM host    |
                    +------------------+----------------+
                                       |
                              +--------v---------+
                              | Object storage   |
                              | durable VM data  |
                              +------------------+
```

A production-shaped deployment should include:

* Multiple control-plane replicas behind HTTPS.
* A worker pool spread across failure domains.
* Durable PostgreSQL and Redis services.
* S3-compatible object storage for checkpoints, hibernation archives, and
  durable image artifacts.
* A secrets manager for database credentials, signing keys, storage
  credentials, and third-party integrations.
* Monitoring, centralized logs, backups, and tested recovery procedures.
* Private worker networking. Only the control-plane or edge endpoint should be
  public.

The control plane can launch cloud workers using the supported provider
integrations, or workers can be provisioned independently and configured to
register with the cell.

## State and storage

Different data has different durability requirements:

| Data                                     | Recommended storage                          |
| ---------------------------------------- | -------------------------------------------- |
| Organizations, API keys, sandbox records | PostgreSQL                                   |
| Worker registry and coordination         | Redis                                        |
| Checkpoints and hibernation archives     | S3-compatible object storage                 |
| Golden rootfs images                     | Worker image or durable object storage       |
| Active sandbox disks                     | Fast local NVMe or provisioned block storage |

Fast local disks are a good fit for active copy-on-write sandbox disks, but they
must not be the only copy of data that needs to survive a worker replacement.

## Networking and security

At minimum:

* Terminate public traffic with HTTPS.
* Keep worker RPC, Redis, PostgreSQL, and worker HTTP ports on private networks.
* Use a randomly generated API key for development and a managed
  authentication flow for shared environments.
* Store secrets outside source control.
* Restrict administrative SSH access to known source addresses or an identity
  aware access layer.
* Treat preview URLs and sandbox egress as security boundaries, not ordinary
  application routes.

The single-cell development guides intentionally trade availability and
durability for simplicity. Do not expose one directly to untrusted traffic.

## Moving from development to scalable hosting

Use the single-cell environment to validate:

* KVM and sandbox boot.
* The unified rootfs and in-VM agent.
* Command, file, and terminal APIs.
* Checkpoint and wake behavior after object storage is configured.
* Your client and SDK integration.

Before serving production traffic, move PostgreSQL, Redis, and durable artifacts
off the worker host; place the API behind HTTPS; provision replaceable workers;
and test worker loss while sandboxes are running.


# Troubleshooting
Source: https://docs.opencomputer.dev/troubleshooting

Common errors and debugging tips

## Common Errors

### `401 Unauthorized`

Your API key is missing or invalid.

* Check that `OPENCOMPUTER_API_KEY` is set: `echo $OPENCOMPUTER_API_KEY`
* Verify the key in your code matches what's in the dashboard
* CLI users: run `oc config show` to check the stored key

### `Sandbox not found`

The sandbox may have been killed or timed out (auto-hibernated or stopped).

```bash theme={null}
oc ls                     # list all sandboxes
oc sandbox get sb-abc123  # check a specific sandbox
```

In code:

```typescript theme={null}
const running = await sandbox.isRunning();
```

### `Connection refused`

The sandbox is still starting up, or it's hibernated and hasn't finished waking.

* Check the sandbox status — if `hibernated`, call `wake()` or `oc sandbox wake`
* If just created, wait a moment for the VM to boot (\~150ms typical)

### Timeout errors

**Command timeout:** Increase the `timeout` parameter on `exec.run()` or use `--timeout` with `oc exec`. Default is 60s for SDK `exec.run()`, unlimited for CLI without `--wait`.

**Idle timeout:** Sandboxes auto-hibernate after 300s of inactivity. Increase with `sandbox.setTimeout()` or `oc sandbox set-timeout`. The timeout resets on every operation.

### Agent exits immediately

* Check that the sandbox has the Claude Agent SDK installed (the default template includes it)
* Verify `ANTHROPIC_API_KEY` is available — pass it via `envs` on sandbox create if the agent needs it
* Use the `onError` callback to capture stderr from the agent process

## Debugging Tips

### Check sandbox status

```bash theme={null}
oc sandbox get sb-abc123
```

```typescript theme={null}
console.log(sandbox.status);
const running = await sandbox.isRunning();
```

### List running processes

```bash theme={null}
oc exec sb-abc123 --wait -- ps aux
```

```typescript theme={null}
const sessions = await sandbox.exec.list();
for (const s of sessions) {
  console.log(s.sessionID, s.running, s.command);
}
```

### Capture agent errors

```typescript theme={null}
const session = await sandbox.agent.start({
  prompt: "...",
  onEvent: (event) => {
    if (event.type === "error") console.error("Agent error:", event.message);
  },
  onError: (data) => console.error("Stderr:", data),
});
```

### Read sandbox logs

```bash theme={null}
oc exec sb-abc123 --wait -- cat /var/log/syslog
oc exec sb-abc123 --wait -- journalctl --no-pager -n 50
```

## Getting Help

* **GitHub Issues:** [github.com/diggerhq/opencomputer/issues](https://github.com/diggerhq/opencomputer/issues)
* **API Reference:** [HTTP API](/reference/api) · [TypeScript SDK](/reference/typescript-sdk) · [Python SDK](/reference/python-sdk) · [CLI](/reference/cli)