### Clone and deploy the example project

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agents/examples/github-actions-triage.mdx

Use this command sequence to clone the example repository, install dependencies, log in to OpenComputer, and deploy to the Development environment. Keep the watch command running while testing; it deploys changes but does not start a local agent server.

```bash
git clone https://github.com/diggerhq/opencomputer-example-actions-triage.git
cd opencomputer-example-actions-triage
npm install
npm run opencomputer -- login
npm run deploy -- --watch
```

--------------------------------

### Install OpenComputer CLI

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agents/document-memory.mdx

Install the CLI globally with npm. After installation, log in and link your project as described in the quickstart.

```bash
npm install -g @opencomputer/cli
```

--------------------------------

### Image.base() example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/reference/python-sdk/image.mdx

Starts from the default OpenSandbox environment (Ubuntu 22.04, Python, Node.js, build tools) and chains builder methods to install packages, set environment variables, and set the working directory.

```python
from opencomputer import Image

image = (
    Image.base()
    .apt_install(["curl", "jq"])
    .pip_install(["requests", "pandas"])
    .env({"PROJECT_ROOT": "/workspace"})
    .workdir("/workspace")
)
```

--------------------------------

### Install VNC stack and start Xvfb, x11vnc, websockify

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/guides/browser-automation.mdx

Installs the VNC stack (xvfb, x11vnc, novnc, websockify) and starts Xvfb, x11vnc, and websockify as long-lived exec sessions so they persist across commands.

```typescript
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"],
});
```

--------------------------------

### Clone and initialize the test coverage example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agents/examples/test-coverage.mdx

Commands to clone the repository, install dependencies, run tests, and perform a type check before logging into OpenComputer.

```bash
git clone https://github.com/diggerhq/opencomputer-example-test-coverage.git
cd opencomputer-example-test-coverage
npm install
npm test
npm run typecheck
npm run opencomputer -- login
```

--------------------------------

### Quick Start: Create sandbox, run commands, read/write files, and cleanup

Source: https://github.com/diggerhq/opencomputer/blob/main/sdks/python/README.md

Example usage of the opencomputer SDK. Creates a sandbox with the 'base' template, runs a command, writes and reads a file, then kills and closes the sandbox.

```python
import asyncio
from opencomputer import Sandbox

async def main():
    sandbox = await Sandbox.create(template="base")

    # Execute commands
    result = await sandbox.commands.run("echo hello")
    print(result.stdout)  # "hello\n"

    # Read and write files
    await sandbox.files.write("/tmp/test.txt", "Hello, world!")
    content = await sandbox.files.read("/tmp/test.txt")

    # Clean up
    await sandbox.kill()
    await sandbox.close()

asyncio.run(main())
```

--------------------------------

### Start a streaming exec session with sandbox.exec.start

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/reference/python-sdk.mdx

Starts a long-running command with streaming I/O. The example starts 'node server.js' in /app, printing stdout lines as they arrive, and waits for the exit code via session.done.

```python
session = await sandbox.exec.start(
    "node", args=["server.js"], cwd="/app",
    on_stdout=lambda b: print(b.decode(), end=""),
)
exit_code = await session.done
```

--------------------------------

### Upload and Run a Script (Python)

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/sandboxes/working-with-files.mdx

Writes a shell script to /tmp/setup.sh and executes it. The script updates the package list, installs redis-server, and starts it as a daemon. Use this when you need to set up a service inside the sandbox before running your main task.

```python
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");
```

--------------------------------

### Upload and Run a Script (TypeScript)

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/sandboxes/working-with-files.mdx

Writes a shell script to /tmp/setup.sh and executes it. The script updates the package list, installs redis-server, and starts it as a daemon. Use this when you need to set up a service inside the sandbox before running your main task.

```typescript
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");
```

--------------------------------

### Sandbox SDK usage example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/guides/build-a-lovable-clone.mdx

Shows how to use the OpenComputer SDK to create a sandbox, write files, run commands, and get a public preview URL. This is the core pattern for the generation flow.

```typescript
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 });
```

--------------------------------

### Complete example: on-demand image and pre-built snapshot

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/sdks/python/templates.mdx

This example shows two patterns: building an image on demand and using a pre-built snapshot. It imports asyncio and the opencomputer classes, defines an async main function, creates a dev image with apt, pip, file, env, and workdir configurations, creates a sandbox with build logs, runs a command, kills the sandbox, then creates a production image, creates a snapshot named 'ml-env', creates a sandbox from that snapshot, runs a Python command, kills the sandbox, and deletes the snapshot.

