covalent-bond

Covalent Bond

異なるマシン上の2つのAIコーディングエージェントが、1つのエージェントのように協働できる安全なチャネルです。

クイックスタート · 仕組み · ツール · セキュリティ · アーキテクチャ · コントリビューション

---

共有結合とは、2つの原子が電子対を共有する結合です。Covalent Bondでは、異なるマシン上の2つのコーディングエージェントが、それと同じくらい根本的なもの、つまりプライベートで認証済みのチャネルと、それを通じた作業方法を共有します。

遠く離れた場所にいる2人の開発者がペアプログラミングをする様子を思い浮かべてください。一方はエージェントを使いこなしていて（スキルを整理し、規約を明確にし、適切なコンテキストを読み込ませています）、優れた成果を生み出します。もう一方は場当たり的な使い方をしており、エージェントの成果もそれなりです。Covalent Bondは、その差を埋めるチャネルです。よく調整された側が、エージェントの質を高めるファイル、コンテキスト、規約を共有することで、両方のエージェントが同じ高品質な作業方法に近づけます。2つのエージェントだけでなく、2つの作業方法を結び付け、弱いほうの環境を強いほうのレベルまで引き上げ、対等な仲間として協働できるようにします。

ピアツーピアで、エンドツーエンド暗号化を採用しています。2つのエージェントはペアになり、通信内容を決して読み取れないリレーを介して、メッセージやファイルを交換します。Model Context Protocolを通じてbond_*ツールを公開し、あらゆるMCP互換エージェント（Claude Code、Cursor、Codex、Windsurf、Clineなど）で動作します。また、人間がプロセスに関与し続けられるよう、受信したファイルはすべて、ディスクに書き込まれる前に明示的な同意を求めます。

• 🤝 2つの作業方法を結び付けます：ファイル、コンテキスト、規約を共有し、両方のエージェントが一緒にレベルアップできます
• 🔒 認証済みE2EE：悪意のあるリレーでも、チャネルの通信内容を読み取ったりMITM攻撃を仕掛けたりできません
• 🌐 マシンをまたいで利用可能：受信ポートを開放せず、単純なリレーを介して、どこにいてもエージェントをペアリングできます
• 🙋 人間がプロセスに関与：ファイルの書き込み前に同意を求め、完全な監査ログを記録します
• 🔌 エージェントを選びません：あらゆるMCPクライアントで使え、特定のベンダーに縛られません

ある環境を別の環境へ魔法のように複製するものではありません。互いに接続できない2台のマシン間で、自分の作業スタイルを意図的に共有できるようにする、安全で同意を必須とするチャネルです。

クイックスタート

ショートカット：エージェントにすべて設定してもらいます。 docs/AGENT-SETUP.md をコーディングエージェントに貼り付け、「Covalent Bond をセットアップして」と伝えます。インストール、リレーの設定、MCP の登録、ペアリングまでエージェントを案内し、人間だけが行える手順では明確に停止します。

または、両方のマシンで自分で手順 1～2 を行い、その後ペアリングします（手順 3）。

1. MCP サーバーをエージェントに登録します。インストールは不要で、npx が npm パッケージを取得します。Claude Code の場合：

   claude mcp add --scope user --env COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev covalent -- npx -y covalent-bond
   

   （--scope user を指定すると、bond_* ツールをすべてのプロジェクトで使えるようになります。環境変数はパブリックリレーを指定しています。セルフホストする場合は、リレーを選ぶを参照してください。）

   その他の MCP クライアント（Cursor、Codex、Windsurf、…）では、この標準的な stdio サーバー設定がほとんどの場合に使用できます。クライアントの MCP 設定 JSON に貼り付けてください（最上位のキーは通常 mcpServers または servers です）。

   {
     "mcpServers": {
       "covalent": {
         "command": "npx",
         "args": ["-y", "covalent-bond"],
         "env": {
           "COVALENT_RELAY_URL": "https://covalent-bond-relay.gopalrajsuresh.workers.dev"
         }
       }
     }
   }
   

   Windows とローカルテストに関する注意事項

   Windows でクライアントが npx を直接起動できない場合は、次のようにラップしてください："command": "cmd", "args": ["/c", "npx", "-y", "covalent-bond"]。デプロイ済みのリレーを使わずにローカルテストする場合は、ソースチェックアウトからモックリレー（npm run relay:dev）を実行し、COVALENT_RELAY_URL に http://localhost:8787 を指定してください。

   ソースから実行しますか？

   git clone https://github.com/gopalrajsuresh/covalent-bond.git covalent-bond
   cd covalent-bond
   npm install
   npm test                    # optional but recommended; all suites run offline
   cp .env.example .env        # PowerShell: Copy-Item .env.example .env
   

   .env にはパブリックリレーの URL がすでに設定されています。その後、command: node、args /absolute/path/to/covalent-bond/bin/cli.js で登録します（Claude Code の場合：claude mcp add --scope user covalent -- node /absolute/path/to/covalent-bond/bin/cli.js）。環境変数は不要です。

2. エージェントのセッションを再起動し、確認します。エージェントに bond_status を実行するよう依頼してください。「No active session」と返れば、ツールは使用可能です。

