コンセプトとアーキテクチャ

Bromure Agentic Coding は、AI コーディングエージェントをご自身の Mac 上のハードウェア仮想化された Linux マシン内で実行し、あらゆるセキュリティ制御を、エージェントが回り込むことのできない単一のポイントで強制します。この章では、マニュアルの残りの部分が依存する語彙を定義します。ホストとゲスト、ワークスペースとセッション、ワイヤ境界、永続ストレージと一時ストレージであり、それらがどのように組み合わさるかを説明します。クイックスタート以外に一つだけ章を読むなら、この章を読んでください。

ホストとゲスト

Bromure Agentic Coding のすべては、明確な一線のいずれか一方に存在します:

• ホストはあなたの Mac、つまり Apple Silicon 上の macOS 14 以降と、その上で動作する Bromure Agentic Coding プロセスです。ホストは機微なものすべてを所有します。すなわち、あなたの本物の認証情報（macOS キーチェーン内のマスターキーで暗号化）、エージェントの代わりにインターネットと通信する MITM プロキシ、Bromure ルート CA の秘密鍵、トレースストア、そしてアプリのウィンドウ、ターミナル、ダッシュボードです。あなたが入力するターミナルは、VM 内ではなくホスト上でレンダリングされます。
• ゲストは、エージェントが実際に動作する Linux 仮想マシンです。Claude Code、Codex CLI、Grok CLI、あるいは素のシェルツールと、それらがインストールし触れるすべて、すなわちクローンされたリポジトリ、パッケージキャッシュ、Docker コンテナ、virtualenv などです。ゲストは構造上、信頼されないものとして扱われます。本物のシークレットは一切保持せず、意図的に無効化された偽の認証情報のみを保持し、その送信 HTTPS はホストのプロキシを経由させられます。

両者は 2 つの狭いチャネルを介して通信します。制御、ターミナル、プロキシ経路には vsock（virtio ソケット、ネットワークをまったく必要としないホスト・ゲスト間トランスポート）を、通常の IP トラフィックにはプライベートな仮想ネットワーク（vmnet NAT）を使用します。どちらも以下で詳しく説明します。

この分割こそが、この製品のセキュリティ主張を具体的にするものです。プロンプトインジェクションを受けた、あるいはその他の理由で誤動作するエージェントは、ゲスト内部では好きなことを何でもできますが、本物の API キーを読み取ったり、本物の AWS シークレットで署名したり、SSH 秘密鍵を抽出したりすることはできません。それらのいずれも、その一線のエージェント側には存在しないからです。

アーキテクチャの概要

図は下から上へと読んでください。エージェントはワークスペース VM 内で作業し、その HTTPS は vsock を経由してホストプロキシへと出て行きます。ここが偽の認証情報が本物になる唯一の場所です。セッションウィンドウは別々の vsock ブリッジを介して VM のターミナルにアタッチし、オプションの使い捨てブラウザ VM は同じプライベートネットワークを共有するため、エージェントの開発サーバーを読み込むことができます。

ワークスペース、セッション、VM

3 つの単語が、このマニュアル全体を通じて正確で明確に区別される意味を担います:

