🖥️ OpenComputerの構造とデータを実装・運用目線で読み解く

OpenComputerは、AIエージェントをTypeScriptの関数として定義し、クラウド上のLinuxマイクロVMで動かすプラットフォームです。公式サイトはこれを「Firebase for agents.」と表現しています。

一見するとエージェント向けPaaSですが、内部にはKVM、QEMU、セル単位のコントロールプレーン、チェックポイント、ハイバネーション、実行中のメモリ変更まで含むサンドボックス基盤があります。本記事では、OpenComputerの公開ドキュメントとOSS実装をもとに、次の点を実装・運用目線で整理します。

• Serverless AgentsとSandboxesの関係
• HTTP、WebSocket、gRPCをまたぐ実行経路
• Project、Session、Sandbox、Checkpointのデータモデル
• SDK、CLI、HTTP APIの使い分け
• timeout、シークレット、スケール、課金で迷いやすい点
• 2026年8月26日時点で確認できる既知の問題

なお、同名の論文「OpenComputer: Verifiable Software Worlds for Computer-Use Agents」や、別作者のPyPIパッケージopencomputerとは異なる製品です。本記事で扱うPython SDKの配布名はopencomputer-sdk、import名はopencomputerです。

この記事の全体像。以下、順に解説します。

概要

OpenComputerには、大きく分けて2つの利用面があります。

1. Serverless Agents: @opencomputer/agentでエージェントを関数として定義し、CLIでデプロイする面
2. Sandboxes: 自前のエージェントハーネスからLinuxマイクロVMを直接操作する面

両者は競合する機能ではありません。Serverless Agentsの実行基盤としてSandboxesが使われ、自前ハーネスも同じ計算プリミティブを利用できます。

製品の二層

Serverless Agentsでは、会話の再開、ストリーミング、途中操作、cron、シークレット注入などをプラットフォームが管理します。Sandboxesでは、ファイルシステム、ネットワーク、プロセス空間を持つ独立カーネルのLinux VMをSDKやHTTP APIから操作します。

Durable Agent Sessionsは、ClaudeやCodexのようなランタイム向けに、永続イベントログを持つbrainと、使い捨て可能なsandboxのhandsを分ける別の利用面です。@opencomputer/agentによるServerless Agentsとは区別して理解する必要があります。

OpenComputerのOSSリポジトリはApache License 2.0です。Sandbox APIの既定エンドポイントはhttps://app.opencomputer.devです。Durable Agent Sessions SDKは別のhttps://api.opencomputer.dev/v3を既定base URLとして使います。2026年8月26日時点で、リポジトリのVERSIONは0.6.0でした。

QEMUとKVMの役割

OpenComputerはQEMUとKVMを組み合わせています。両者は代替関係ではありません。

• QEMU: ユーザー空間でVMのデバイス、I/O、ライフサイクルを管理するVMM
• KVM: Linuxカーネル内でCPU仮想化とメモリ分離を担う機構

エージェント向けサンドボックスの比較では、「KVMを使うか」だけでなく、その上のVMMがQEMU、Firecracker、Cloud Hypervisorのどれか、あるいはgVisorやコンテナ系かを見ると差を捉えやすくなります。

OpenComputerがQEMU on KVMを選ぶ理由として、公式ガイドは長さが読めないセッションへの適応を挙げています。virtio-memによる実行中のメモリ増減、hibernate / wake、長時間セッションでのRAM回収を同じ基盤で扱えるためです。

特徴

OpenComputerの特徴を、開発者から見える機能と基盤側の機能に分けると次のようになります。

特に重要なのは、CheckpointとHibernationの役割が違う点です。

Full Checkpointはディスク、メモリ、CPU状態を保存します。Disk-onlyはroot filesystemとworkspaceを保存します。一方、Checkpointからのforkで引き継ぐのはファイルシステムと導入済みパッケージであり、実行中プロセスは新しいVMにそのまま移りません。

構造

OpenComputerは、クライアント、コントロールプレーン、データプレーンの3層で捉えると理解しやすい構造です。

• クライアント → コントロールプレーン: HTTP RESTとWebSocket
• コントロールプレーン → ワーカー: gRPC
• ワーカー → VM内osb-agent: gRPC over virtio-serial

配備と障害隔離の単位はセルです。セルIDは{cloud}-{region}-{slot}形式で、たとえばazure-us-east-2-aになります。

システムコンテキスト図