```python
import asyncio
from opencomputer import Sandbox, Image, Snapshots

async def main():
    # ── Pattern 1: On-demand image ──
    dev_image = (
        Image.base()
        .apt_install(["curl", "jq"])
        .pip_install(["requests"])
        .add_file("/workspace/config.json", '{"debug": true}')
        .env({"APP_ENV": "development"})
        .workdir("/workspace")
    )

    sandbox = await Sandbox.create(
        image=dev_image,
        on_build_log=lambda log: print(f"build: {log}"),
    )

    await sandbox.commands.run("curl --version")
    await sandbox.kill()

    # ── Pattern 2: Pre-built snapshot ──
    snapshots = Snapshots()

    prod_image = (
        Image.base()
        .apt_install(["python3-pip", "git"])
        .pip_install(["pandas", "numpy", "scikit-learn"])
        .run_commands("mkdir -p /workspace/data")
        .env({"APP_ENV": "production"})
        .workdir("/workspace")
    )

    await snapshots.create(
        name="ml-env",
        image=prod_image,
        on_build_logs=lambda log: print(f"build: {log}"),
    )

    # Instant — no build, just boot from snapshot
    ml_sandbox = await Sandbox.create(snapshot="ml-env")
    await ml_sandbox.commands.run(
        'python3 -c "import pandas; print(pandas.__version__)"'
    )
    await ml_sandbox.kill()

    # Cleanup
    await snapshots.delete("ml-env")

asyncio.run(main())
```

--------------------------------

### sandbox.exec.background example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/reference/typescript-sdk/exec.mdx

Runs a command in the background using sandbox.exec.background, which is an alias for start. The example starts 'npm run dev' and writes stdout to process.stdout.

```typescript
const server = await sandbox.exec.background("npm", {
  args: ["run", "dev"],
  onStdout: (data) => process.stdout.write(data),
});
```

--------------------------------

### Edit hello-world agent with useInput and useModel

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agents/quickstart.mdx

Example agent code that uses useInput to get the current request and useModel to select the model. Saving the file publishes a new development deployment; an existing session keeps the deployment it started with.

```tsx
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"}`;
}
```

--------------------------------

### Quick example in Python

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/introduction.mdx

Create a sandbox, run a command, print its stdout, and kill the sandbox using the Python SDK with asyncio.

```python
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())
```

--------------------------------

### Create the host with deploy-qemu-dev.sh create

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/self-hosting/gcp-development.mdx

Creates the VM, enables nested virtualization, formats the Local SSD as reflink-enabled XFS, and installs host dependencies. The first run creates an SSH key if needed, creates an Ubuntu N2 instance with nested virtualization, attaches one Local NVMe SSD, mounts it at /data, and installs QEMU/KVM, Docker, Go, PostgreSQL, Redis, and systemd units.

```bash
./deploy/gcp/deploy-qemu-dev.sh create
```

--------------------------------

### Quick Start: Create and use a Sandbox

Source: https://github.com/diggerhq/opencomputer/blob/main/sdks/typescript/README.md

Create a sandbox, run commands, read/write files, and clean up. Demonstrates the core Sandbox API.

```typescript
import { Sandbox } from "@opencomputer/sdk";

const sandbox = await Sandbox.create({ template: "base" });

// Execute commands
const result = await sandbox.commands.run("echo hello");
console.log(result.stdout); // "hello\n"

// Read and write files
await sandbox.files.write("/tmp/test.txt", "Hello, world!");
const content = await sandbox.files.read("/tmp/test.txt");

// Clean up
await sandbox.kill();
```

--------------------------------

### GET /github/installations

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agent-sessions/api-reference.mdx

Lists GitHub installations visible to OpenComputer. Returns an array of installation objects.

```APIDOC
## GET /github/installations

### Description
Lists GitHub installations visible to OpenComputer. Returns an array of installation objects.

### Method
GET

### Endpoint
/github/installations

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **items** (array) - Array of installation objects.
  - **id** (string) - The unique identifier of the installation.
  - **account** (string) - The GitHub account (user or org) that installed the app.
  - **app_id** (string) - The ID of the app.
  - **created_at** (string) - Creation timestamp.

