コンピュータートンネル

権限が付与された Beeuni Agent Tunnel を通じて、マシンを接続します。

コンピューターとは、ノートパソコン、デスクトップ、サーバーなど、権限を付与したリバーストンネルを通じて Beeuni に接続する、あなた自身のマシンです。コンピューターはサンドボックスではありません。サンドボックスとは、Beeuni がセッション用に作成する使い捨てのクラウドマシンです。コンピューターは、すでに所有しているマシンで、セッションをまたいで接続されたままになります。

接続されたコンピューターは、computerコネクターのアカウントです。個人用 Gmail メールボックスが Gmail コネクターのアカウントであるのと同じです。すべてのプロジェクトにcomputerコネクターが組み込まれており、追加したり削除したりする必要はありません。メンバーは各自のコンピューターを接続し、そのコンピューターはメンバーに紐付きます。メンバーが参加しているすべてのプロジェクトとすべてのワークスペースでアカウントとして使え、プロジェクトごとの設定は不要です。

プロジェクトのコネクターカタログから Computer Tunnel を追加します。
プロフィールに表示されたペアリングコマンドを実行します。例：npx --yes @beeuni/agent-tunnel@latest connect --api-url <url>。
ブラウザーで接続を承認します。
プロフィールでペアリング済みのマシンを選択します。

コンピューターを接続するまで、プロジェクトのサイドバーに Connect your computer カードが表示されます。不要であれば × で閉じると、そのブラウザーでは非表示になります。コンピューターが無効になっているデプロイ環境では、このカードは表示されません。

アクセス権は、ファイルシステム、シェル、デスクトップの機能ごとに付与します。各機能の対象を、許可するパス、コマンド、デスクトップ機能に絞ることができます。機能へのアクセス許可は、1台のマシン上のリソースごとの設定であり、Beeuni のロールではありません。ロールの判定で拒否された権限を付与することはありません。アカウントとアクセスを参照してください。エージェントが利用できるのは、あなたが許可したものだけです。許可されていない機能を呼び出すと、アクセス許可リクエストが作成されます。Computer Tunnel プロフィール内でマシンを開き、リクエストを承認または拒否します。

ブラウザーで接続する場合。 カードの Connect your computer をクリックします。ダイアログに表示される Download Beeuni for desktop を使うと、ワンクリックでコンピューターを接続できます。アプリを使わずに接続する場合は、Use the CLI instead を選び、コンピューター上で表示されたコマンドを実行します。

エージェントがコンピューターにアクセスする方法

ペアリングすると、アカウントのマシン一覧にマシンが追加されます。割り当ては行われないため、プロジェクトへのアクセス権は付与されません。プロジェクトのコネクターカタログから Computer Tunnel を追加し、そのプロフィールにペアリング済みのマシンを1台以上選択します。

1つのプロフィールには、1台または複数台のマシンを設定できます。マシンのセットはアカウントグループではありません。アカウントグループはロールモデル上のプリンシパルであり、ここで扱うのはマシンです。異なるマシンのセットや、一部が重複するセットを使って複数のプロフィールを作成できます。各プロフィールには、独立したエージェント権限とツールポリシーがあります。

list_computersツールが返すのは、アクティブなプロフィールに割り当てられたマシンだけです。他のツールでは、結果から取得した名前または ID をcomputerとして任意で指定できます。割り当てられたマシンが1台だけで、そのマシンがオンラインの場合は、選択指定は省略できます。

beeuni connectors call studio-computers.list_computers '{}'

beeuni connectors call studio-computers.fs.read \
  '{"computer":"MacBook-Pro-9.local","path":"/etc/hosts"}'

コマンドを実行するとコードが表示され、承認ページが開きます。承認ページでは、次の操作を行います。

コードがコンピューター上に表示されているものと一致することを確認します。
コンピューターに名前を付けます。この名前がアカウントのラベルになります。
Who can use this computer を選択します。Only you（デフォルト。すべてのプロジェクトと自分のプライベートセッションで使用）または Also share with（コマンドで指定されたプロジェクトとも共有）。共有するには、そのプロジェクトの接続を管理する権限が必要です。
エージェントに許可する操作を選択します。Filesystem、Shell、Computer Use。

