You have access to the

oc

CLI for managing OpenComputer cloud sandboxes. Use it to create sandboxes, execute commands, manage checkpoints, and more.

你可以使用

oc

CLI来管理OpenComputer云沙箱，可用于创建沙箱、执行命令、管理检查点等操作。

First-time setup (run this BEFORE any other

oc

command)

首次设置（在执行任何其他

oc

命令前运行）

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?

1. 是否已安装

oc

CLI？

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.

bash

which oc

如果返回路径 → 已安装，跳至步骤2。

如果无返回/退出码非零 → 使用官方单行命令安装：

bash

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

此命令会将

oc

安装至

~/.local/bin/oc

。如果

~/.local/bin

不在用户的PATH中，请告知用户将

export PATH="$HOME/.local/bin:$PATH"

添加到其shell配置文件中，并在本次会话中使用完整路径

~/.local/bin/oc

。

2. Is the user logged in (API key configured)?

2. 用户是否已登录（API密钥已配置）？

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 (

, "unauthorized", "missing API key"):

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
```
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
```
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.

bash

oc config show

如果显示

API Key

（即使是掩码形式）→ 已登录，设置完成。

如果未设置API密钥，或沙箱命令因认证错误失败（

、"unauthorized"、"missing API key"）：

在用户浏览器中打开OpenComputer控制台，以便他们创建密钥：
- macOS：
```
open https://app.opencomputer.dev
```
- Linux：
```
xdg-open https://app.opencomputer.dev
```
在聊天中告知用户：
- 在打开的页面登录/注册
- 创建一个API密钥
- 获取密钥后在终端中运行以下命令：
  bash
```
oc config set api-key YOUR_API_KEY
```
等待用户确认已设置密钥后再继续操作。

请勿在聊天中提示用户输入密钥——他们应将密钥粘贴到自己的终端中，确保密钥不会离开本地设备。

CLI Reference

CLI参考文档

Sandbox Lifecycle

沙箱生命周期

bash

undefined

bash

undefined

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>

undefined

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

undefined

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

undefined

oc exec

默认实时流式传输stdout/stderr，并以远程进程的退出码退出。使用

--wait

进行缓冲/同步执行（使用

--json

时需要），或使用

--detach

实现即发即弃。

bash

undefined

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>

undefined

oc exec list <sandbox-id> oc exec attach <sandbox-id> <session-id> oc exec kill <sandbox-id> <session-id>

undefined

Checkpoints

检查点

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

bash

undefined

检查点会对运行中的沙箱进行快照。你可以恢复到某个检查点（原地回滚）或从检查点生成新沙箱（分叉）。

bash

undefined

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>

undefined

oc checkpoint delete <sandbox-id> <checkpoint-id>

undefined

Checkpoint Patches

检查点补丁

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

bash

undefined

补丁是从检查点生成沙箱时应用的脚本，用于自定义分叉环境。

bash

undefined

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>

undefined

oc patch delete <checkpoint-id> <patch-id>

undefined

Preview URLs

预览URL

Expose a sandbox port via a public URL.

bash

undefined

通过公共URL暴露沙箱端口。

bash

undefined

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>

undefined

oc preview delete <sandbox-id> <port>

undefined

Interactive Shell

交互式Shell

bash

undefined

bash

undefined

Open an interactive terminal session

oc shell <sandbox-id> oc shell <sandbox-id> --shell /bin/zsh

undefined

oc shell <sandbox-id> oc shell <sandbox-id> --shell /bin/zsh

undefined

Global Flags

全局标志

All commands support:

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

所有命令均支持：

```
--json
```
— 以JSON格式输出而非表格形式
```
--api-key <key>
```
— 覆盖API密钥
```
--api-url <url>
```
— 覆盖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

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

undefined

bash

undefined

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')

undefined

FORK1=$(oc checkpoint spawn $CP --json | jq -r '.sandboxID') FORK2=$(oc checkpoint spawn $CP --json | jq -r '.sandboxID')

undefined

Add a patch to customize forks

添加补丁自定义分叉环境

bash

oc patch create $CP --script ./inject-config.sh --description "Add app config"

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

undefined

undefined

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.

当需要以编程方式提取ID或字段时，请始终使用
```
--json
```
并通过
```
jq
```
解析。
沙箱ID格式为
```
sb-xxxxxxxx
```
，检查点ID为UUID。
检查点需要几秒时间变为
```
ready
```
状态，必要时可使用
```
oc checkpoint list
```
轮询。
使用完毕后请用
```
oc sandbox kill
```
清理沙箱。
```
oc exec
```
命令会以远程进程的退出码退出。

opencomputer

Original

Translation

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

首次设置（在执行任何其他oc命令前运行）

1. Is the oc CLI installed?

1. 是否已安装oc CLI？

2. Is the user logged in (API key configured)?

2. 用户是否已登录（API密钥已配置）？

CLI Reference

CLI参考文档

Sandbox Lifecycle

沙箱生命周期

Create a sandbox (returns sandbox ID)

Create a sandbox (returns sandbox ID)

List running sandboxes

List running sandboxes

Get sandbox details

Get sandbox details

Kill a sandbox

Kill a sandbox

Hibernate (saves state to S3, can wake later)

Hibernate (saves state to S3, can wake later)

Wake a hibernated sandbox

Wake a hibernated sandbox

Update timeout

Update timeout

Execute Commands

执行命令

Stream live (default)

Stream live (default)

Buffered + JSON envelope (exitCode, stdout, stderr) — required for scripting

Buffered + JSON envelope (exitCode, stdout, stderr) — required for scripting

Fire-and-forget; prints the session id so you can re-attach later

Fire-and-forget; prints the session id so you can re-attach later

Manage exec sessions

Manage exec sessions

Checkpoints

检查点

Create a checkpoint

Create a checkpoint

List checkpoints

List checkpoints

Restore sandbox to a checkpoint (in-place revert)

Restore sandbox to a checkpoint (in-place revert)

Spawn a new sandbox from a checkpoint (fork)

Spawn a new sandbox from a checkpoint (fork)

Delete a checkpoint

Delete a checkpoint

Checkpoint Patches

检查点补丁

Create a patch (reads script from file)

Create a patch (reads script from file)

Create a patch from stdin

Create a patch from stdin

List patches

List patches

Delete a patch

Delete a patch

Preview URLs

预览URL

Create a preview URL

Create a preview URL

List preview URLs

List preview URLs

Delete a preview URL

Delete a preview URL

Interactive Shell

交互式Shell

Open an interactive terminal session

Open an interactive terminal session

Global Flags

全局标志

Workflow Patterns

工作流模式

Create and use a sandbox

创建并使用沙箱

Checkpoint workflow (setup once, fork many)

检查点工作流（一次设置，多次分叉）

Create base environment

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

首次设置（在执行任何其他
`oc`
命令前运行）

1. Is the
`oc`
CLI installed?

1. 是否已安装
`oc`
CLI？