# Opencomputer > Manage OpenComputer cloud sandboxes. Use when the user wants to create, run commands in, checkpoint, or manage sandbox environments. Auto-invokes when sandboxes, remote environments, or the oc CLI are mentioned. - Skill: `diggerhq/opencomputer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add diggerhq/opencomputer` - Raw SKILL.md: https://api.skillmd.com/api/skills/diggerhq/opencomputer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: diggerhq (https://skillmd.com/u/diggerhq) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/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? ```bash 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: ```bash 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? ```bash 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: ```bash 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. ## CLI Reference ### Sandbox Lifecycle ```bash # 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 # Kill a sandbox oc sandbox kill # Hibernate (saves state to S3, can wake later) oc sandbox hibernate # Wake a hibernated sandbox oc sandbox wake --timeout 300 # Update timeout oc sandbox set-timeout ``` ### 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. ```bash # Stream live (default) oc exec -- echo hello oc exec --cwd /app -- npm install oc exec --timeout 120 -- make build oc exec --env NODE_ENV=production -- node server.js # Buffered + JSON envelope (exitCode, stdout, stderr) — required for scripting oc exec --wait --json -- whoami # Fire-and-forget; prints the session id so you can re-attach later oc exec --detach -- long-running-job # Manage exec sessions oc exec list oc exec attach oc exec kill ``` ### Checkpoints Checkpoints snapshot a running sandbox. You can restore to a checkpoint (in-place revert) or spawn new sandboxes from one (fork). ```bash # Create a checkpoint oc checkpoint create --name "after-setup" # List checkpoints oc checkpoint list # Restore sandbox to a checkpoint (in-place revert) oc checkpoint restore # Spawn a new sandbox from a checkpoint (fork) oc checkpoint spawn --timeout 300 # Delete a checkpoint oc checkpoint delete ``` ### Checkpoint Patches Patches are scripts applied when sandboxes are spawned from a checkpoint. Use them to customize forked environments. ```bash # Create a patch (reads script from file) oc patch create --script ./setup.sh --description "Install deps" # Create a patch from stdin echo "apt install -y curl" | oc patch create --script - # List patches oc patch list # Delete a patch oc patch delete ``` ### Preview URLs Expose a sandbox port via a public URL. ```bash # Create a preview URL oc preview create --port 3000 oc preview create --port 8080 --domain myapp.example.com # List preview URLs oc preview list # Delete a preview URL oc preview delete ``` ### Interactive Shell ```bash # Open an interactive terminal session oc shell oc shell --shell /bin/zsh ``` ### Global Flags All commands support: - `--json` — output as JSON instead of tables - `--api-key ` — override API key - `--api-url ` — override API URL ## Workflow Patterns ### Create and use a sandbox ```bash 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) ```bash # 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 ```bash 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.