#### Response Example
{
  "items": [
    {
      "id": "install_123",
      "account": "octocat",
      "app_id": "app_123",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}
```

--------------------------------

### Quick Start: create, exec, shell, and kill sandbox

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/cli/overview.mdx

Creates a sandbox, runs a command with `--wait`, opens an interactive shell, and cleans up with `oc sandbox kill`.

```bash
# 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
```

--------------------------------

### Launch the dev host

Source: https://github.com/diggerhq/opencomputer/blob/main/deploy/ec2/README.md

Sources the environment file and runs the create script to launch the QEMU dev host. Takes ~5–10 minutes and prints the public IP. After creation, update DEV_IP in the env file and re-source.

```bash
source ~/.opensandbox-dev.env
cd <repo>
./deploy/ec2/deploy-qemu-dev.sh create     # ~5–10 min, prints the public IP
```

--------------------------------

### GET /api/sandboxes/{id} - 200 Response Example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/sandboxes/get.mdx

Example JSON response for a successful GET request to retrieve sandbox details. Shows the sandbox object with fields including sandboxID, status, region, workerID, tags, and tagsLastUpdatedAt. The tags field is an object and tagsLastUpdatedAt is a timestamp string.

```json
{
  "sandboxID": "sb-abc123",
  "status": "running",
  "region": "use2",
  "workerID": "w-use2-abc123",
  "tags": { "env": "prod", "team": "payments" },
  "tagsLastUpdatedAt": "2026-04-19T14:02:00Z"
}
```

--------------------------------

### Deploy OpenComputer with deploy-qemu-dev.sh deploy

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/self-hosting/gcp-development.mdx

Builds the server, worker, and in-VM agent; builds rootfs images; installs environment files; starts services; and seeds the development API key. The first rootfs build takes several minutes and emits default.ext4 (legacy 4 GiB split-disk base) and default-merged.ext4 (unified 20 GiB base).

```bash
./deploy/gcp/deploy-qemu-dev.sh deploy
```

--------------------------------

### Start a long-running command with sandbox.exec.start

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/reference/python-sdk/exec.mdx

Starts a long-running command with streaming I/O, using callbacks for stdout, stderr, and exit. The session's `done` attribute can be awaited to get the exit code.

```python
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
```

--------------------------------

### Per-boot setup with Sandbox.create and commands

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/guides/browser-automation.mdx

Use this snippet to perform per-boot setup that depends on per-sandbox state. It creates a sandbox with a snapshot, sets environment variables to redirect Playwright/Chromium to the data disk, and runs commands to populate /etc/hosts, trust the egress-proxy CA, and create a temporary directory. The snippet includes comments explaining why each step is necessary.

```typescript
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");
```

--------------------------------

### 201 Response Example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/exec/create-session.mdx

Example of a successful 201 response from the Create Exec Session endpoint, showing the session ID, sandbox ID, command, arguments, running status, exit code, start time, and attached clients.

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

--------------------------------

### List Patches Response Example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/patches/list.mdx

Example response for the GET /api/sandboxes/checkpoints/{checkpointId}/patches endpoint. Returns a JSON array of patch objects, each containing id, checkpointId, script, description, strategy, sequence, and createdAt fields.

```json
[
  {
    "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"
  }
]
```

--------------------------------

### GET /api/sandboxes/{id}/tags - 200 Response

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/sandboxes/get-tags.mdx

Example 200 response for the Get Sandbox Tags endpoint. Shows a sandbox with tags 'env' and 'team'. A sandbox with no tags returns an empty tags object and null tagsLastUpdatedAt.

```json
{
  "tags": { "env": "prod", "team": "payments" },
  "tagsLastUpdatedAt": "2026-04-19T14:02:00Z"
}
```

--------------------------------

### List Webhooks Response Example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/webhooks/list.mdx

Example JSON response for the GET /api/webhooks endpoint. Shows a webhook destination with id 'whk_3f9a2c', name 'prod', URL 'https://app.example.com/oc-webhook', event type 'sandbox.stopped', and enabled status true.

```json
{
  "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"
    }
  ]
}
```

--------------------------------

### List Exec Sessions - Response Example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/exec/list-sessions.mdx

Example JSON response for the GET /api/sandboxes/{id}/exec endpoint. Shows a list of exec sessions with fields such as sessionID, sandboxID, command, args, running, exitCode, startedAt, and attachedClients.

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

--------------------------------

### Create a workspace with oc workspace create

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/background-agents/quickstart.mdx

Prepares a repo ahead of time: the first build clones it, runs setup, and snapshots the result, then rebuilds on every push. `oc workspace builds web` lists the builds. In v0 this step is not built yet — skip it and the session clones the repo on demand.

```bash
oc workspace create web \
  --repo github.com/acme/web \
  --setup "pnpm i && pnpm build"
