🖥️ Cua Spacesの構造とデータから読む、エージェント用デスクトップの導入と運用

AI エージェントに GUI を操作させたいとき、手元の画面をそのまま渡すのは不安があります。
Cua Spaces は、エージェント専用のデスクトップを用意し、人がその画面を見守れるようにする仕組みです。
この記事では、Cua Spaces の構成要素、扱うデータ、導入から運用までを、公式ドキュメントとリポジトリ trycua/cua に沿って整理します。
記載は 2026-10-07 時点の公開情報にもとづきます。

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

Cua Spacesとは

Cua Spaces は、エージェントが操作し、人が画面を見守れるデスクトップです。
1 つの Space は、仮想マシンまたはコンテナとして動く、完結したデスクトップです。

Space を動かせる場所は次の 4 つです。

配布物は 2 層に分かれます。

• macOS 26 以降向けの Spaces アプリ。2026-10-05 公開の cua-spaces-v0.7.2 が最新です。
• 同じリポジトリの cua CLI、cua daemon、Cua Driver、Lume、言語 SDK。これらは MIT です。

ゲストの中では cua-spacesd が TCP 3211 と UDP 3212 で待ち受けます。
ポインタとキーボードの注入は Cua Driver が担います。cua-spacesd 自身は入力を注入しません。

アカウントと料金の扱いは次のとおりです。

ライセンスはパスで分かれます。
ルートの LICENSE.md は MIT です。Spaces 系のパスは FSL-1.1-MIT で、各リリースは 2 年後に MIT になります。
主なパスは次のとおりです。正本は LICENSING.md です。競合利用の商用条件は COMMERCIAL.md を確認してください。

2026-10-07 に GitHub API で取得したリポジトリの指標です。

特徴

• Space の ID は、実行場所を接頭辞で表します。local:、direct:、relay:、cloud: の 4 種です。
• 配置は 3 軸で決まります。on が場所、kind が container か vm、runtime がエンジンです。
• ゲストの制御面は cua-spacesd です。契約は cua.env.v1 の protocol version 1、revision 8 です。
• メディアの経路は 2 つです。UDP 3212 の QUIC（ALPN rcdp/2）と、TCP 3211 のチケット付き WebSocket GET /media です。
• 環境トークンは URL に載せません。ブラウザはチケットと署名付き URL を使います。
• ホストのエージェントは cua daemon mcp または cua mcp 経由でツールを呼びます。
• Space の中で起動できる準備済みの harness は claude-code と openai-codex です。
• Cua Volume は版管理された共有ドライブです。削除は削除マーカーで表し、履歴は残ります。
• Teleport は、同意を経てセッションを Space へ渡します。イメージ同梱のバンドルは cua-machine-seal で封緘されます。
• 匿名テレメトリは既定でオンです。DO_NOT_TRACK=1 で確実に止まります。
• 実験フラグ cua_volume、your_cloud、sharing は Settings の Experiments にあります。オフにしても入口が隠れるだけで、既存のマウント、接続、共有は残ります。

公式のイメージカタログ（SDK quickstart）は次のとおりです。

Linux イメージのログインユーザは cua です。パスワードなしの sudo を持ちます。

構造

システムコンテキスト図

利用者、ホスト上のエージェント、Spaces、リレー、自分のクラウドの関係です。

手元の Space と、アドレスで直結した Space はリレーを通りません。
自前クラウドのサンドボックスは受信ポートを開かず、relay.cua.ai へ外向きに接続します。
リレーは TLS を終端します。通過中の画面、入力、ファイルを読める位置にありますが、保存はしません。
Teleport の封緘バンドルはリレーから読めない、と cua-machine-seal の説明にあります。

コンテナ図

1 台のホストと、1 つのゲストの境界です。

ホスト側で押さえておくファイルは次のとおりです。

コンポーネント図

cua-spacesd が公開する主な面です。

認証と待ち受けの規則は次のとおりです（libs/cua-spacesd の README）。