この境界で重要なのは、マネージドエージェントの制御面と、公開リポジトリのサンドボックス基盤が別系統であることです。前者は後者のSandbox APIを消費します。WorkOS、決済、LLM、観測などの外部サービスは、OpenComputer本体の外側にあります。

コンテナ図

createはエッジを経由し、グローバルレジストリがセルを選びます。その後のexec、ファイルI/O、PTY、destroyは、署名付きJWTを使ってセルのコントロールプレーンへ直通します。

セルのコントロールプレーンには4つの中心責務があります。

1. Sandboxを特定ワーカーへスケジュールする
2. 各VMの所在と状態を追跡する
3. idle VMをオブジェクトストアへhibernateし、要求時にwakeする
4. リバランス時にVMをワーカー間で移行する

コンポーネント図

OSS実装では、製品名がOpenComputerでも、バイナリや環境変数に歴史的なopensandbox名が残っています。

コントロールプレーンとワーカー間の契約はproto/worker、ワーカーとVM内エージェント間の契約はproto/agentにあります。VMのNICはTAPで、outboundはiptablesのMASQUERADEです。Sandbox SecretStoreの置換プロキシは169.254.169.253:3128で動きます。

ExecのWebSocketは、先頭1バイトでストリーム種別を表します。

接続時はscrollbackが再生され、0x04の後にライブ出力が流れます。PTYは同じバイナリフレームを使いますが、ストリームプレフィックスなしの生端末データです。

データ

永続エンティティは、Serverless Agents側とSandboxes側の2群に分かれます。

• Serverless Agents: Projectを境界にAgent、Deployment、Alias、Sessionを保持
• Sandboxes: Organizationを境界にSandbox、Checkpoint、Snapshot、SecretStoreを保持

概念モデル

ProjectはServerless Agentsのクラウド境界です。Deploymentは1つのAgentの不変ビルドで、developmentやproductionのAliasが参照します。Sessionは開始時のDeploymentに固定されるため、production Aliasを更新しても既存Sessionは古いDeploymentのままです。

Sandboxはハードウェア隔離されたLinuxマイクロVMです。Checkpointは同じSandbox内で名前が一意で、PreviewURLはVM内ポートへの公開HTTPS入口です。SecretStoreはSandbox向けの暗号化シークレット集合で、egress allowlistを持ちます。

情報モデル

HTTP JSONとSDKでは、方向とキー名の両方が異なります。Createのリクエスト項目を、そのままCreateレスポンスの属性として扱わないようにします。

Createの201レスポンスには、sandboxID、status、region、workerIDが含まれ、指定時にはpreviewAuthTokenやwebhooksも加わります。templateID、diskMB、memoryMBは作成リクエストのキーです。

Sandboxの顧客向け状態はrunning、hibernated、stopped、errorです。実装内部にはpausedやpooledもありますが、制御面はpausedをhibernatedとして投影します。

Checkpointのkindはfullまたはdisk_only、statusはprocessing、ready、failedです。保持ポリシーで古いCheckpointを削除できますが、公開中、patch付き、fork参照中のものは削除対象外です。

構築方法

前提条件とバージョン

ホステッド版を使う場合はOpenComputerアカウントとAPIキーが必要です。実行環境の要件はクライアントによって異なります。

公式サイトはnpm create @opencomputer/start@latestを案内しています。npmのinitializer規則により、実際には@opencomputer/create-startが実行されます。直接初期化する場合はnpx @opencomputer/cli initも使えます。

npm install @opencomputer/sdk
npm install @opencomputer/agent
pip install opencomputer-sdk

CLIは2系統ある

コマンド名を混ぜないことが大切です。

npx @opencomputer/cli init my-agent
cd my-agent
npm install
npx --package @opencomputer/cli opencomputer login

Sandbox向けGo CLIは次のスクリプトで~/.local/binへ導入できます。

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

APIキーは環境変数から渡せます。HTTP APIではX-API-Keyヘッダです。

export OPENCOMPUTER_API_KEY=your-api-key
npx --package @opencomputer/cli opencomputer whoami
oc config show

OPENCOMPUTER_API_KEYが設定済みの状態でopencomputer loginを使う場合は、環境変数を外すか--forceが必要です。ocの設定はフラグ、環境変数、~/.oc/config.json、既定値の順に解決します。APIキーには既定値がなく、既定値があるのはAPI URLです。

セルフホストの構成

セルフホストには、KVMを利用できるworker、PostgreSQL、Redis、S3互換オブジェクトストレージが必要です。workerイメージにはQEMU、opensandbox-worker、osb-agent、kernel、rootfsを含めます。