```

--------------------------------

### Create a workspace with oc workspace create

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/background-agents/workspaces.mdx

Creates a workspace named 'web' for the repo github.com/acme/web. The --setup command installs and builds, --warm runs a smoke test to heat caches, and --pool 1 keeps one machine pre-booted. Pass --repo again to span multiple repos.

```bash
oc workspace create web \
  --repo github.com/acme/web \
  --setup "pnpm i && pnpm build" \
  --warm "pnpm test --filter smoke" \
  --pool 1
```

--------------------------------

### Get a snapshot by name

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/sdks/python/templates.mdx

Fetches a snapshot by its name and prints its status. The example assumes a snapshot named 'data-science' exists.

```python
snapshot = await snapshots.get("data-science")
print(snapshot["status"])  # "ready"

```

--------------------------------

### REST API: get and update repository access

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agent-sessions/api-reference.mdx

Use `GET /agents/agt_.../repository-access` to retrieve the current access and `PUT /agents/agt_.../repository-access` with a JSON body to update it. The example sets the mode to `selected` with a repository ID.

```HTTP
GET /agents/agt_.../repository-access

PUT /agents/agt_.../repository-access
Content-Type: application/json

{ "mode": "selected", "repository_ids": ["repo_..."] }
```

--------------------------------

### First deploy to dev host

Source: https://github.com/diggerhq/opencomputer/blob/main/deploy/ec2/README.md

Sources the environment file and runs the deploy script. First run takes ~10–15 minutes because the rootfs build dominates.

```bash
source ~/.opensandbox-dev.env
./deploy/ec2/deploy-qemu-dev.sh deploy     # ~10–15 min on first run (rootfs build dominates)
```

--------------------------------

### Quick example in TypeScript

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/introduction.mdx

Create a sandbox, run a command, print its stdout, and kill the sandbox using the TypeScript SDK.

```typescript
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();
```

--------------------------------

### List Agent Sessions - JSON Response Example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/agent/list.mdx

Example JSON response for the GET /api/sandboxes/{id}/agent endpoint. Returns an array of agent session objects, each containing sessionID, sandboxID, running status, startedAt timestamp, and claudeSessionID.

```json
[
  {
    "sessionID": "as-abc123",
    "sandboxID": "sb-abc123",
    "running": true,
    "startedAt": "2025-01-15T10:30:00Z",
    "claudeSessionID": ""
  }
]
```

--------------------------------

### Image.base() example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/reference/typescript-sdk/image.mdx

Starts from the default OpenSandbox environment (Amazon Linux 2023, Python, Node.js, build tools) on ARM64. Images are built ahead of time and started by name; passing an Image directly to Sandbox.create() is refused because a build takes minutes.

```typescript
import { Image } from "@opencomputer/sdk";

const image = Image.base()
  .aptInstall(['curl', 'jq'])
  .pipInstall(['requests', 'pandas'])
  .env({ PROJECT_ROOT: '/workspace' })
  .workdir('/workspace');
```

--------------------------------

### Example opencomputer.toml config

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/background-agents/agents.mdx

TOML configuration file defining name, runtime, triggers, and policies.

```toml
# opencomputer.toml
name = "fixer"

[runtime]
image = "claude"
model = "anthropic/claude-opus-4-8"

[[triggers]]
type = "github"
on = "issue.labeled:agent"

[policies]
budget.per_session_usd = 5

```

--------------------------------

### Get Usage API Response (grouped by tag:team)

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/usage/get-usage.mdx

Example JSON response from the Get Usage API when grouping by the 'team' tag. It includes total, untagged, and per-tag usage metrics such as memoryGbSeconds, diskOverageGbSeconds, and sandboxCount, along with a nextCursor for pagination.

```json
{
  "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
}
```

--------------------------------

### Initialize and log in to OpenComputer

Source: https://github.com/diggerhq/opencomputer/blob/main/README.md

Initializes a new OpenComputer agent project, installs dependencies, and logs in. Run these commands in order to set up a project for the first time.

```bash
npx @opencomputer/cli init my-agent
cd my-agent
npm install
npx --package @opencomputer/cli opencomputer login
```

--------------------------------

### GET /api/webhooks/{id} - 200 Response

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/webhooks/get.mdx

Example JSON response for a successful request. The response includes the webhook destination details, with `hasSecret` indicating whether a secret is configured. The secret itself is not returned; fetch it via `GET /api/webhooks/{id}/secret`.

```json
{
  "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"
}
```

--------------------------------

### Complete example: on-demand image and pre-built snapshot

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/sdks/typescript/templates.mdx

Shows two patterns: building an image on demand with Sandbox.create, and creating a snapshot with Snapshots.create for instant reuse. Includes cleanup via snapshots.delete.

```typescript
import { Sandbox, Image, Snapshots } from '@opencomputer/sdk';