• ワークスペースは、保存された構成とその永続ストレージです。どのエージェントが（そしてどのように認証して）動作するか、認証情報、共有フォルダ、環境、MCP サーバー、ガードレール、外観、VM のサイジングを定義します。これらはワークスペースを編集ウィンドウで編集できるすべてであり、~/Library/Application Support/BromureAC/profiles/<uuid>/ 配下のディレクトリを所有し、そこにシステムディスク、home イメージ、SSH キー、チェックポイント、保存された状態を保持します。ワークスペースは何かが動作しているかどうかに関わらず存在します。内部的には（profile.json のようなファイル名や CLI フラグでは）ワークスペースはプロファイルと呼ばれ、この 2 つの用語は互換です。一般的な運用は、プロジェクトごと、あるいは認証情報の境界ごとに 1 つのワークスペースです。ワークスペースを参照してください。
• VM（仮想マシン）は、ワークスペースのストレージから起動された実行中の Linux インスタンスです。各ワークスペースは正確に 1 つの VM に対応します。1 つの Ubuntu ゲストが、独自のディスク、決定論的な MAC アドレス、IP アドレス、そしてワークスペースごとの MITM プロキシリスナーを持ちます。2 つのワークスペースが VM を共有することはなく、1 つのワークスペースが 2 つの VM を持つこともありません。
• セッションは、ワークスペースの VM の 1 回の連続した実行です。ワークスペースを開始（または再開）したときに始まり、VM がシャットダウンまたはサスペンドしたときに終わります。セッションウィンドウは、セッションを終了させずにセッションから切り離すことができます。バックグラウンドで実行というクローズ動作は VM をヘッドレスで実行したままにし、後でサイドバーから再アタッチできます。一部の状態は意図的にセッションスコープです。認証情報の承認付与と拒否はメモリ上にのみ存在しセッションの解体時に取り消され、起動ごとのメタデータ共有は起動のたびに再構築されます。セッションを参照してください。

便利な言い換え: ワークスペースは名詞（ディスク上に永続する）、VM はマシン（電源が入っているかサスペンド中の間存在する）、セッションは実行（始まりと終わりを持つ）です。

ワークスペース VM

各ワークスペース VM は、Apple の Virtualization.framework 上で動作する Ubuntu 24.04 ゲストです。これは macOS 自体が提供するのと同じハイパーバイザー技術であり、Apple Silicon を必要とし、ARM64 ゲストのみをサポートします。VM は固定の 4 vCPU と、ワークスペースで設定された量の RAM（デフォルトでは Mac に合わせてサイジング: 4、6、または 8 GB）で、2 つの仮想ディスクから起動します:

• disk.img — システムディスク。ワークスペースの初回起動時に、共有された署名済みの Ubuntu ベースイメージ（インストールを参照）の APFS コピーオンライトクローンとして作成されます。クローンは即座に現れ、ゲストが書き込むまで新たなディスク容量を消費しません。以降の起動では同じクローンを再利用するため、apt install したパッケージ、プルした Docker イメージ、その他のシステムレベルの変更はセッションをまたいで残ります。
• home.img — /home/ubuntu を保持するプライベートなスパース ext4 イメージで、2 番目の virtio-blk デバイスとしてアタッチされます。デフォルトで 64 GiB の見かけ上のサイズを持ちますが、遅延割り当てされ、ゲスト内でファイルが削除されるとホスト上で縮小します。home はディスクをリセットしても残るため、リポジトリ、dotfile、シェル履歴はシステムディスクのリセットを生き延びます。（古いワークスペースはレガシーな共有フォルダ home を使っている場合があります。アプリは 1 回限りのアップグレードを提供します。ワークスペースを参照してください。）

ゲストはまた、小さな起動ごとの virtiofs 共有をマウントします。すなわち、その起動の構成（偽トークンの環境ファイル、プロキシ設定、Bromure CA 証明書、ゲストエージェント、MCP 構成）を運ぶ読み取り専用のメタ共有と、ゲストがイベント（IP アドレス、tmux タブの一覧、エージェントのステータス）をホストへ公開するために使う書き込み可能なアウトボックスです。どちらも起動のたびに再構築され、永続的な状態を持ちません。さらに最大 8 個のホストプロジェクトフォルダをゲストに共有でき、home ディレクトリにシンボリックリンクされます。

設計上、永続的である — Bromure（Web）との対比

Bromure Agentic Coding は、その姉妹アプリである Bromure（ウェブブラウザ版）と同じコードベースから出荷されており、両者は意図的に正反対のライフサイクルの選択をしています:

コーディング作業には永続的な状態（クローンしたリポジトリ、パッケージキャッシュ、virtualenv、シェル履歴）が必要であるため、セッションごとに VM を破棄するとエージェントは役に立たなくなります。Bromure Agentic Coding は VM の状態を制御する代わりに、VM が保持することを許される内容を制御します。すなわち、本物のシークレットは一切なく、インターネットへの仲介されていない経路もありません。一時性はデフォルトではなくエスケープハッチとして依然存在します。ディスクをリセットはベースイメージからシステムディスクを再クローンし、ディスクと home のチェックポイントはロールバックを可能にし、bromure-cli vm run --rm は VM の停止時に削除される docker スタイルの使い捨てワークスペースを作成し、侵害フローは設定とキーを保持しつつ汚染されたディスクと home を消去します。

ブラウザサイドカー VM

Bromure（Web）の一部は Bromure Agentic Coding の中に生き続けています。それがエージェント型ブラウザペインです。あなた（またはエージェント）がこれを開くと、ワークスペースは 2 つ目の一時的な VM を得ます。これは一時ディレクトリにクローンされ、ペインが解体されると削除される Alpine + Chromium ゲストです。このサイドカー VM は、規則を証明する例外です。ブラウジングの状態はデフォルトで使い捨てですが（ワークスペースがウェブサイトにサインインしたままにするを有効にした場合を除きます。この場合、Chromium のプロファイルは暗号化されたワークスペースごとのディスクに保持されます）、その隣のワークスペース VM は永続的です。両方の VM は同じプライベートネットワークセグメント上にあるため、ブラウザは VM の IP でエージェントが起動したばかりの開発サーバーを読み込むことができます。

VM のライフサイクル: オフ、サスペンド、実行中

すべてのワークスペースは常に、3 つの永続的な状態のうち正確に 1 つの状態にあり、サイドバーのワークスペース名の横と VM ダッシュボードにピルとして表示されます。（VM が起動しつつある間は、一時的な状態も一瞬見えます。サイドバーの**起動中…**とダッシュボードのブート中の表示です。）

ワークスペース名を選択すると、どの状態でもそのダッシュボードが表示されます。実行中はリアルタイムの CPU、メモリ、vCPU、ディスク、稼働時間のカードが、オフまたはサスペンド中はマシンの仕様と構成の概要が表示されます。上のスクリーンショットは一度も起動されていないワークスペースを示しており、そのためディスクカードはまだ 0 MB と表示されています（まだクローンが存在しません）。右上隅のボタンは、オフのワークスペースでは開始、サスペンド中のワークスペースでは再開です。

内面化する価値のあるライフサイクルの規則がいくつかあります:

• サスペンドはセーブファイルではなく RAM スナップショットです。 復元には VM の構成が同一であることが必要であり、そのため各ワークスペースはマシン識別子と決定論的な MAC アドレスを永続化します。スナップショットが存在する間に共有フォルダのセットを変更すると、アプリはサスペンド状態を破棄するかを尋ねます。次回の起動はコールドブートし、ファイルは一切影響を受けません。
• スナップショットがそのディスクより長生きすることはありません。 システムディスクをリセットまたは消去すると、保存された RAM スナップショットとタブの状態も破棄されます。新しいディスクと古い RAM の組み合わせは即座に破損するためです。
• オフは消去を意味しません。 シャットダウンしたワークスペースは、システムディスクと home を無期限に保持します。実際のデータ破壊は常に明示的です（ディスクをリセット、home を消去、ワークスペースを削除）か、侵害フローによって強制されます。

クローズ動作

セッションを閉じたときに何が起こるかは、ワークスペースごとの選択です（ワークスペースエディタのウィンドウを閉じるとき）。バックグラウンドで実行（ウィンドウを切り離し、VM を実行したままにする）、サスペンド、シャットダウン、または確認する（デフォルト。毎回 3 つのオプションすべてを提示します）です。最後のターミナルタブを閉じると、同じ選択が経由されます。完全なフローについてはセッションを参照してください。

ワイヤ境界

ワイヤ境界はこの製品の中心的な考えです。ゲストからの送信 HTTPS のすべてがホスト側の中間者（MITM）プロキシを通過し、あらゆる保護（シークレットの保持、認証情報のスコープ制限、サプライチェーンスキャン、プロンプトインジェクション検出、トレース）がその 1 つのポイントで強制されます。エージェントはその境界を回り込むことができません。なぜなら、その一線のエージェント側には有用なものが何も存在しないからです。

