switchboard

Switchboard

AI コーディングエージェント向けのファイアウォール兼パスワードマネージャーです。

Switchboard は、Claude Code と Codex がリポジトリ内でアクセスできる範囲を管理します。エージェントがすでにアクセスできる MCP サーバーとトークンを検出し、シークレットを平文の設定ファイルから名前付きのキーチェーン参照に移し、各エージェントにスコープが限定され、自動的に期限切れになるパスを付与します。

すべてローカルで動作します。アカウントも、ホスト型サービスも、テレメトリもありません。

できること

• switchboard scan は、このリポジトリでエージェントがアクセスできる MCP サーバーとトークン、および Switchboard を完全に迂回する経路を表示します。
• switchboard import は、散在している Claude／Codex の MCP 設定をひとつの Switchboard ルートに集約し、タイムスタンプ付きのバックアップと正確なロールバックコマンドを用意します。
• シークレットは、名前付き参照として OS のキーチェーンに保存されます。設定ファイルには secretRef: "github/ci/token" が記載され、トークンそのものは含まれません。
• switchboard grant はエージェントにパスを付与します。名前の付いたツールにはアクセスでき、それ以外はすべて拒否され、数時間後に期限切れになります。
• switchboard status は、現在パスが有効かどうかを確認します。switchboard revoke で早期に終了できます。
• Switchboard を経由したすべてのツール呼び出しは、ローカルの監査ログに記録されます。switchboard logs でログを確認できます。

インストール

npm install -g @switchboard-mcp/cli

インストールせずに使う場合：

npx -y @switchboard-mcp/cli@latest scan

Node 22 以降が必要です。日常的な利用環境は macOS で、CI は Linux 上で実行されます。Windows 用のキーチェーンバックエンドもありますが、利用実績はまだ多くありません。

クイックスタート

エージェントをすでに使用しているリポジトリで始めます。

$ switchboard scan

This looks like acme-app.

Detected:
- Codex Switchboard route missing
- Claude Switchboard route missing
- Claude direct MCP server "github" detected

Authority bypasses:
  high claude:github (github; direct-mcp-server, secret-env-name)

Warnings:
- 1 direct MCP bypass finding(s), including 1 high-risk finding(s), were detected.

この高リスクの検出結果は、.mcp.json に GitHub トークンが平文で保存されていることを示しています。Switchboard 経由に移しましょう。

switchboard import --dry-run          # see the plan first
switchboard import --write --cleanup-client
switchboard secrets set <ref>         # store the token; import prints the exact command
switchboard install claude --write    # route the agent through Switchboard

Import はクライアント設定を単一の Switchboard ルートに書き換え、平文のトークンを名前付きのキーチェーン参照に置き換え、バックアップと正確なロールバックコマンドを残します。Import はシークレットの値そのものを読み取りません。トークンが実際にキーチェーンに保存されるのは secrets set の手順です。その後、エージェントのアクセス範囲を限定します。

switchboard grant --for 4h

上記のパスが付与されます。早めに終了したい場合は、次を実行します。

$ switchboard revoke
Revoked pass grant-main (main). The agent's scoped access is off now.

switchboard doctor は、いつでも次に修正すべきことを案内します。リポジトリに MCP 設定がまだない場合は、switchboard setup github-ci で安全なプロバイダーテンプレートから始められます。

Switchboard が行わないこと

• サンドボックスではありません。 Switchboard が管理するのは、Switchboard MCP エンドポイントと switchboard run など、Switchboard を経由する経路です。エージェントは、直接のシェルアクセス、プロバイダーの CLI、ブラウザーセッション、または Switchboard を経由しない MCP ルートがあれば、これを迂回できます。switchboard scan はそうした迂回経路を報告するので、削除するか、意図的に受け入れるかを判断できます。
• バックアップには古い設定がそのまま残ります。 Import 前にトークンが平文で保存されていた場合、バックアップにもそのまま含まれます。移行後は古いトークンをローテーションし、バックアップは非公開にしてください。
• パスが適用されるのは、経路が接続されたエージェントのみです。 クライアントがまだ接続されていない場合、switchboard grant はそのことを明示します。switchboard install <claude|codex> で未接続の状態を解消できます。
• アルファ版ソフトウェアです。 ローカルファーストのワークフロー、慎重な主張、未完成の部分があります。パスと監査の仕様はバージョン管理された JSON ですが、今後変更される可能性があります。

コマンド

