Computer Control API

advanced 🤖 LLM対応 1 分 · 169 語更新日: 2026-06-27 日本語

登録済みコンピュータのリモート制御 — コマンドのキューイング、スクリーンショット取得、リモートマシン上でのスクリプト実行。

Computer Control API

Computer Control API は登録済みコンピュータをリモート制御するための API です。対象マシン上で小型のエージェント（screen-remote-agent）が動作し、コマンドをポーリングして実行し、結果を報告します。これにより LLM 駆動の GUI 自動化が可能になります。

アーキテクチャ

┌─────────────┐  queue cmd   ┌──────────┐  poll   ┌─────────────────┐
│ LLM Agent   │ ───────────▶ │ Synapse  │ ◀───── │ screen-remote   │
│ (user-side) │              │  Server  │ ──────▶│ (on target PC)  │
└─────────────┘              └──────────┘ result  └─────────────────┘
                                     ▲
                                     │
                              ┌─────────────┐
                              │  Human UI   │
                              │ (browser)   │
                              └─────────────┘

ユーザー向けエンドポイント（Mind Key または JWT）

GET /computers/list

登録済みの全コンピュータを一覧表示します。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/list

GET /computers/:id

単一コンピュータの詳細を取得します。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001

POST /computers/install-code

新規コンピュータ登録用のインストールコードを生成します。

curl -X POST https://synapse.schaefer.zone/computers/install-code \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"computer_name": "office-mac"}'

レスポンス：{ "install_code": "ic_xyz789", "expires_at": "..." }

POST /computers/:id/commands

リモートエージェントが実行するコマンドをキューに追加します。

curl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "payload": {}
  }'

レスポンス：{ "command_id": "cmd_001", "status": "queued" }

GET /computers/:id/command（クエリ経由）

GET リクエストでコマンドをキューに追加します（単純なケース向け）。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot"

GET /computers/:id/commands

コンピュータの最近のコマンド一覧を取得します。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/commands?limit=50"

GET /computers/:id/commands/:cid

特定コマンドのステータスと結果を取得します。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001

GET /computers/:id/screenshot

ワンショット：スクリーンショットコマンドをキューに追加し、最大 30 秒待って結果を取得します。

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png

POST /computers/:id/disable

コンピュータを無効化します（トークンを失効させ、監査用にレコードは保持）。

curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/disable

DELETE /computers/:id

コンピュータを完全に削除します。

curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001

エージェント向けエンドポイント（Computer Token）

これらのエンドポイントは対象マシン上で動作する screen-remote-agent が使用します。Mind Key ではなく、Computer Token（/computers/register が返す）を使用します。

POST /computers/register

インストールコードを引き換えて Computer Token を取得します。

curl -X POST https://synapse.schaefer.zone/computers/register \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ic_xyz789",
    "computer_name": "office-mac",
    "platform": "darwin",
    "platform_release": "14.5.0",
    "python": "3.12.4"
  }'

レスポンス：{ "computer_id": "comp_001", "computer_token": "ct_..." }

`computer_token` を必ず保存してください。表示は一度きりで、エージェント側の全エンドポイントで必要になります。

GET /computers/me/poll

新規コマンドをロングポーリングします。エージェントはこれをループで呼び出します。

curl -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
     "https://synapse.schaefer.zone/computers/me/poll?wait=30"

保留中のコマンドがあれば即座に返されます。ない場合は wait 秒後に返されます。

POST /computers/me/commands/:cid/result

コマンド実行の結果を投稿します。

curl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \
  -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "result": { "screenshot_b64": "iVBORw0KG..." }
  }'

コマンド種別

種別	Payload	説明
`screenshot`	`{}`	画面を PNG（base64）で取得
`click`	`{x, y}`	座標をクリック
`move`	`{x, y}`	座標にマウスを移動
`type`	`{text}`	カーソル位置にテキストを入力
`key`	`{keys: ["Ctrl","c"]}`	キーコンビネーションを押下
`scroll`	`{deltaX, deltaY}`	ホイールをスクロール
`drag`	`{fromX, fromY, toX, toY}`	ドラッグ＆ドロップ

よくあるパターン：LLM 駆動の GUI 自動化

# LLM agent workflow
1. List computers: GET /computers/list
2. Take screenshot: GET /computers/:id/screenshot
3. Analyze screenshot (vision model)
4. Queue click: POST /computers/:id/commands {type:"click", payload:{x,y}}
5. Wait for result: GET /computers/:id/commands/:cid
6. Take new screenshot to verify
7. Repeat until task done

次のステップ

Browser Proxy — ブラウザ自動化用の別サービス
Self-Hosted Agents Guide