• トークンのヘッダは authorization: Bearer または x-cua-env-authorization: Bearer です。
• フリートのゲートウェイは authorization を消費します。その先では代替ヘッダを使います。
• 既定の待ち受けは、トークンがあるとき 0.0.0.0:3211、無いとき 127.0.0.1:3211 です。
• ループバック以外をトークンなしで開くことは、既定では拒否されます。
• --insecure-bootstrap を付けたときだけ、トークンなしの非ループバックを許します。このとき応答するのは GetCapabilities、Health、Init だけです。
• gRPC-Web はクライアントストリームを運べません。StreamInput の代わりに SendInput、WriteFile の代わりに UploadChunk を使います。
• チケットは ?ticket= か、WebSocket サブプロトコル cua.ticket. に続けて渡します。
• トークンを回すと、そのトークン由来のチケットと署名 URL は失効します。

RPC の数は protocol ページ の表のとおりです。

StreamService のチケット型は、MIT の cua-proto にあります。

データ

概念モデル

Space にぶら下がる主な記録です。

配置は次の順で解決されます。

1. 呼び出し時の明示
2. 環境変数 CUA_DEFAULT_ON と、kind・runtime 用の同系統の環境変数
3. 設定の default.on
4. 組み込みの既定値（local / auto / auto）

不正な組み合わせは InvalidPlacement になります。
kind=auto では、macOS と Windows のイメージは VM、コンテナ rootfs はコンテナ、ディスクだけのイメージは VM になります。

情報モデル

公開レコードのうち、運用でよく読むものだけをクラス図にしました。メソッドは省いています。

Space.info は接続時のスナップショットです。spacesd があると、handshake で得た OS 関連の値がレコードの値を置き換えます。
Spaces.list と Spaces.resolve は、レジストリ上のレコードをそのまま返します。

Volume まわりの値は次のとおりです（volume、volume-sync）。

サンドボックスの状態は provisioning、starting、ready、stopped です。
作成の進捗フェーズは preparing、pulling、creating、booting、waiting_for_services、connecting の順に進みます。

導入

前提

アプリと CLI

macOS と Linux は同じ 1 行でインストールします。Windows は PowerShell を使います。

curl -fsSL https://cua.ai/install.sh | sh

irm https://cua.ai/install.ps1 | iex

インストーラのフラグは --select、--only、--cli-only、--app-only、--mode（host または client）、--version、--no-onboarding、--dry-run、--yes です。
Mac のアプリだけが欲しい場合は、Release cua-spaces-v0.7.2 の DMG か .pkg を使えます。

インストール後は次のコマンドで確認します。

cua --version
cua auth status
cua spaces ls

Python と TypeScript

SDK は用途で入口が分かれます。

pip install cua-sandbox

npm install @trycua/cua

既存の Space をアドレスとトークンで登録し、コマンドを実行する例です。

import asyncio
import cua

async def main():
    spaces = cua.embedded().spaces()
    info = await spaces.add("http://10.0.0.5:3211", "TOKEN", "lab")
    space = await spaces.space(info.id)
    out = await space.bash("uname -a", None)
    print(info.id, out.stdout)

asyncio.run(main())

高レベル API で直結する場合は次のように書きます。

from cua_sandbox import Sandbox

async with Sandbox.connect(url="http://127.0.0.1:3211", token="TOKEN") as sb:
    print(sb)

import { embedded } from "@trycua/cua"

const sandbox = await embedded().sandboxes().connectUrl(url, token, "dev")

ローカルランタイム

ランタイムの診断と導入は cua runtime で行います。名前を渡せる対象は qemu、lume、container です。

cua runtime doctor
cua runtime setup --dry-run
cua runtime setup
cua runtime setup lume

Docker で Linux デスクトップを起動する公式例です。
トークンは環境変数で渡し、ホスト側のポートはループバックに限定します。

TOKEN=$(openssl rand -hex 24)
docker run -d --name my-space -e CUA_ENV_TOKEN=$TOKEN -p 127.0.0.1:3211:3211 ghcr.io/trycua/linux:24.04

後片付けは docker rm -f my-space です。

• SDK や CLI でローカルに作るとき、Linux コンテナのランタイムは自動選択です。gVisor が入っていれば gVisor、無ければ runc になります。
• 上の docker run 例は gVisor を指定していないため、Docker の既定ランタイムで動きます。
• Cua Cloud の ghcr.io/trycua/linux:24.04 は gVisor コンテナで動きます。
• --kind vm を付けるとディスク付きバリアントが選ばれます。手元は QEMU、Cua Cloud は KubeVirt です。

