opencomputer

You have access to the oc CLI for managing OpenComputer cloud sandboxes. Use it to create sandboxes, execute commands, manage checkpoints, and more.

First-time setup (run this BEFORE any other oc command)

Before running any sandbox command, make sure the user is set up. Do these checks in order, only fixing what's broken:

1. Is the oc CLI installed?

which oc

If it returns a path → installed, skip to step 2.

If it returns nothing / non-zero exit → install it with the official one-liner:

curl -fsSL https://raw.githubusercontent.com/diggerhq/opencomputer/main/scripts/install.sh | bash

This installs oc to ~/.local/bin/oc. If ~/.local/bin is not on the user's PATH, tell them to add export PATH="$HOME/.local/bin:$PATH" to their shell rc file, and use the full path ~/.local/bin/oc for the rest of this session.

2. Is the user logged in?

oc whoami

If it succeeds → logged in, you're done.

If it fails because no credential is configured, OR a sandbox command fails with an auth error (401, "unauthorized", "missing API key"):

1. Run:

   oc login
   

2. Relay the complete browser URL and short confirmation code printed by the command to the user.
3. Leave the command running while the user approves it in their browser. It resumes automatically after approval.

Do not ask for an API key in chat. For CI or service automation, the user may instead configure OPENCOMPUTER_API_KEY themselves.

3. Out of credits (402, insufficient_credits)

If any command fails with HTTP 402, code: "insufficient_credits", or a message mentioning "credits exhausted" / "out of prepaid credits", the organization has no prepaid credits left and every further command will fail the same way. Do not retry or work around it. Instead:

1. Stop and tell the user they've used their OpenComputer credits.
2. Relay the upgrade link from the error verbatim (it looks like https://app.opencomputer.dev/billing?plan=max). Pro is $200/month. If the error links to plain /billing instead, the org is already on Pro and its monthly credits renew next billing period.
3. Resume once they confirm they've upgraded.

When the error carries a haltReason (the trial ended, the month's minutes and credits are used, a payment failed, or the plan ended), relay the hint as is: it says why and links the Billing page, where the user picks a plan, buys credits or updates their card.

A response that carries warning: "low_credits" or a billingWarning (or a warning line after run) still succeeded — finish the task, then mention the balance and the upgrade link to the user so they can act before sessions pause.

CLI Reference

Sandbox Lifecycle

# Create a sandbox (returns sandbox ID)
oc sandbox create --timeout 300 --cpu 1 --memory 512
oc sandbox create --env KEY=VALUE --env KEY2=VALUE2
oc sandbox create --secret-store my-secrets --metadata project=demo
oc create  # shortcut

# List running sandboxes
oc sandbox list
oc ls  # shortcut

# Get sandbox details
oc sandbox get <sandbox-id>

# Kill a sandbox
oc sandbox kill <sandbox-id>

# Hibernate (saves state to S3, can wake later)
oc sandbox hibernate <sandbox-id>

# Wake a hibernated sandbox
oc sandbox wake <sandbox-id> --timeout 300

# Update timeout
oc sandbox set-timeout <sandbox-id> <seconds>

Execute Commands

oc exec streams stdout/stderr live by default and exits with the remote process's exit code. Use --wait for buffered/synchronous execution (needed for --json), or --detach to fire-and-forget.

# Stream live (default)
oc exec <sandbox-id> -- echo hello
oc exec <sandbox-id> --cwd /app -- npm install
oc exec <sandbox-id> --timeout 120 -- make build
oc exec <sandbox-id> --env NODE_ENV=production -- node server.js

# Buffered + JSON envelope (exitCode, stdout, stderr) — required for scripting
oc exec <sandbox-id> --wait --json -- whoami

# Fire-and-forget; prints the session id so you can re-attach later
oc exec <sandbox-id> --detach -- long-running-job

# Manage exec sessions
oc exec list <sandbox-id>
oc exec attach <sandbox-id> <session-id>
oc exec kill <sandbox-id> <session-id>

Checkpoints

Checkpoints snapshot a running sandbox. You can restore to a checkpoint (in-place revert) or spawn new sandboxes from one (fork).

# Create a checkpoint
oc checkpoint create <sandbox-id> --name "after-setup"

# List checkpoints
oc checkpoint list <sandbox-id>

# Restore sandbox to a checkpoint (in-place revert)
oc checkpoint restore <sandbox-id> <checkpoint-id>

# Spawn a new sandbox from a checkpoint (fork)
oc checkpoint spawn <checkpoint-id> --timeout 300

# Delete a checkpoint
oc checkpoint delete <sandbox-id> <checkpoint-id>

Checkpoint Patches

Patches are scripts applied when sandboxes are spawned from a checkpoint. Use them to customize forked environments.

# Create a patch (reads script from file)
oc patch create <checkpoint-id> --script ./setup.sh --description "Install deps"

# Create a patch from stdin
echo "apt install -y curl" | oc patch create <checkpoint-id> --script -

# List patches
oc patch list <checkpoint-id>

# Delete a patch
oc patch delete <checkpoint-id> <patch-id>

Preview URLs

Expose a sandbox port via a public URL.

# Create a preview URL
oc preview create <sandbox-id> --port 3000
oc preview create <sandbox-id> --port 8080 --domain myapp.example.com

# List preview URLs
oc preview list <sandbox-id>

# Delete a preview URL
oc preview delete <sandbox-id> <port>

Interactive Shell

# Open an interactive terminal session
oc shell <sandbox-id>
oc shell <sandbox-id> --shell /bin/zsh

Report a bug or friction (feedback.now)

If OpenComputer itself misbehaves while you work — an API call returns an unexpected error, a flag doesn't match the docs, an SDK method is confusing — report it. Reports go through the open feedback.now protocol; no API key needed and it does not interrupt your task. Prefer one precise report over many vague ones.

# Full report: --surface, --category, --severity, --title are required
oc feedback submit \
  --surface 'POST /api/sandboxes' --kind api_endpoint \
  --category bug --severity high --reproducibility always \
  --title 'create returns 500 when template is missing' \
  --summary 'Expected 404 with a clear error' \
  --evidence 'http_summary={"status":500}' --evidence stderr_excerpt=@/tmp/err.log \
  --agent-vendor <your-vendor> --agent-product <your-product> --json

# Low-confidence or minor: an observation (only --surface required)
oc feedback observe --surface 'oc sandbox create' --category friction \
  --summary '--template flag name differs from the docs'

# Later: was it accepted, folded into a known issue, or fixed?
oc feedback receipt <receipt-id> --json

• Categories: bug, docs_mismatch, friction, feature_gap, quality_degradation, other. Severities: critical, high, medium, low.
• Set --agent-vendor / --agent-product to identify yourself (e.g. anthropic / claude-code).
• Never put secrets, API keys, or customer data in --summary or --evidence.
• Works against any feedback.now host: oc feedback submit --target https://api.example.com ....

Global Flags

All commands support:

• --json — output as JSON instead of tables
• --api-key <key> — override API key
• --api-url <url> — override API URL

Workflow Patterns

Create and use a sandbox

ID=$(oc create --json | jq -r '.sandboxID')
oc exec $ID --wait -- apt update
oc exec $ID --wait -- apt install -y nodejs
oc exec $ID -- node -e "console.log('hello')"
oc sandbox kill $ID

Checkpoint workflow (setup once, fork many)

# Create base environment
ID=$(oc create --json | jq -r '.sandboxID')
oc exec $ID --wait -- apt update
oc exec $ID --wait -- apt install -y python3 pip
oc exec $ID --wait -- pip install flask

# Checkpoint it
CP=$(oc checkpoint create $ID --name "python-flask" --json | jq -r '.id')
# Wait for checkpoint to be ready
oc checkpoint list $ID

# Spawn copies from the checkpoint
FORK1=$(oc checkpoint spawn $CP --json | jq -r '.sandboxID')
FORK2=$(oc checkpoint spawn $CP --json | jq -r '.sandboxID')

Add a patch to customize forks

oc patch create $CP --script ./inject-config.sh --description "Add app config"
# All future spawns from $CP will run inject-config.sh on boot

Important Notes

• Always use --json and parse with jq when you need to extract IDs or fields programmatically.
• Sandbox IDs look like sb-xxxxxxxx. Checkpoint IDs are UUIDs.
• Checkpoints take a few seconds to become ready. Poll with oc checkpoint list if needed.
• Use oc sandbox kill to clean up sandboxes when done.
• The oc exec command exits with the remote process exit code.