最短の確認は、serverのhealth、Sandbox作成、VM内execの順です。

curl -sf "$OPENCOMPUTER_URL/health"

SBX=$(curl -s -X POST "$OPENCOMPUTER_URL/api/sandboxes" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
  -d '{"templateID":"default"}' | jq -r .sandboxID)

curl -s -X POST "$OPENCOMPUTER_URL/api/sandboxes/$SBX/exec" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
  -d '{"cmd":"uname -a && pwd && date"}'

ここには命名上の差があります。SandboxドキュメントとSDKの既定templateは"base"ですが、SELFHOSTING.mdのsmoke testは"default"を送ります。セルフホスト時は、自分の環境に登録されたtemplate名を確認してください。

本番では、HTTPS終端、複数のcontrol-plane replica、failure domainを分けたworker、managed Postgres / Redis、オブジェクトストレージを用意します。単一ホスト構成は開発確認向けです。

利用方法

Serverless Agentsをデプロイする

エージェントはopencomputer/agents/<agent-id>/agent.tsに定義します。ローカルのagent serverを常駐させるのではなく、managed development cloudへデプロイします。

import { useInput, useModel } from "@opencomputer/agent";

export default function Agent() {
  const input = useInput();
  useModel("anthropic/claude-sonnet-4.6");

  return input.text
    ? `Help the user with this request: ${input.text}`
    : "You are a helpful assistant.";
}

npm run deploy -- --watch
npm run deploy -- --alias production
npm run session -- --agent hello-world "Say hello"
npx --package @opencomputer/cli opencomputer logs --follow

クライアントからはagent-id@aliasで指定します。hello-world@developmentのような形です。production Aliasを切り替えても、既存Sessionは開始時のDeploymentを使い続けます。