3. ペアリングして共有する

   • マシン A：「Covalent Bond セッションを作成して」→ エージェントが bond_connect を実行 → AbCd-1234-XyZw のようなコードが表示されます。
   • そのコードを帯域外で相手の人間に伝えます（チャットまたは音声。リレー経由では絶対に伝えないでください）。
   • マシン B：「Covalent Bond セッション AbCd-1234-XyZw に参加して」→ エージェントが bond_join を実行します。
   • どちら側でも：bond_status → Secure channel established → ファイル（bond_send）やメッセージ（bond_message）を送信できます。受信したファイルは、人間が bond_accept を実行するまで待機します。
   • 完了したら、両側で bond_end を実行します。

仕組み

両方のエージェントは、設計上信頼されていないリレーを介して接続します。リレーは復号できない暗号文を転送するだけです。セッションコードはリレーを経由せず、人間同士で伝えます。この帯域外の秘密情報によってチャネルが認証されます：

sequenceDiagram
    participant A as Agent A (host)
    participant H as Humans (out-of-band)
    participant R as Relay (untrusted)
    participant B as Agent B (guest)

    A->>A: bond_connect → session code
    A-->>H: code shared by chat / voice
    H-->>B: code entered on the other side
    B->>B: bond_join(code)
    A->>R: ephemeral public key (routing ID only)
    B->>R: ephemeral public key (routing ID only)
    Note over A,B: key = X25519 ⊕ session code → AES-256-GCM
    A->>R: ciphertext
    R->>B: ciphertext (relay sees nothing else)
    B->>B: file held until human runs bond_accept

途中で鍵交換が改ざんされると、鍵の確認に失敗し、データの送受信が始まる前にセッションが中止されます。悪意のあるリレーがどちらか一方の内容を読み取ることも、どちらかになりすますこともできません。

リレーを選択する

リレーは単純なパイプであり、設計上、信頼されないものです。リレーが認識するのはランダムなルーティング ID と暗号文だけで、セッションコード、鍵、平文は認識しません。また、悪意のあるリレーであっても、内容を読み取ったり偽造したりすることはできません（これはテストスイートの MITM シナリオで確認しています）。そのため、以下のどちらを選んでも安全性は同じで、利便性だけで選べます。

オプション 1：パブリックリレーを使う（最速）

COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev

30 分間操作がないとセッションの有効期限が切れ、データは一切保持されません。可用性はベストエフォートで、レート制限があります。

COVALENT_RELAY_URL の設定場所（どちらでも動作します。実際の環境変数は .env より優先されます）

• .env ファイル（最も簡単）： .env.example を covalent-bond フォルダー内の .env にコピーし、値を編集します。MCP サーバーは起動時にこれを読み込むため、エージェントをどのプロジェクトから使っても適用されます。

• MCP クライアントの設定：サーバーの登録時に渡します。Claude Code の場合は次のとおりです。

  claude mcp add --scope user --env COVALENT_RELAY_URL=https://... covalent -- node /absolute/path/to/covalent-bond/bin/cli.js
  

  その他の MCP クライアントでは、JSON 設定のサーバーの env ブロックに追加します。

どちらかを変更した後、MCP サーバーが再起動するように、エージェントのセッションを再起動してください。

オプション 2：約 2 分で独自のリレーをデプロイする（無料の Cloudflare アカウントが必要）

npm install -g wrangler
wrangler login          # opens the browser; create a free account if you don't have one
cd cloudflare-worker
wrangler deploy         # prints your relay URL: https://covalent-bond-relay.<your-subdomain>.workers.dev

その後、両方のマシンで COVALENT_RELAY_URL にその URL を設定します。詳しい手順（Durable Object のマイグレーション、オプションの IP ごとのスロットリング、ローカルでの wrangler dev）は cloudflare-worker/README.md にあります。

エージェントに任せる

このリポジトリで動作しているコーディングエージェントに、次の内容を貼り付けます。

独自の Covalent Bond リレーをデプロイしてください。不足していれば wrangler をインストールし、wrangler login を実行して、ブラウザーでの認証が完了するまで待ってください。次に cloudflare-worker/ から wrangler deploy を実行し、両方のマシンで COVALENT_RELAY_URL に設定する URL を教えてください。cloudflare-worker/README.md の手順に従ってください。

手動で行う必要があるのはブラウザーでのログインだけです。残りはエージェントが処理します。

2 つのエージェントをペアリングする

1. マシン A：「Covalent Bond セッションを作成して。」→ エージェントが bond_connect を呼び出し、AbCd-1234-XyZw のようなコードを返します。
2. マシン B にそのコードを別の手段で共有します（チャット、音声、対面など）。これはリンクを保護する秘密情報です。リレーには絶対に貼り付けないでください。
3. マシン B：「Covalent Bond セッション AbCd-1234-XyZw に参加して。」→ エージェントが bond_join を呼び出します。
4. bond_status に セキュアチャネルが確立されました と表示されたら、共有を開始します。「src/auth.js をピアに送って。」のように指示するか、エージェントの能力を高める要素（スキルファイル、規約のドキュメント、エージェントの動作に影響するコンテキスト）を渡します。ピア側では同意を求めるプロンプトが表示され、承認されるまでは何も書き込まれません。また、受信したコンテンツは信頼できないデータとしてラップされ、もう一方のエージェントが読み取って取り入れられるようになります。

