> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-oc-s-762ac928075c46d2828bcb22.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Manage sandboxes from your terminal

The `oc` CLI lets you manage OpenComputer sandboxes directly from your terminal — create sandboxes, run commands, open interactive shells, manage checkpoints, and more.

## Installation

<CodeGroup>
  ```bash macOS (Apple Silicon) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-darwin-arm64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```

  ```bash macOS (Intel) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-darwin-amd64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```

  ```bash Linux (x86_64) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-linux-amd64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```

  ```bash Linux (ARM64) theme={null}
  curl -fsSL https://github.com/diggerhq/opencomputer/releases/latest/download/oc-linux-arm64 -o /usr/local/bin/oc
  chmod +x /usr/local/bin/oc
  ```
</CodeGroup>

## Configuration

```bash theme={null}
oc config set api-key your-api-key
oc config show
```

### Resolution Order

| Priority    | Source                | Example                        |
| ----------- | --------------------- | ------------------------------ |
| 1 (highest) | CLI flags             | `--api-key=xxx`                |
| 2           | Environment variables | `OPENCOMPUTER_API_KEY`         |
| 3           | Config file           | `~/.oc/config.json`            |
| 4 (lowest)  | Defaults              | `https://app.opencomputer.dev` |

## Global Flags

| Flag        | Environment Variable   | Description                      |
| ----------- | ---------------------- | -------------------------------- |
| `--api-key` | `OPENCOMPUTER_API_KEY` | API key for authentication       |
| `--api-url` | `OPENCOMPUTER_API_URL` | Control plane URL                |
| `--json`    | —                      | Output as JSON instead of tables |

## Key Workflows

### Quick Start

```bash theme={null}
# 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
```

### JSON Output & Scripting

All commands support `--json` for machine-readable output:

```bash theme={null}
# Get a sandbox ID programmatically
ID=$(oc create --json | jq -r '.sandboxID')

# List all running sandbox IDs
oc ls --json | jq -r '.[].sandboxID'

# Run a command and capture the result
RESULT=$(oc exec $ID --json --wait -- npm test)
echo $RESULT | jq '.exitCode'
```

### Top-level Shortcuts

| Shortcut    | Expands to          |
| ----------- | ------------------- |
| `oc create` | `oc sandbox create` |
| `oc ls`     | `oc sandbox list`   |
| `oc cp`     | `oc checkpoint`     |

### Create and Shell In

```bash theme={null}
oc shell $(oc create --json | jq -r '.sandboxID')
```

### Hibernate for Cost Savings

```bash theme={null}
oc sandbox hibernate sb-abc123
# ... hours later ...
oc sandbox wake sb-abc123
oc shell sb-abc123
```

### Checkpoint and Fork

```bash theme={null}
oc cp create sb-abc --name ready-state
ID1=$(oc cp spawn cp-xyz --json | jq -r '.sandboxID')
ID2=$(oc cp spawn cp-xyz --json | jq -r '.sandboxID')
oc exec $ID1 --wait -- ./test-a.sh
oc exec $ID2 --wait -- ./test-b.sh
```

## Command Reference

| Command                                 | Description                                        |
| --------------------------------------- | -------------------------------------------------- |
| [`oc agent`](/cli/agents)               | Create, manage, connect channels, install packages |
| [`oc sandbox`](/cli/sandbox)            | Create, list, kill, hibernate, wake                |
| [`oc exec`](/cli/exec)                  | Run commands, manage exec sessions                 |
| [`oc shell`](/cli/shell)                | Interactive PTY terminal                           |
| [`oc checkpoint`](/cli/checkpoint)      | Snapshot, fork, restore                            |
| [`oc patch`](/cli/patch)                | Checkpoint-attached scripts                        |
| [`oc preview`](/cli/preview)            | Expose ports to the internet                       |
| [`oc config`](/reference/cli#oc-config) | Configure API key and API URL                      |

<Tip>
  Full flag reference for every command: [CLI Reference](/reference/cli).
</Tip>