diggerhq/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 (API key configured)?

oc config show

If API Key is shown (even masked) → logged in, you're done.

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

1. Open the OpenComputer dashboard in the user's browser so they can create a key:
   • macOS: open https://app.opencomputer.dev
   • Linux: xdg-open https://app.opencomputer.dev
2. Tell the user (in chat) to:
   • Sign in / sign up at the page that just opened
   • Create an API key
   • Run this command in their terminal once they have the key:

     oc config set api-key YOUR_API_KEY
     

3. Wait for the user to confirm they've set the key before proceeding.

Do not prompt them for the key in the chat — they should paste it into their own terminal so it never leaves their machine.

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

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.