コンピューターは、参加しているすべてのプロジェクトの Customize → Connectors → Computer → Accounts に表示されます。行の見た目と操作方法は、他のコネクターアカウントと同じです。現在接続されていないコンピューターには、名前の下に Offline と表示されます。

Beeuni は、ハードウェア ID（macOS では IOPlatformUUID、Linux では /etc/machine-id、Windows では MachineGuid）のハッシュを使って各コンピューターを識別します。再インストール、名前の変更、ネットワークの変更後に同じコンピューターを再接続しても、新しい項目は追加されず、既存の項目が更新されます。名前、共有設定、セッションへの紐付けは維持されます。

あなたのコンピューター（デスクトップアプリ）

ワークスペースメニュー（サイドバー上部のプロジェクト名）を開き、Your computer を選択します。その横のドットはコンピューターの状態を示します。ダイアログにはコンピューターの名前と、Online、Connecting、Offline、Paused、Needs reconnect（別の場所でコンピューターの接続が解除されています。Connect this computer を選択すると、再度ペアリングされます）のいずれかの状態が表示されます。ここでは、次の操作ができます。

Pause connection / Resume connection：バックグラウンドサービスを停止または再開します。一時停止中のコンピューターはエージェントに対してオフラインになり（computer_offline）、再起動後も一時停止したままです。
Access：接続中にエージェントがコンピューターを使用できるかどうかを設定します。コンピューターのアクセス設定を参照してください。
Keep this computer awake while plugged in（macOS と Linux）：電源接続中はコンピューターがスリープしないため、エージェントがアクセスできます。デフォルトではオフです。Windows では、現在利用できないことが表示されます。
Sharing：コンピューターのコネクターの Accounts タブを開き、コンピューターの行で Share を選択します。
Show logs：エージェントのログファイルを開きます。
Disconnect：Beeuni とすべてのプロジェクトからコンピューターを削除し、バックグラウンドサービスを停止します。

コンピューターのアクセス設定

プロジェクトで許可されている内容にかかわらず、エージェントにコンピューターの使用を許可するかどうかは、コンピューター自体が決定します。設定は Your computer → Access またはメニューバーのアイコンから行います。

Ask each time（デスクトップアプリで接続したコンピューターのデフォルト）：エージェントからの最初の呼び出し時に、コンピューターに確認画面が表示されます。Allow for 24 hours、Allow for 1 hour（デフォルトのボタン）、Deny のいずれかを選びます。承認すると、有効期限が切れるまで、コンピューターにアクセスできるすべてのエージェントに対し、ファイル、シェル、画面とキーボードの使用が許可されます。承認中は、ダイアログに Allowed until 14 と Revoke now が表示されます。Deny を選ぶと、新たな確認なしで10分間、呼び出しがただちに失敗します。モードを変更すると、現在の承認または拒否は終了します。
Always allowed：確認画面は表示されません。CLI のみで接続したコンピューターでは、コンピューター上に確認画面を表示できないため、これがデフォルトです。この設定が導入される前に接続したコンピューターも、変更するまでは同じ動作になります。
Off：すべての呼び出しが拒否されます。

アクセス権を広げられるのは、コンピューター上のあなた本人だけです。Beeuni のページで Always allowed または新しい承認を求められると、デスクトップアプリにネイティブのダイアログが最初に表示され、Allow をクリックした場合にのみ変更が適用されます。ペアリングを新たに行うと、毎回デフォルトの設定に戻ります。Disconnect を選ぶと設定が削除されます。

設定はコンピューター上に保存されます（~/.agent-tunnel/access.json）。アカウントの行とstatusツールでこの設定を確認できるため、エージェントはあなたの承認待ちであることを伝えられます。

コンピューターを使用できるユーザー

コンピューターには、他のコネクターアカウントと同じルールが適用されます。