利用方法

配置

配置の 3 軸が取る値は次のとおりです。

SDK のイメージ指定は次のように書きます。

CLI の対応フラグは --on、--kind、--runtime です。
cua spaces create はイメージを位置引数に取ります。省略すると正規の Linux になります。
ほかに --name、--count（1〜8）、--cpus、--memory-mb、--disk-gb、--gpu があります。

作成

このマシンに Linux を作り、自前の AWS にもう 1 つ作る例です。

cua spaces create linux
cua spaces create linux --on aws --name research
cua sb create linux --kind vm --name dev-vm
cua sb create macos:tahoe --name mac

Python で場所を省略すると、このマシンの正規 Linux になります。

import asyncio
import cua

async def main():
    spaces = cua.embedded().spaces()
    created = await spaces.create(cua.SpaceCreateOptions())
    print(created.space.id)
    await spaces.delete(created.space.id)

asyncio.run(main())

作成のキャンセルは cua spaces cancel local:space-1a2b3c か、SDK の cancel_create です。

• 結果は cancelled、not_creating、already_created のいずれかです。
• キャンセルされた作成は CuaError.Cancelled で失敗します。Ctrl-C の CLI 終了コードは 130 です。
• 取得済みのイメージレイヤはキャッシュに残ります。

登録

既にあるマシンは URL とトークンで登録します。登録はリモートの作成や削除をしません。

cua spaces add 10.0.0.5:3211 --token "$CUA_ENV_TOKEN" --name studio

cua sb create --on direct:10.0.0.5:3211 --token "$CUA_ENV_TOKEN"

スペアの Mac をリレー経由で提供するときは --profile spare を使います。
これは --no-desktop --provide-spaces と同じ意味です。

cua host setup --profile spare --name "Mac mini spare"
cua spaces create macos:26 --on host:0123abcd4567ef89

リレーを使わない直接待ち受けは、信頼できる LAN か Tailscale 向けです。待ち受けは平文 HTTP です。

cua host setup --direct 100.101.102.103:3211 --profile spare --name "Mac mini spare"
cua spaces add 100.101.102.103:3211 --host --name "Mac mini spare" --token "$CUA_ENV_TOKEN"

削除系の操作は意味が分かれます。

エージェント接続

ホストのエージェントを検出して、MCP を設定します。

cua agents detect
cua agents setup --agents claude,codex --yes
cua agents status

手作業で MCP を登録する例です。

claude mcp add cua -- cua daemon mcp
claude mcp add cua -- cua mcp --sandbox dev --permissions sandbox:readonly,computer:all

--sandbox または環境変数 CUA_SANDBOX が、コンピュータツールの既定の操作対象になります。
権限グループ（CUA_MCP_PERMISSIONS）は次のとおりです（MCP server ガイド）。

• 空のリストだけがすべてを許可する、と公式が警告しています。
• 未知の権限名は警告して読み飛ばします。
• 有効な権限が 1 つも残らないと、ツールは登録されません。
• 破壊的な操作として名指しされているのは computer:shell、computer:file、spaces:space_bash、spaces:teleport_app、sandbox:delete、spaces:delete_space です。
• 座標は、直前の computer_screenshot の画素空間です。長辺は 1200 px が上限です。

ホスト側のセットアップ文書は、Claude Code、Codex、Cursor、Gemini CLI、Cline、Kiro、OpenClaw、OpenCode、Pi、Windsurf、Devin、Copilot CLI、Amp、Goose、Zed、VS Code、Google Antigravity、Hermes の設定場所を挙げています。
このうち Pi は MCP を持たない、と文書に書かれています。

Space 内エージェント

ゲストの中でエージェントを走らせるツール群です。
agent_capabilities が返す準備済み harness は claude-code と openai-codex だけです。

ホスト側の MCP 接続と、ゲスト内の harness は別の一覧です。
use-from-an-agent ガイド が名前を挙げるツールは、list_spaces、create_space（reuse）、space_bash、send_file、stream_endpoint、list_tools、call_tool、delete_space、add_space、remove_space、teleport_manifest、teleport_app です。