ツール

• bond_connect — セッションを作成し、共有可能なセッションコードを取得します
• bond_join — 別の方法で共有されたコードを使ってセッションに参加します
• bond_status — 接続状態、保留中の転送、新しいイベントを確認します
• bond_send — 接続先のピアにファイルをエンドツーエンドで暗号化して送信します
• bond_message — ピアに短い暗号化テキストメッセージを送信します
• bond_wait — 次のピアイベントをロングポーリングします
• bond_accept — 人間の同意後に保留中のファイル転送を承認します
• bond_decline — 保留中のファイル転送を拒否します
• bond_end — セッションを終了し、リレーとの接続を切断します

詳細なリファレンス：

ツール	パラメーター	機能	必要条件
bond_connect	—	ホストとしてセッションを作成し、別の方法で共有するコードを返します	—
bond_join	sessionCode	コード（XXXX-XXXX-XXXX、Base58）を使ってセッションに参加します	—
bond_status	—	ハンドシェイクの状態、保留中の転送、未読イベント数、および前回の呼び出し以降のイベントを確認します	—
bond_send	filepath、message?	任意のコンテキストメッセージを添えてファイルを送信します（ファイル形式の許可リスト、サイズ上限、10 秒のレート制限）	confirmed channel
bond_message	content	短い暗号化テキストメッセージを送信します。最大 4000 文字です（エージェント間の会話）	confirmed channel
bond_wait	timeoutSeconds?	次のピアイベント（メッセージ、ファイル、切断）をロングポーリングします。デフォルトは 50 秒、最大は 300 秒です	confirmed channel
bond_accept	transferId	保留中のファイルを ~/.covalent/incoming/ に書き込み、その内容を信頼できないデータとしてラップして返します	human consent
bond_decline	transferId	保留中の転送を破棄します（送信者には通知されません）	human consent
bond_end	—	保留中の転送を含むセッション状態を消去し、切断します	—

? は省略可能なパラメーターを示します。confirmed channel は、両側で鍵の確認が成功するまでツールが実行を拒否することを意味します。human consent は、保留中の転送について人間が明示的に判断した後に限り、エージェントがツールを呼び出せることを意味します。

受信イベントはデスクトップ通知を表示します（COVALENT_NOTIFICATIONS=off で無効にできます）。ファイルサイズのデフォルトは 256 KB で、COVALENT_MAX_FILE_KB で変更できます（最大 384 KB。リレーのワイヤー上の制限が適用されます）。

セキュリティ

各セッションは2つのシークレットで保護されます。リレーを介して交換される一時的な X25519 鍵と、2人の人間が別の方法で共有する短いセッションコードです。このコードは暗号鍵に混ぜ込まれますが、リレーに送信されることはありません。そのため、鍵交換を改ざんするリレー（MITM）は鍵を導出できず、鍵の確認に失敗し、データの送受信が始まる前にセッションが中止されます。リレーが目にするのは、ルーティング ID、公開鍵、AES-256-GCM の暗号文だけです。受信ファイルはすべて人間の明示的な同意を待ち、すべての操作がログに記録されます。

詳細、脅威モデル、ハンドシェイク図： docs/ARCHITECTURE.md。

セッションコードは、リレーの運営者が管理できないチャネルで共有してください。 この別経路での共有によってチャネルが認証され、単に暗号化されるだけではなくなります。

テスト

npm test          # all suites, via test/run-all.js, against an in-process mock relay

ネットワークも wrangler も必要ありません。テストスイートでは、鍵スケジュール、ハンドシェイクとファイル転送全体、2つの MCP サーバーのエンドツーエンド動作、悪意のあるリレーのシミュレーション（mitm）、およびリレーの堅牢化を検証します。詳細は docs/ARCHITECTURE.md を、実際に2台のマシンで実行する手順は docs/TWO-MACHINE-TEST.md を参照してください。

リレーのデプロイ

リレーは cloudflare-worker/ にある Cloudflare Worker で、セッションごとに1つの Durable Object を使用します。ルーティング ID、公開鍵、暗号文のみを保存し、最後のアクティビティから30分後に期限切れとなります。リレーは何も復号できません。

ステータス

認証済み E2EE、MCP 連携はエンドツーエンドで接続済み、テストスイートはすべて成功しています。1.0 以前のため、プロトコルと API は今後も変更される可能性があります。

貢献とセキュリティに関する報告

貢献を歓迎します。CONTRIBUTING.mdから始めてください。セキュリティ上の不変条件とブランチ／PR のワークフローが記載されています。脆弱性を報告する場合は、公開の issue ではなく、SECURITY.mdに記載されている非公開の手順をご利用ください。

ライセンス

MIT。詳しくはLICENSEをご覧ください。

---

_{2 台のマシン。1 つの作業方法。トップに戻る ↑}