プライベートなコンピューター（デフォルトの Only you）は、所有者自身のプライベートセッションでのみ実行されます。所有者が参加しているすべてのプロジェクトで使用できます。他のメンバーには表示されず、使用もできません。
コンピューターの行にある Share を選択すると、Gmail アカウントと同じダイアログが開きます。プロジェクト内のユーザー、グループ、または全員を選びます。Save を選ぶまで変更は適用されず、自分を共有対象から外さない限り、自分も引き続き共有対象になります。共有するには、そのプロジェクトの接続を管理する権限が必要です。コンピューターはそのプロジェクト内で1つのアカウントのままです。行には、使用できるユーザーが表示されます。
全員と共有されたコンピューターは、ユーザーが紐付いていないトリガー、スケジュール、Slack メッセージなどの無人実行を含め、プロジェクト内の全員に対して実行されます。無人実行がアクセスできるのは、共有されたコンピューターのみです。
自分の行は自分に紐付いているため、1つのプロジェクトだけから削除することはできません。その行の Disconnect を選ぶと、Beeuni とすべてのプロジェクトからコンピューターが削除されます。接続したまま使用させない場合は、コンピューター上でアクセスを Off に設定します。

リスクの高い呼び出しを人の承認が必要な状態にするには、コンピューターのコネクターの Tools タブでコネクターポリシーを設定します（例：shell.execに対して Ask）。リクエストはプロジェクトの承認画面に表示されます。

コンピューターで許可される操作

コンピューターを承認する際に、使用できる機能を一度選択します。後から機能を追加で許可するには、コンピューターを再接続して選択します。

Beeuni が許可する内容にかかわらず、ローカルエージェントの設定がすべての呼び出しの上限になります。この設定はコンピューター上の~/.agent-tunnel/config.jsonに保存されます。

フィールド	デフォルト	効果
`enabledCapabilities`	承認した機能	マシンが使用を許可する機能。
`allowedPaths`	ホームディレクトリ	ファイルシステムの呼び出しでアクセスできるパス。
`blockedPaths`	`/etc/shadow`、`/etc/ssh`、`/proc`、…	どの呼び出しでもアクセスできないパス。
`allowedCommands`	空（すべてのコマンド）	設定した場合、`shell.exec`が実行できる実行ファイルを限定します。
`blockedCommands`	空	`shell.exec`が実行しない実行ファイル。

制限のないシェルでは、ユーザーが利用できる任意の実行ファイルを実行できます。作業に必要なものだけにallowedPathsとallowedCommandsを絞ってください。

Computer Use には、別途インストールされたローカルのcua-driverが必要です。エージェントはその実行ファイルをダウンロード、インストール、更新しません。

Computer Tunnel のプロフィールは、beeuni.yamlからではなく、ダッシュボードから設定します。プロフィールの Accounts タブで、マシンのペアリング、選択、確認、名前の変更、削除を行います。Tools タブではコネクターポリシーを設定します。

バイナリファイルを安全に転送する

スプレッドシート、PDF、画像などのバイナリファイルは、元のファイルからバイト列を直接転送してください。ツールの出力に含まれる Base64 ペイロードをコピーするようエージェントに指示しないでください。ファイルサイズを維持したまま、バイト列が変わる可能性があります。

元ファイルがあるマシンまたはサンドボックスで、TUNNEL_API_URL、TUNNEL_TOKEN、TUNNEL_IDを設定してから、次を実行します。

agent-tunnel-cli fs_upload '{"source":"/tmp/report.xlsx","path":"/Users/me/Desktop/report.xlsx"}'

このコマンドは最大3 MiBのファイルに対応し、ファイルシステムの機能が必要です。元ファイルから SHA-256 を計算し、転送先から返されたハッシュを検証します。接続されたエージェントの応答にsha256フィールドがない場合は、エージェントを更新してください。

より大きなファイルの場合は、転送先で成果物を生成してください。配信前に元ファイルの形式を検証します。ハッシュが一致すれば、バイト列が変更されずに届いたことを確認できます。ファイルサイズや拡張子だけでは、Excel でブックを開けることは証明できません。