機能が足りないときのエラーは 2 種類です。

• ゲストに機能が無いときは capability_missing です。
• ホスト側（アプリセッション、オペレータ表示、ローカルランタイム、未登録のストリームクライアント）に無いときは host_capability_missing です。どの拡張も提供しないツールは Cua Spaces に同梱される、とメッセージが案内します。

デスクトップとファイル

send_file はホストのファイルをゲストの ~/Downloads へ置き、SHA-256 で検証します。
Teleport ゾーンへドロップしたファイルも同じ検証を通ります。

await space.send_file(path, cua.SpaceSendFileOptions(target_directory="inbox"))

cua sb screenshot mac -o desktop.png
cua sb view mac

画面ストリームを開く SDK の例です。

opts = cua.SpaceStreamOptions(app_name="Firefox", audio=True, max_fps=30, codecs=["h264"])
ticket = await space.open_stream(opts)

Teleport は同意を必須にしています。

• 初回の teleport_app は consent_required を返し、自分では承認しません。
• 同意のフィールドは request_id、scope（full または tabs）、include（マニフェスト内の相対パス）、acknowledge_sensitive です。
• 空の include は拒否されます。

GPU の扱いは環境で分かれます。

運用

起動とログイン

アプリの初回起動は、Welcome、Command line、Sign in、AI agents、This machine、Done の順に進みます。

• This machine では、他のマシンへアクセスするか、このマシンを無人アクセス用に提供するかを選びます。無人側は cua host setup --provide-spaces です。
• Screen Recording と Accessibility の許可は利用者が与えます。プログラムからは付与しません。
• ログイン時の自動起動を選べます。
• Windows では、メインウィンドウを閉じても隠れるだけです。
• Settings の AI agents は cua agents setup を実行します。
• デバッグ用に、CUA_SPACES_START_VIEW で開始画面を new-space か settings にできます。

Cua Cloud の資格情報は次の優先順で使われます。

1. サインイン済みユーザ（デバイス認可）
2. 環境変数の静的ベアラ FLEETS_TOKEN
3. 環境変数 CUA_CLIENT_ID と CUA_CLIENT_SECRET

トークン URL の既定は https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token です。

cua auth login
cua auth status

初回インストールモードの記録は ~/.cua/spaces-install-mode です。
Windows は %USERPROFILE%\.cua\spaces-install-mode、MSI では %ProgramData%\Cua\spaces-install-mode です。
マシン全体の設定は /Library/Application Support/Cua/ または /etc/cua/ に置きます。

電源

Spaces.stop の意味は場所で分かれます。

cua spaces stop local:dev
cua spaces start local:dev

• start は再開または起動です。
• 高レベル API のローカル suspend / resume は手元だけで使えます。
• クラウドの suspend と restart は Unsupported です。
• 短命サンドボックスはハンドルとともに消えます。
• プロセスが落ちた場合は、次の cua sb かデーモンが 10 分後に回収します。分数は CUA_ORPHAN_REAP_MINUTES で変えられます。

テレメトリ

匿名テレメトリは既定でオンです（telemetry）。

止めるときは次のコマンドを使います。DO_NOT_TRACK=1 は他の設定より優先されます。

cua telemetry off
cua config set telemetry off

SDK からは cua.telemetry.disable() と telemetrySetEnabled(false) で止めます。
CUA_TELEMETRY=0 や、旧来の CUA_TELEMETRY_ENABLED=false、CUA_DRIVER_RS_TELEMETRY_ENABLED=false も有効です。

ディスク

イメージ、VM ディスク、ログは ~/.cua の下に置かれます（disk-usage）。

• キャッシュ予算は、30 GiB と空きの 10% のうち小さい方です。
• prune で消さないものは、動作中・停止中のサンドボックス、サンドボックスが使うもの、チェックポイント、SDK が作っていない Docker オブジェクトです。
• ログは 1 ファイル 10 MiB が上限です。
• スクリーンショットは ~/.cua/screenshots に新しい 20 枚だけを残します。

cua cache du
cua cache prune --dry-run
cua cache prune
cua cache config --budget 50G --min-free 10G

空きが足りない作成は CuaError.InsufficientDisk で止まります。CLI の終了コードは 7 で、何も書き込みません。

