# 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. Use when this capability is needed. - Skill: `tomevault-io/opencomputer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/opencomputer` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/opencomputer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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 (API key configured)? ```bash 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: ```bash 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 ```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. --- > Source: [diggerhq/opencomputer](https://github.com/diggerhq/opencomputer) — distributed by [TomeVault](https://tomevault.io).