// ── Pattern 1: On-demand image ──
const devImage = Image.base()
  .aptInstall(['curl', 'jq'])
  .pipInstall(['requests'])
  .addFile('/workspace/config.json', '{"debug": true}')
  .env({ APP_ENV: 'development' })
  .workdir('/workspace');

const sandbox = await Sandbox.create({
  image: devImage,
  onBuildLog: console.log,
});

await sandbox.commands.run('curl --version');
await sandbox.kill();

// ── Pattern 2: Pre-built snapshot ──
const snapshots = new Snapshots();

const prodImage = Image.base()
  .aptInstall(['python3-pip', 'git'])
  .pipInstall(['pandas', 'numpy', 'scikit-learn'])
  .runCommands('mkdir -p /workspace/data')
  .env({ APP_ENV: 'production' })
  .workdir('/workspace');

await snapshots.create({
  name: 'ml-env',
  image: prodImage,
  onBuildLogs: console.log,
});

// Instant — no build, just boot from snapshot
const mlSandbox = await Sandbox.create({ snapshot: 'ml-env' });
await mlSandbox.commands.run('python3 -c "import pandas; print(pandas.__version__)"');
await mlSandbox.kill();

// Cleanup
await snapshots.delete('ml-env');
```

--------------------------------

### Create Webhook - 201 Response Example

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/webhooks/create.mdx

Example JSON response for a successful webhook creation. Returns 201 without an Idempotency-Key, or 200 on an idempotent retry. Includes the generated secret (whsec_…) which is re-fetchable via GET /api/webhooks/{id}/secret.

```json
{
  "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"
}
```

--------------------------------

### oc sandbox get <id>

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/reference/cli.mdx

Shows detailed information for a sandbox, including ID, Template, Status, CPU, Memory, Started, and Ends.

```APIDOC
## oc sandbox get <id>

### Description
Shows detailed information for a sandbox, including ID, Template, Status, CPU, Memory, Started, and Ends.

### Method
CLI command

### Command
`oc sandbox get <id>`

### Parameters
#### Path Parameters
- **id** (string) - Required - The sandbox ID.
```

--------------------------------

### await sandbox.agent.start(...)

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/reference/python-sdk/agent.mdx

Starts a new agent session with the provided parameters. Returns an AgentSession object.

```APIDOC
## await sandbox.agent.start(...)

### Description
Starts a new agent session with the given prompt and configuration.

### Method
await

### Endpoint
`sandbox.agent.start`

### Parameters
#### Request Body
- **prompt** (str) - Required - Initial prompt
- **model** (str) - Optional - Claude model
- **system_prompt** (str) - Optional - System prompt
- **allowed_tools** (list[str]) - Optional - Restrict tools
- **permission_mode** (str) - Optional - Permission mode
- **max_turns** (int) - Optional - Max turns (default: 50)
- **cwd** (str) - Optional - Working directory
- **mcp_servers** (dict[str, Any]) - Optional - MCP server configuration
- **on_event** (Callable[[AgentEvent], None]) - Optional - Event callback
- **on_error** (Callable[[str], None]) - Optional - Stderr callback

### Request Example
```python
session = await sandbox.agent.start(
    prompt="Build a todo app",
    on_event=lambda e: print(e.type),
)
```

### Response
#### Success Response
- **Returns** (AgentSession) - The started agent session

### Notes
- `resume`, `on_exit`, and `on_scrollback_end` are not available in the Python SDK.
```

--------------------------------

### GET /api/sandboxes - 200 Response

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/sandboxes/list.mdx

Example 200 response from the GET /api/sandboxes endpoint. The response is a JSON array of sandbox objects. Each object includes sandboxID, status, region, workerID, tags, and tagsLastUpdatedAt. The tags field is always present, and tagsLastUpdatedAt is null when unset.

```json
[
  {
    "sandboxID": "sb-abc123",
    "status": "running",
    "region": "use2",
    "workerID": "w-use2-abc123",
    "tags": { "env": "prod" },
    "tagsLastUpdatedAt": "2026-04-19T14:02:00Z"
  }
]
```

--------------------------------

### Daily workflow: source env, deploy backend, run UI

Source: https://github.com/diggerhq/opencomputer/blob/main/deploy/ec2/README.md

Start by sourcing the environment file, then deploy backend changes with the deploy command (rsync + rebuild + restart, ~30-60s). In a separate terminal, run the UI dev server on localhost:3000. Note that deploy uses rsync --delete, so ensure parallel agents have finished editing before deploying.

```bash
source ~/.opensandbox-dev.env