自前クラウドの寿命

接続、試験、状態確認、掃除のコマンドです（your-cloud）。

cua cloud connect aws --region us-west-2 --default
cua cloud test aws
cua cloud status
cua cloud sweep --delete

• cua cloud disconnect は接続情報を忘れるだけで、クラウド上の資源は消しません。
• cua cloud sweep --delete は、この所有者のタグが付いた資源だけを消します。タグは cua-managed=true、cua-owner、cua-space、cua-machine、cua-created-by、cua-expires です。
• IAM ユーザは作りません。既存のネットワーク、セキュリティグループ、ファイアウォール規則は変更しません。

事業者ごとに作られる資源は次のとおりです（your-cloud-resources）。

寿命の規則は次のとおりです。

• 既定の TTL は 8 時間です。--ttl-hours で変更し、0 は削除するまで残します。
• TTL が来ると、サンドボックスは自分で削除します。
• AWS と Google Cloud では、TTL の前に stop と start を使うとディスクが残ります。
• Modal は stop / start ができず、上限は 24 時間です。/dev/kvm が無いため Linux イメージだけが動きます。
• Windows、Omarchy、macOS は自前クラウドでは未提供です。AWS で macOS を出すには EC2 Mac の専用ホスト（最小 24 時間）が必要です。
• 失敗は CuaError.Cloud になります。

cua cloud status が示す、稼働中の計算とディスクの概算です。ネットワーク費用は含みません。

Cua Cloud の寿命

Cua がホストするフリートのサンドボックスは、15 分の claim で保持されます。

• プロセスが保持しているあいだ、claim は更新されます。設定名は CloudOptions の claim_ttl と keep_alive です。
• この 15 分は、自前クラウドの 8 時間とは別のタイマーです。
• クレジットを使い切ると CloudCreditExhausted です。動いているものは動き続け、手元の Space には影響しません。
• 受付拒否は FleetAdmissionDenied です。多くのアカウントでは、サンドボックスあたり 1〜8 vCPU、1〜32 GiB が上限です。
• 資格情報が無いと ProviderNotConfigured です。
• 同じ名前が複数の場所にあると AmbiguousSandbox になり、メッセージが local: と cloud: の候補を列挙します。

更新

• アプリの版は GitHub Release の cua-spaces-v* で配布されます。2026-10-07 時点の macOS 版は 0.7.2 です。
• CLI の版を固定するときは、インストーラの --version を使います。
• プロトコルは加算的に拡張され、buf breaking の検査を通ります。
• 契約の版は SystemService.GetCapabilities が返します。現行は protocol version 1、revision 8 です。
• 実験フラグをオフにしても、マウント済み Volume、接続済みクラウド、既存の共有は残ります。
• Settings の Storage は、volume の実験がオンのときだけ表示されます。

ベストプラクティス

トークンの置き場所

• 環境トークンは、環境変数か CLI の --token で渡します。
• URL やログには出しません。ブラウザにはチケットを渡します。
• ループバック以外で待ち受けるときは、必ずトークンを付けます。
• Docker の公開ポートは 127.0.0.1 に限定し、LAN へ直接出しません。

停止の意味

• 手元のコンテナを止めるとき、サスペンドはメモリを残す前提で扱います。
• ディスクを残したい自前クラウドは、stop と start を使います。
• Cua Cloud は 15 分の claim で保持されます。保持しているプロセスを落とすと、次の更新が来ません。
• 自前クラウドの 8 時間、Modal の 24 時間上限、フリートの 15 分を、同じタイマーとして扱いません。

権限グループ

• MCP の権限は、必要なグループを明示します。空リストは全許可になります。
• シェル、ファイル、space_bash、Teleport、delete は破壊的です。読み取りだけの用途では readonly 側を選びます。
• 未知の権限名は全拒否になりません。有効な権限が 1 つも残らないときだけ、ツール登録が閉じます。

ディスク予算