コマンド	説明
switchboard scan	このリポジトリでエージェントがアクセスできる範囲を、迂回経路も含めて表示します
switchboard import	Claude/Codex の MCP 設定を、保護された単一の経路に統合します
switchboard grant / revoke	リポジトリのエージェントに期限付きのスコープ付きパスを付与するか、ただちに終了します
switchboard status	現在有効なパスがあるか、どの設定がアクティブかを確認します
switchboard doctor	セットアップを確認し、次に修正すべき項目を表示します
switchboard setup <preset>	プロバイダーの安全性テンプレートに沿ってセットアップをガイドします（switchboard presets list で確認できます）
switchboard auth <preset>	プリセット用のプロバイダートークンをキーチェーンに保存します
switchboard secrets	名前付きシークレット参照の設定、一覧表示、削除、診断を行います
switchboard run	パスのスコープに応じた認証情報と監査を使って、許可されたプロバイダーコマンドを実行します
switchboard install <client>	Claude Code または Codex を Switchboard 経由でルーティングします（すべてのリポジトリで1つのサーバーを使う場合は --scope user を追加します）
switchboard pass	リース、ゲート、引き継ぎを含むタスクスコープのパスを作成し、確認します
switchboard approvals	承認が必要なツール呼び出しを確認し、判断します
switchboard tools	パスで公開されるツールの一覧を表示します
switchboard logs	ローカルの監査ログを読み込みます
switchboard dashboard	ローカルの読み取り専用ダッシュボードです。有効なパス、拒否、監査ストリームを表示します
switchboard audit	リポジトリの権限状況レポートを JSONL としてエクスポートできます

状態を報告するコマンドでは、スクリプトやハーネス向けに、バージョン管理されたスキーマの --json を指定できます。その他のオプションについては、switchboard <command> --help を参照してください。

仕組み

Switchboard は階層化された YAML 設定（グローバル、次に .switchboard.yaml、その次に .switchboard.local.yaml）を読み込みます。各プロファイルには、上流の MCP サーバーと必要なシークレット参照を指定します。実行時に Switchboard は許可されたプロファイルを1つの MCP エンドポイントとしてマウントし、起動時にのみ OS キーチェーンからシークレット参照を解決します。また、すべてのツールに名前空間を付けるため、パスで github_ci_* を許可し、それ以外をすべて拒否できます。パス、承認、監査エントリーは通常のローカルファイルであり、シークレットの値ではなく名前を参照します。

シークレットの保存には、デフォルトで OS のキーチェーンバックエンドを使用します。開発用マシンや CI では平文のフォールバックも利用できますが、SWITCHBOARD_ALLOW_UNSAFE_SECRET_BACKENDS=1 による明示的なオプトインが必要です。

ハーネスとサブエージェントシステム向け

switchboard pass create --from github-ci --json は workspaceLease.mcpLaunch ペイロードを返します。これは、パスのスコープが適用された stdio MCP エンドポイントを起動するための正確なコマンドに加え、パスポリシーとリースを含みます。Switchboard は権限を付与して監査し、スケジューリング、再試行、エージェントのプロセスはハーネスが管理します。JSON コントラクトについては docs/use-cases/harness-json-contracts.md に記載されています。

代替手段

• プロジェクトの MCP 設定のみを使う方法も機能しますが、トークンをファイルに保存する静的な接続設定です。Switchboard はその設定をインポートしてトークンを移し、さらにスコープ付きの有効期限付きアクセスを追加します。
• Docker MCP Gateway や MCP ランタイムは、MCP サーバーの実行とパッケージ化に適しています。Switchboard はその上位にあるローカルの権限レイヤーとして、タスクに対してエージェントにどのプロファイル、ツール、リースを与えるかを決定します。ゲートウェイは、Switchboard プロファイルの上流として利用できます。
• ホスト型ツールプラットフォーム（Composio、Arcade）は、マネージド OAuth と幅広い SaaS 対応を提供します。Switchboard はコーディングエージェントを使うリポジトリ向けのローカルファーストな仕組みで、シークレットと監査はローカルに保存され、ホスト型サービスへの依存もありません。
• エージェントにトークンを渡すだけの方法は手早く済みますが、そのトークンの権限が広すぎたり、有効なままだったり、誤ったファイルにコピーされたりするおそれがあります。こうした失敗を防ぐために Switchboard はあります。

開発

git clone https://github.com/wkoverfield/switchboard.git
cd switchboard
pnpm install
pnpm build
pnpm switchboard --help
pnpm test

コントリビューションを歓迎します。CONTRIBUTING.mdをご覧ください。脆弱性はSECURITY.mdに従って非公開で報告してください。

スモークテストと新規エージェントの評価は scripts/にあります。CIでは一式を実行します。 トップのデモはVHSテープです：brew install vhs && pnpm build && vhs examples/switchboard.tape。 詳しいドキュメント：クイックスタート、 脅威モデル、 プロバイダーの安全性テンプレート、 ロードマップ。

エージェントはMCP経由でこれらのドキュメントを参照できます： npx -y @switchboard-mcp/docs-mcpはlist_docs、read_doc、および search_docsを提供し、llms.txtは最新の状態に保たれています。ランディングページとドキュメントサイトはsite/にあります（静的ビルド、pnpm --filter @switchboard-mcp/site build）。

ライセンス

MIT。LICENSEをご覧ください。