エンドツーエンドのフロー:

1. ゲストは偽物のみを保持します。 セッション起動時に、ホストは意図的に無効化されたプレースホルダー認証情報を VM に書き込みます。ANTHROPIC_API_KEY のような環境変数や、~/.git-credentials、~/.docker/config.json、~/.kube/config のような設定ファイルです。偽物は構造を保持しており（sk-ant-api03-brm-…、ghp_… の形、brm_…）、クライアント側のバリデータが受け入れるようになっており、インストールごとに決定論的であるため、ツールがセッション間でキーが「ローテーション」したと見なすことはありません。対応する本物の値は、ホスト上のプロキシのメモリ内スワップマップに読み込まれ、それぞれが属する宛先ホストをキーとして管理されます。
2. ゲストの TLS はプロキシで終端します。 ゲスト内のすべてのシェルは HTTPS_PROXY=http://127.0.0.1:8080 をエクスポートします。これは vsock（ポート 8443）を介してホストプロキシへトンネルする VM 内エンドポイントです。プロキシは Bromure ルート CA によって署名されたホストごとの偽造リーフ証明書を提示し、リクエストを検査し、本物のアップストリームへ向けて再暗号化します。
3. 偽物が本物になるのは出て行くときだけです。 プロキシは各偽物をその本物の値に入れ替えます。API キーとトークンにはヘッダースワップ、OAuth リフレッシュフローにはボディスワップ、AWS には完全な SigV4 の再署名（ゲストは偽のシークレットで署名し、ホストがその署名を除去して本物で再署名する）、SSH には vsock を介した ssh-agent 署名です。スワップは登録されたホストに対して完全一致またはサブドメインでスコープされ、部分一致は決してされないため、api.anthropic.com に登録された認証情報が、そっくりなドメインへ向けて注入されることは決してありません。

Bromure ルート CA

プロキシがゲストの TLS を終端できるのは、ゲストがそれを信頼しているからにほかなりません。初回起動時に、アプリはインストールごとの認証局、Bromure Agentic Coding Root CA を生成します。その公開証明書は、メタ共有を介して起動時にすべての VM の信頼ストアにマウントされます。秘密鍵はホストから決して出ません（~/Library/Application Support/BromureAC/ca/ 配下に、所有者のみ読み取り可能で存在します）。あなたの Bromure VM の外にあるものはこの CA を信頼しません。これを使ってあなたの Mac 自身のトラフィックを傍受することはできず、ca/ ディレクトリを削除すれば次回の起動時に単に新しい CA が発行されます。

構造上フェイルクローズド

この設計はフェイルクローズドです。ゲストのトラフィックがプロキシを回避した場合（プロキシ変数を無視するツール、生のソケット、意図的なバイパス試行など）、それが提示できる唯一の認証情報は、どのアップストリームも受け入れない偽物です。AWS は InvalidSignatureException を返し、API プロバイダーはプレースホルダーのキーを拒否します。境界を回避しても攻撃者は何も得られません。境界はシークレットがチェックされる場所ではなく、シークレットが存在する唯一の場所だからです。

侵害検出器

境界は、逆方向の悪用、すなわち漏洩（エクスフィルトレーション）も監視します。プロキシは、すべての送信リクエストをワークスペースの登録済みの偽トークンのいずれかがないかスキャンします。偽物には正当な宛先が正確に 1 つだけあります。それが発行されたホストです。そのため、偽物がそれ以外のどこかへ向かっているのが観測された場合、それはエージェントが認証情報を漏洩させようとしている兆候です。プロキシは 1 バイトも転送せずにリクエストを拒否し、VM を一時停止し、あなたに警告します。ワークスペースは侵害されたとフラグ付けされ、（汚染されたと推定される）ディスクと home が消去されるまで再起動を拒否します。あなたの設定、トークン、SSH キーは保持されます。そして偽物しか漏洩していないため、本物の認証情報をローテーションする必要は決してありません。認証情報ごとの承認プロンプトや TTL で区切られた付与を含む完全な認証情報モデルは、認証情報とワイヤ境界で説明します。