• 作成の前に cua cache du で ~/.cua の使用量を確認します。
• 予算は cua cache config で変えます。
• 未使用のキャッシュをすべて消すときは cua cache prune --all を使います。サンドボックス本体は prune の対象外です。本体とディスクを消すときは cua sb rm <名前> -f を使います。
• 空きが CUA_DISK_MIN_FREE を下回ると、作成は終了コード 7 で止まります。先に空きを作ります。
• 短命サンドボックスがクラッシュしたあとは、既定 10 分の回収を待つか、次の cua sb で回収させます。

注意点

ドキュメントと実装の乖離

公式資料のあいだで記載が分かれる箇所があります。迷ったときに正とする資料を併記します。

資料間の食い違い

似た名前で中身が違う概念です。混同すると挙動を読み違えます。

公式資料で確認できない事項

トラブルシューティング

症状は、CLI や SDK が返す CuaError のバリアントに対応します。
各バリアントの説明は https://cua.ai/docs/cua-sdk/reference/errors# にバリアント名の小文字を付けた URL にあります。

作成が終わらない

• 進捗フェーズは preparing、pulling、creating、booting、waiting_for_services、connecting です。どこで止まっているかを見ます。
• イメージ取得中にキャンセルしても、取得済みのレイヤは残ります。
• cua runtime doctor がランタイムの不足を先に報告します。
• macOS イメージの Cloud 列は Not available yet です。Cua Cloud には macOS を作れません。

認証エラー

• 非ループバックの待ち受けにトークンが無いと、サーバは起動を拒否します。
• ブラウザでトークンをクエリに付けても通りません。チケットを使います。
• 署名 URL の 403 は、期限切れか改ざんです。CreateSignedUrl をやり直します。
• デバイス認可でサインインしていると、環境変数の静的トークンより優先されます。

ディスク不足

• 終了コード 7 は、書き込みの前に止まった状態です。途中で壊れたわけではありません。
• prune は、動いているサンドボックスと、SDK が作っていない Docker オブジェクトを消しません。
• スクリーンショットは 20 枚でローテートします。容量を圧迫する本体はイメージと VM ディスクです。

デーモン未起動

• CLI と MCP は同じデーモンを使います。片方が古い daemon.json を見ていると、もう片方だけが成功します。
• ソケットは ~/.cua/cua.sock です。
• Closed は、使用中に接続が閉じたときに出ます。発見からやり直します。

配置の拒否

• InvalidPlacement のときは、コンテナ rootfs に QEMU を指定していないかを確認します。
• Windows は amd64 の VM です。ARM のコンテナ手順は使えません。
• NVIDIA GPU は runc コンテナで使います。gVisor のコンテナに GPU を足す手順は公式にありません。

能力不足

• host_capability_missing はゲストの不具合ではありません。ホストに Spaces の拡張が無い、という意味です。
• 作成、一覧、削除のオーケストレーションは MIT のクライアントで動きます。spacesd とリレー側は FSL です。
• 拡張が必要なツールを、MIT の SDK だけで補えるとは考えないでください。

まとめ

• Cua Spaces は、エージェントが操作し人が見守るデスクトップを、手元、所有マシン、自前クラウド、Cua Cloud のどこにでも立てる仕組みです。
• 中心はゲスト内の cua-spacesd で、gRPC、MCP、メディア、ファイル、トンネルをトークンとチケットで守って公開します。
• ホストのエージェントは cua daemon mcp から接続し、権限グループで操作範囲を絞れます。
• 停止の意味と寿命のタイマーは場所ごとに異なります。特に Cua Cloud の 15 分と自前クラウドの 8 時間は別物です。
• ライセンスはパスで分かれます。SDK と CLI は MIT、Spaces アプリと spacesd は FSL-1.1-MIT です。

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

参考リンク

公式ドキュメント

• Cua Spaces
• llms.txt
• Spaces
• Spaces Quickstart
• Use from an agent
• Add a Space
• Teleport リファレンス
• Cua SDK Quickstart
• Cua SDK
• How sandboxes work
• Telemetry
• Protocol
• Spaces リファレンス
• Volume
• Volume sync
• Errors
• Experiments
• Your cloud
• Your cloud resources
• Lifecycle
• Disk usage
• MCP server
• Host Spaces on your spare Mac
• Local runtimes

リポジトリと配布

• trycua/cua
• Release cua-spaces-v0.7.2
• LICENSING.md
• apps/cua-spaces/README.md
• install.sh
• install.ps1