# Backend changes
./deploy/ec2/deploy-qemu-dev.sh deploy     # rsync + rebuild + restart, ~30–60s

# UI iteration (separate terminal, also source the env)
cd web && npm install && npm run dev       # http://localhost:3000
```

--------------------------------

### Create a session - POST /v1/sessions

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/sessions-api/sessions.mdx

Creates a cloud sandbox, starts an AI agent with the provided prompt, and returns a session with a live preview URL. The agent begins working immediately; stream events to follow progress. The request body includes required fields 'prompt' and 'user_id', and optional 'agent_config' with default allowed_tools and cwd.

```bash
curl -X POST https://api.opencomputer.dev/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: osb_your_api_key" \
  -d '{
    "prompt": "Build a todo app with Next.js and Tailwind",
    "user_id": "user_123",
    "agent_config": {
      "system_prompt": "You are a web app builder. Work in /workspace/app.",
      "skills": {
        ".claude/skills/build-app/SKILL.md": "# Build App\n\nScaffold, install, edit, verify."
      }
    }
  }'
```

--------------------------------

### Example response for GET /api/usage/sandbox

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/api-reference/usage/get-sandbox-usage.mdx

Shows the JSON response for a sandbox usage query, including totals and per-minute points. The example uses a sandbox provisioned at 1024 MiB running for one minute, with memoryAllocatedGbSeconds of 60 and memoryUsedGbSeconds of 35.86 for a measured RSS of 612 MiB.

```json
{
  "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
    }
  ]
}
```

--------------------------------

### GET /github/deploy-app

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agent-sessions/api-reference.mdx

Returns the installed OpenComputer GitHub App and its pickable repositories. Each repository includes linked_sources[] with the owner-scoped path, production_ref, status, and owning agent.

```APIDOC
## GET /github/deploy-app

### Description
Returns the installed OpenComputer GitHub App and its pickable repositories. Each repository includes linked_sources[] with the owner-scoped path, production_ref, status, and owning agent.

### Method
GET

### Endpoint
/github/deploy-app

### Response
#### Success Response (200)
- **repositories** (array) - List of pickable repositories.
  - **id** (string) - Repository ID.
  - **full_name** (string) - Full repository name.
  - **default_branch** (string) - Default branch name.
  - **linked_sources[]** (array) - Linked sources.
    - **path** (string) - Owner-scoped path.
    - **production_ref** (string) - Production reference.
    - **status** (string) - Status of the source.
    - **agent** (object) - Owning agent.
      - **id** (string) - Agent ID.
      - **name** (string) - Agent name.

#### Response Example
{
  "repositories": [
    {
      "id": "repo_...",
      "full_name": "acme/agents",
      "default_branch": "main",
      "linked_sources": [
        {
          "path": "agents/support",
          "production_ref": "main",
          "status": "active",
          "agent": { "id": "agent_...", "name": "support-agent" }
        }
      ]
    }
  ]
}
```

--------------------------------

### Create .env file with API keys

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/guides/build-a-lovable-clone.mdx

Sets up the environment variables required for the project: ANTHROPIC_API_KEY, OPENCOMPUTER_API_KEY, and optional DEPLOY_DOMAIN. If a custom domain was configured, set DEPLOY_DOMAIN to that domain; otherwise, the default openlovable.cc is used.

```bash
ANTHROPIC_API_KEY=sk-ant-...
OPENCOMPUTER_API_KEY=your-opencomputer-token
DEPLOY_DOMAIN=mycompany.com  # optional — defaults to openlovable.cc
```

--------------------------------

### Initialize a new agent project with npx @opencomputer/cli init

Source: https://github.com/diggerhq/opencomputer/blob/main/docs/agents/quickstart.mdx

Creates a new agent project named 'my-agent' and installs dependencies. Use '.' instead of 'my-agent' to initialize an empty current directory. The initializer creates one hello-world agent.

```bash
npx @opencomputer/cli init my-agent
cd my-agent
npm install
```