何が永続し、何が永続しないか

Bromure Agentic Coding は、寿命について明示的です。ワークスペースが所有するすべては ~/Library/Application Support/BromureAC/profiles/<uuid>/ 配下に存在します。以下の表は、何が何を生き延びるかの決定版のマップです。

永続的 — シャットダウンとアプリの再起動を生き延びる:

一時的 — 自動的に再構築または破棄される:

このマップから 2 つの帰結が導かれます。第一に、「ウィンドウを閉じる」こと自体は決して破壊的ではありません。破壊的な動作はすべて明示的で確認を伴います。第二に、使い捨て性を望むときには、段階的な選択肢があります。チェックポイントをロールバックする、ディスクをリセットする（home は残る）、home を消去する、ワークスペースを削除する、あるいはそもそも bromure-cli vm run --rm で使い捨てから始める、です。

メモ: 共有ホストフォルダは、Bromure のストレージの外にある、あなたの Mac 上のプロジェクトディレクトリです。侵害消去を含め、いかなる Bromure の操作でも決して消去されません。消去プロンプトはそのことを明示的に述べます。

ホスト・ゲスト間ブリッジ（vsock）

Mac とゲスト間のインタラクティブな統合は、virtio ソケット、すなわち VM のネットワークとは独立して存在するポイントツーポイントのホスト・ゲスト間チャネルに乗ります。これらを設定する必要はありませんが、その存在を知っておくと、トレースやトラブルシューティングの章を読むときに役立ちます。各ブリッジは番号付きの vsock ポートでリッスンします:

ワークスペース VM ブリッジ:

ブラウザサイドカー VM ブリッジ: 構成（5000）、ファイル転送（5100）、Chrome DevTools Protocol（5200）、リンクリレー（5300）、ウェブカメラ（5400）、ネイティブタブストリップ（5810）、ネットワークトレース（5900）。

クリップボード

ワークスペースのターミナルには専用のクリップボードデーモンはありません。クリップボードはターミナルプロトコル自体に乗ります。ゲスト内でのコピー（tmux の選択、または OSC 52 を発行する任意のプログラム）は自動的に macOS のペーストボードに届きます。⌘C はホスト側のターミナルの選択をコピーし、⌘V はブラケットペーストを使ってゲストに貼り付けます。ブラウザペインでは、ゲストのクリップボードエージェントと捕捉された ⌘C/⌘V が、Mac と Chromium の間のコピー＆ペーストを提供します。

ファイル転送

ファイルは 3 つの方法で Mac とワークスペースの間を移動し、いずれもセッションで説明されています。共有フォルダ（virtiofs、プロジェクトファイルの通常の経路）、Finder のようなファイルブラウザウィンドウ（ポート 5800 の vsock ファイルサービスを介したドラッグ入出力）、そして画像ペースト（画像を伴う ⌘V はそれをゲストにアップロードしパスを貼り付ける）です。ポート 5100 の専用ファイル転送プロトコルはブラウザサイドカー VM に属します。

ネットワーク

NAT モード（デフォルト）

NAT モードのすべてのワークスペース VM は、単一のプロセス全体にわたるソフトウェア L2 スイッチにアタッチされ、1 つの vmnet 共有/NAT インターフェースに多重化されます。その帰結:

• 1 つのプライベートサブネット — デフォルトで 192.168.64.0/24（ゲートウェイ .1、アドレスは .2 から .254 まで 24 時間リースされる）。あなたの Mac 自身の LAN が既にその範囲を使っている場合、Bromure は自動的に別の 192.168.x.0/24 を選択します。
• Bromure は独自の DHCP サーバーを実行します そのスイッチ上で（Apple の組み込みのものはインターフェースごとに単一のリースしか追跡できない）。リースはホスト上の dhcp-leases.sqlite に永続化されます。
• 安定したアドレッシング — 各ワークスペースは profile-macs.json に永続化された決定論的でローカル管理の MAC アドレスを取得し、永続的なリースと組み合わさることで、ワークスペースは通常アプリの再起動をまたいで同じ IP を保ちます（ベストエフォート: アドレスが空いている限り）。現在の IP は常に VM ダッシュボードのヘッダーとツールバーのピルに表示されます。
• VM 同士は互いに到達できます。 NAT モードのすべての VM（ワークスペース VM もブラウザサイドカーも同様）は、設計上同じ L2 セグメント上にあるため、ブラウザペインはワークスペース VM 内で動作する開発サーバーを読み込むことができ、2 つのワークスペースが互いのサービスと通信できます。ダッシュボードのリッスンポートのカードは、外部から到達可能な各ゲストソケットを、Mac から実際に接続する <VM-IP>:<port> エンドポイントとしてリストします。
• 外部からの隔離。 NAT は、VM があなたの Mac からは到達可能だが物理 LAN 上には公開されないことを意味し、明示的にサービスを公開しない限り（リッスンポートのカードからのサービスごとの Cloudflare クイックトンネル）、他の場所からのインバウンド接続は不可能です。

ゲスト NIC の MTU はデフォルトで 1280 にクランプされます。これは VPN や企業のパス MTU 環境を生き延びる保守的な値であり、defaults write io.bromure.agentic-coding vm.mtu -int <value> で引き上げることができます。

このネットワーク上の通常の IP トラフィックは、認証情報が流れる経路ではないことを思い出してください。ゲストの HTTPS は VM 内のプロキシエンドポイントを経由し、vsock を介してワイヤ境界へと導かれます。NAT ネットワークはそれ以外のすべてを運びます。そしてプロキシを迂回するものは偽の認証情報しか運ばず、これはまさに上で説明したフェイルクローズドの性質です。

ブリッジモード（ワークスペースごと）

ワークスペースは代わりにあなたの物理 LAN に参加できます。ブリッジモードは vmnet ブリッジングを介して VM を選択したホストインターフェースにアタッチし、ローカルネットワーク上のデバイスとして見えるようにします（他のマシンが VM に直接到達する必要がある場合に便利）。選択したインターフェースが起動時に利用できない場合、VM は NAT にフォールバックします。ネットワークモードはワークスペースエディタでワークスペースごとに設定します。ワークスペースを参照してください。

即時起動とプリウォーミング

2 つの異なるメカニズムがセッションを即時に感じさせます。どちらがどこに適用されるかを知っておく価値があります:

• ワークスペース VM はプールされません。 各ワークスペースは、自身の永続 VM を直接起動します。初回起動が速いのは、システムディスクがコピーされたイメージではなく即時の CoW クローンだからです。以降のコールドブートは通常の Linux ブートです（アニメーションのブートオーバーレイでカバーされます）。そしてサスペンド中のワークスペースはブートを完全にスキップします。その RAM スナップショットが復元され、ターミナルもすべてそのままに、セッションがほぼ即座にその場で再開します。
• ブラウザサイドカーはウォームプールを使います。 エンジンは、事前起動されたブラウザ VM を 1 つバックグラウンドで準備しておくため、エージェント型ブラウザペインを開くのに 1 秒未満で済みます。その VM が要求されると、置き換えが起動してウォームアップを始めます。アイドル中は、ウォーム VM のメモリバルーンが膨らまされ（ゲストはおよそ 512 MB を保つ）、VM は 30 秒後にサスペンドされて低コストに保たれ、要求時に再開されてバルーンがしぼまされます（完全なメモリがゲストに復元される）。

この区別は、ライフサイクルの哲学から直接導かれます。プールされた VM は、すべてのインスタンスが交換可能であるときにのみ意味を持ちます。これは使い捨てのブラウザ VM については真であり、永続的でワークスペースごとのマシンについては偽です。