Toolはagents/<agent>/tools/*.tsへ置きます。agent.ts内に直接書いたdefineToolがデプロイ成果物から落ちる既知の問題があるためです。

// opencomputer/agents/support/tools/lookup-order.ts
import { defineTool } from "@opencomputer/agent";

export const lookupOrder = defineTool({
  name: "lookup_order",
  description: "Look up an order by ID",
  input: {
    type: "object",
    properties: { orderId: { type: "string" } },
    required: ["orderId"],
    additionalProperties: false,
  },
  async run({ input }) {
    return { orderId: String(input.orderId), status: "processing" };
  },
});

MCP serverはdefineMcpServer、同じProject内の別AgentはuseSubagent(agentId)で接続できます。Skillはopencomputer/agents/<agent-id>/skills/<skill>/SKILL.mdへ置きます。

Sandboxを作成してコマンドを実行する

現行APIはsandbox.exec.run()です。一部の古いIntroductionにはcommands.runが残っていますが、新しいコードではexecを使います。

import { Sandbox } from "@opencomputer/sdk";

const sandbox = await Sandbox.create({
  template: "base",
  timeout: 600,
  cpuCount: 1,
  memoryMB: 4096,
  diskMB: 20480,
  envs: { NODE_ENV: "production" },
});

const result = await sandbox.exec.run("echo Hello from $(uname -a)");
console.log(result.stdout);
await sandbox.kill();

from opencomputer import Sandbox

async with await Sandbox.create(timeout=600) as sandbox:
    result = await sandbox.exec.run("echo Hello from $(uname -a)")
    print(result.stdout)

Pythonには注意が必要です。PyPI 0.6.9と公式Python SDKリファレンス、GitHub mainの実装には差があります。ホステッド版でコピー可能な例はPyPI版に合わせ、hibernate()やwake()などGitHub mainの先行実装を使う場合はコミットSHAを固定するのが安全です。

Checkpointから環境を分岐する

const sandbox = await Sandbox.create();
await sandbox.exec.run("npm install && npm run build", { cwd: "/app" });

const checkpoint = await sandbox.createCheckpoint("after-build");
const experimentA = await Sandbox.createFromCheckpoint(checkpoint.id);
const experimentB = await Sandbox.createFromCheckpoint(checkpoint.id);

await sandbox.restoreCheckpoint(checkpoint.id);

Checkpoint名はSandbox内で一意です。重複はHTTP 409になります。分岐後のVMはディスク状態から新しくbootするため、元VMの実行中プロセスを前提にしないでください。

HibernateとWakeを使う

await sandbox.hibernate();
await sandbox.wake({ timeout: 600 });

curl -X POST "https://app.opencomputer.dev/api/sandboxes/$SBX/hibernate" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY"

curl -X POST "https://app.opencomputer.dev/api/sandboxes/$SBX/wake" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout":600}'

wake()はまずsnapshot resumeを試し、失敗時は保存ディスクからのcold bootへフォールバックします。Sandbox IDとPreview URLは変わりません。

Preview URLを保護する

Preview URLは既定では公開です。外部公開するサービスでは、Sandbox作成時にbearer認証を明示します。

const sandbox = await Sandbox.create({
  previewAuth: { scheme: "bearer", token: "auto" },
});

console.log(sandbox.previewAuthToken);

curl -H "Authorization: Bearer $TOKEN" \
  https://sb-abc123-p3000.workers.opencomputer.dev/

平文トークンはcreateまたはrotateの応答で一度だけ返り、サーバ側にはSHA-256ハッシュが保存されます。安全な場所へ直ちに保存してください。

シークレットを実行環境から分離する

Serverless Agentsのmanaged secretは、defineConnectionで定義したHTTPS originへの送信時にだけ注入されます。ランタイム環境変数、プロンプト、ログから秘密を切り離せます。

import { bearer, defineConnection, useSecret } from "@opencomputer/agent";

const github = defineConnection({
  id: "github-api",
  origin: "https://api.github.com",
  methods: ["GET"],
  pathPrefix: "/repos/",
  headers: {
    Authorization: bearer(useSecret("GITHUB_TOKEN")),
    "User-Agent": "my-opencomputer-agent",
  },
});

Sandbox SecretStoreでは、VM内にはosb_sealed_*形式の封印トークンだけが入ります。許可されたHTTPS hostへの送信時に、worker上のプロキシが実値へ置換します。

import { Sandbox, SecretStore } from "@opencomputer/sdk";

const store = await SecretStore.create({
  name: "my-agent-secrets",
  egressAllowlist: ["api.anthropic.com"],
});

await SecretStore.setSecret(store.id, "ANTHROPIC_API_KEY", "sk-ant-...", {
  allowedHosts: ["api.anthropic.com"],
});

const sandbox = await Sandbox.create({
  secretStore: "my-agent-secrets",
  timeout: 600,
});

運用

timeoutは必ず明示する

公式資料にはidle timeoutの既定値が2通りあります。

ドキュメント差に依存しないよう、作成時または実行後に用途別の値を明示します。

const sandbox = await Sandbox.create({ timeout: 600 });
await sandbox.setTimeout(3600);
await sandbox.setTimeout(0); // persistent

always-on以外で0を使うと、不要なmachine timeを消費しやすくなります。対話開発なら600〜3600秒、短命なバッチやテストなら60〜300秒を起点に調整します。

状態と実エラーを確認する

oc ls
oc sandbox get sb-abc123
oc exec sb-abc123 --wait -- journalctl --no-pager -n 50
npx --package @opencomputer/cli opencomputer logs --follow

失敗ターンの詳細がCLIのlogsに出ず、managed sessionのevents APIにだけ出る既知の問題があります。表面的なメッセージしか見えない場合は、次のAPIを確認します。

GET /api/managed-agents/sessions/{id}/events?after=0

セルフホストではserverとworkerの両方を確認します。

sudo journalctl -u opensandbox-server -n 100 --no-pager
sudo journalctl -u opensandbox-worker -f

live resizeとautoscale

autoscaleはSandbox単位のopt-inです。CPUはメモリに比例し、公開されている主なティアは次の通りです。

await sandbox.setAutoscale({
  enabled: true,
  minMemoryMB: 1024,
  maxMemoryMB: 16384,
});

await sandbox.scale({ memoryMB: 4096 });

scale upは1分平均のメモリ使用率が75%を超えると次ティアへ進み、cooldownは60秒です。scale downは1分、5分、15分平均がすべて25%未満で1ティア下がり、cooldownは5分です。明示的なscaleはautoscaleを無効化します。

縮小先がworking setを下回るとHTTP 409 oom_floor、lock中は403 scaling_locked、プラン上限超過は402になります。

課金を見積もる

2026年8月26日時点の公式サイトでは、モデル料金のパススルーとmachine timeが別メーターです。BYOモデルキーではtoken meterが0になり、bare Sandboxではmachine timeだけが対象です。

Agentの既定マシンは2GB / 1 vCPUで、$0.00315/分です。hibernate中はcompute課金が止まります。課金粒度は10秒ハートビートを秒単位へ集約します。

価格、プラン、制限は変わりやすいため、本番導入時は公式Pricingを再確認してください。

Burst Sandboxesを再実行可能にする

alphaのBurst Sandboxesはburst: trueで作成します。ディスクはインフラ再起動をまたいで残りますが、プロセス、メモリ、端末、接続は再起動する可能性があります。再起動通知がある場合、ゲストには最大25秒のflush時間があります。

環境変数OPENSANDBOX_RESUMABLE=trueとOPENSANDBOX_RESUME_NOTICE_SECONDS=25を確認し、/home/sandbox/.opencomputer/on-restart-noticeへflush hookを置きます。CI、バッチ、探索処理のように再実行可能なワークロード向けです。

ベストプラクティス

CI/CD

• developmentの--watchとproduction Aliasを分離する
• productionはdeploy --alias productionで不変Deploymentを切り替える
• 切り替え後の確認は新規Sessionで行う
• CIのsecret値はコマンド引数ではなく標準入力から渡す
• Toolはagents/<agent>/tools/*.tsへ置く
• Reserved Capacityの書き込みには決定的なIdempotency-Keyを付ける

マルチ環境

Agentの環境はdevelopmentとproductionを基本にし、secretsとruntime variablesを分けます。クライアントはagent-id@aliasで環境を固定します。

基盤側はセルID{cloud}-{region}-{slot}でfailure domainを表します。開発セルは単一ホストでも構築できますが、本番ではcontrol plane、worker、Postgres、Redis、Object Storeの障害境界を分けます。

リソース制限

• idle timeoutを必ず用途別に明示する
• autoscaleのmin/maxは公開ティアから選ぶ
• ベンチマーク中や固定課金が必要な場合だけscaling lockを使う
• 重いビルド前にVM内metadata APIでscale upし、終了後に下げる
• Burstには再実行可能な処理だけを載せる
• 20GBを超えるdiskが必要なら超過課金とclosed beta条件を確認する

セキュリティ

• managed secretをHTTPS originとmethod、path prefixに束縛する
• runtime variableとmanaged secretを用途で分ける
• Preview URLにはbearer認証を明示する
• create / rotateで一度だけ返るトークンをdurable storeへ保存する
• worker RPC、Postgres、Redisをprivate networkへ閉じる
• セルフホストの秘密はKey VaultやSecrets Managerから供給する
• GitHub API向けConnectionにはUser-Agentを明示する

設定管理

主な環境変数にはOPENSANDBOX_*プレフィックスが付きます。

秘密値と非秘密値を分け、server用とworker用の設定ファイルも分離します。Postgresを直接変更する運用は避け、公開APIとCLIを正とします。

トラブルシューティング

問題が起きたら、認証、Sandbox状態、worker登録、VM内プロセスの順に切り分けます。

oc config show
oc sandbox get sb-abc123
oc exec sb-abc123 --wait -- ps aux
oc exec sb-abc123 --wait -- journalctl --no-pager -n 50

頻出エラー

2026年8月26日時点の既知の問題

運用に影響しやすいopen issueは次の通りです。状態は変わるため、導入時に各issueを再確認してください。

セルフホストで/dev/kvmが無い場合は、ホストとクラウドインスタンスのnested virtualizationを確認します。Local SSD上のSandbox diskはインスタンス停止や置換で消えるため、CheckpointやHibernationを検証する前にObject Storeを設定してください。

まとめ

OpenComputerは、TypeScriptで定義するServerless Agentsと、QEMU on KVMで動くLinux Sandboxesを重ねたプラットフォームです。エージェントAPIだけを見るよりも、セル、コントロールプレーン、worker、VM内osb-agent、Object Storeまでを一続きの構造として捉えると、Checkpoint、Hibernation、live resize、secret injectionの設計意図が見えます。

実装時には、opencomputerとocの2系統のCLI、HTTP JSONとSDKのキー差、PyPI版とGitHub mainのPython SDK差に注意が必要です。運用時にはtimeoutを明示し、Preview URLを保護し、autoscaleとlockの相互作用を監視してください。特に公式資料間で既定値が揺れている項目は、コード側で値を固定するのが安全です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• OpenComputer公式サイト
• OpenComputer Introduction
• How it works
• Serverless Agents Overview
• Sandboxes Overview
• GitHub diggerhq/opencomputer
• SELFHOSTING.md
• Checkpoints
• Elasticity
• Timeout
• Preview URLs
• TypeScript SDK
• Python SDK
• HTTP API
• Troubleshooting
• QEMU vs KVM