opencomputer

OpenComputer のクラウドサンドボックスを管理するための oc CLI を利用できます。サンドボックスの作成、コマンドの実行、チェックポイントの管理などに使用します。

初回セットアップ（ほかの oc コマンドを実行する前に行ってください）

サンドボックスコマンドを実行する前に、ユーザーのセットアップが完了していることを確認してください。以下の確認を順番に行い、問題がある場合にのみ修正します。

1. oc CLI はインストールされていますか？

which oc

パスが返された場合はインストール済みです。ステップ 2 に進んでください。

何も返されない場合、または終了コードが 0 以外の場合は、公式のワンライナーでインストールします。

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

これにより、oc が ~/.local/bin/oc にインストールされます。~/.local/bin がユーザーの PATH に含まれていない場合は、シェルの rc ファイルに export PATH="$HOME/.local/bin:$PATH" を追加するよう伝え、このセッションの残りではフルパス ~/.local/bin/oc を使用してください。

2. ユーザーはログインしていますか（API キーが設定されていますか）？

oc config show

API Key が表示されている場合（マスクされていても）、ログイン済みです。これで完了です。

API キーが設定されていない場合、またはサンドボックスコマンドが認証エラー（401、"unauthorized"、"missing API key"）で失敗した場合：

1. ユーザーがキーを作成できるよう、ブラウザーで OpenComputer ダッシュボードを開きます。
   • macOS：open https://app.opencomputer.dev
   • Linux：xdg-open https://app.opencomputer.dev
2. チャットでユーザーに以下を伝えます。
   • 開いたページでサインイン／サインアップする
   • API キーを作成する
   • キーを取得したら、ターミナルで次のコマンドを実行する

     oc config set api-key YOUR_API_KEY
     

3. キーを設定したというユーザーの確認を待ってから続行します。

チャットでキーを尋ねてはいけません。キーがユーザーのマシンの外に出ないよう、自分のターミナルに貼り付けてもらってください。

CLI リファレンス

サンドボックスのライフサイクル

# 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>

コマンドの実行

oc exec はデフォルトで stdout/stderr をリアルタイムにストリーミングし、リモートプロセスの終了コードを返します。バッファリングされた同期実行には --wait（--json に必要）、実行を開始して待機しない場合は --detach を使用します。

# 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>

チェックポイント

チェックポイントは実行中のサンドボックスのスナップショットです。チェックポイントに復元（その場で巻き戻し）するか、そこから新しいサンドボックスを起動（フォーク）できます。

# 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>

チェックポイントのパッチ

パッチは、チェックポイントからサンドボックスを起動するときに適用されるスクリプトです。フォークした環境をカスタマイズするために使用します。

# 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>

プレビュー URL

サンドボックスのポートをパブリック 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>

対話型シェル

# Open an interactive terminal session
oc shell <sandbox-id>
oc shell <sandbox-id> --shell /bin/zsh

グローバルフラグ

すべてのコマンドで以下を使用できます。

• --json — テーブルではなく JSON で出力します
• --api-key <key> — API キーを上書きします
• --api-url <url> — API URL を上書きします

ワークフローパターン

サンドボックスを作成して使用する

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

チェックポイントのワークフロー（一度セットアップし、何度もフォーク）

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

フォークをカスタマイズするパッチを追加する

oc patch create $CP --script ./inject-config.sh --description "Add app config"
# All future spawns from $CP will run inject-config.sh on boot

重要な注意事項

• ID やフィールドをプログラムで抽出する必要がある場合は、常に --json を使用し、jq で解析してください。
• サンドボックス ID は sb-xxxxxxxx の形式です。チェックポイント ID は UUID です。
• チェックポイントが ready になるまで数秒かかります。必要に応じて oc checkpoint list でポーリングしてください。
• 作業が終わったら oc sandbox kill を使用してサンドボックスをクリーンアップしてください。
• oc exec コマンドは、リモートプロセスの終了コードを返します。