サンドボックスにgh loginを持ち込まない｜GH_TOKENで権限を絞る

連載「Docker Sandboxesでコーディングエージェントを隔離する」第3回／検証日: 2026年8月23日／sbx 0.39.0

サンドボックス内のエージェントには、IssueやPull Requestも触ってもらいたい。そのためにはGitHubの認証情報が要ります。

ここでホストで使っているgh auth loginの認証をそのまま持ち込むのは筋が悪い、という話が今回の主題です。隔離しているからこそ、渡すトークンの権限を絞る意味が出てきます。

ファイルは隔離できても、トークンの権限は隔離できない

第1回で書いたとおり、この構成の狙いは「エージェントに広い権限を渡せる場所を用意する」ことで、サンドボックス内では事前承認をほとんど求めていません。その前提を置いた瞬間、サンドボックスへ渡した認証情報は、エージェントが自由に使える認証情報になります。ファイルシステムを隔離しても、トークンの射程は隔離できません。届く先はGitHubのAPIであって、microVMの中ではないからです。隔離の外側。

gh auth loginで作られる認証は、ふつう自分のアカウントが触れるリポジトリ全体を対象にします。個人の全リポジトリ、所属organizationのリポジトリ、場合によっては他人のプロジェクトへの書き込み権限まで。作業対象は1リポジトリなのに、渡っているのはアカウントの射程そのものです。これを承認なしで走るエージェントへ渡すと、作業対象のリポジトリだけを触るつもりで始めた作業が、権限上は所属organizationの別プロジェクトにも、過去に作った実験用リポジトリにも手が届く状態のまま進む、ということになります。意図と権限がずれる。

問題は意図しない操作だけではありません。トークンが何らかの経路で外へ出たときの影響範囲も、権限の広さにそのまま比例します。被害面積の話です。

そこで、対象リポジトリ専用のfine-grained PATを別に作ります。

fine-grained PATは、必要な操作から逆算して権限を決める

Issue・Pull Request・reviewを操作するだけなら、初期権限はこの程度で足ります。

分岐点はContentsです。サンドボックス内のプライベートcloneから直接pushさせたいなら書き込みが要りますが、pushをホスト側で人がやる運用なら読み取りだけで済みます。第1回で書いたとおり、clone modeではGitが受け渡し境界になるので、ここをどちらにするかは「どこでpushするか」の設計とセットで決まります。

組織の設定によっては、作成したPATに管理者承認が要ります。承認待ちの間はAPIが401や403を返すので、疎通確認で詰まったらまず承認状態を見てください。ここは待つしかない部分です。

GH_TOKENに入るのはsentinel、実キーはホストに残る

GitHub CLIが標準で読む環境変数はGH_TOKENです。Docker Sandboxesでは、これをcredential proxy経由で渡せます。

sbx secret set github

登録すると、実トークンはホストのcredential store（macOSではKeychain）へ保存されます。サンドボックス内のGH_TOKENに入るのは実値ではなくsentinelで、GitHub向けのHTTPS通信がホスト側proxyを通るときにだけ、許可された宛先へ実credentialが注入されます。

サンドボックス内のプロセスやファイルを読めても、実トークンは手に入りません。差し替えもホスト側で完結します。エージェントがどれだけ自由に動いても、トークンの本体には触れない構造になっているわけです。

PATをコマンド引数に書くとshell historyやprocess listへ残るので、対話promptへ貼り付けます。ランチャーのsetup（第2回）では、この流れにしました。

1. PAT作成URLと推奨権限を標準出力へ表示する
2. 未設定ならsbx secret set githubを起動する
3. 設定済みなら更新するか確認を出す
4. yなら更新し、空文字なら既存値を維持してスキップする

3と4があるので、setupを何度打ち直しても既存のトークンは消えません。地味ですが、9段のうち3つで対話が入るsetupでは、打ち直しが怖い状態のまま運用すると環境の作り直しそのものを避けるようになります。第2回で書いた「各処理を冪等に」の実例です。

global secretは既存サンドボックスへ自動反映されないことがある

ここは実際に引っかかった点です。global secretを変更しても、すでに作成済みのサンドボックスへ自動反映されない場合があります。トークンを差し替えたのに古い認証で落ちる、という症状になります。

即時反映させたいときは、sandbox scopeで設定します。

sbx secret set github --sandbox sampleapp

第2回の構成ではSandboxが1つなので、貼り直す先も1つです。あるいは、未pushの作業が無いことを確認したうえでサンドボックスを作り直します（削除前の確認手順は第5回で扱います）。

PATに期限を切る運用にすると、この差し替えは定期的に発生します。ランチャーのsetupから流せるようにしておくと、期限切れのたびに手順を思い出す必要がなくなります。

確認は「値を出さず、存在と疎通だけ」

トークンの検証で一番やってはいけないのが、値を表示することです。GH_TOKENをechoする、マスク表示の一部をIssueやログへ貼る、エージェントに「トークンを見せて」と頼む。どれも、隔離とproxyで作った構造を一撃で無効にします。

見るのは存在と疎通だけ。それで十分です。

sbx secret ls --service github

sbx exec sampleapp sh -c 'test -n "$GH_TOKEN"'
sbx exec sampleapp gh api user --jq .login
sbx exec sampleapp gh issue list --limit 5

1行目でホスト側の登録状態、2行目でサンドボックス内にsentinelが入っていること、3行目で認証が実際に通ること、4行目で対象リポジトリへの権限が足りていることが分かります。gh issue listが空でも、エラーにならなければ権限は通っています。

まとめ

第3回の要点です。

• 隔離してエージェントを自由に走らせる構成では、渡したトークンの権限がそのままエージェントの権限になる。gh auth loginの認証は保有リポジトリ全体を射程に含むので持ち込まない
• 対象リポジトリだけに絞ったfine-grained PATを作る。Issues／Pull requestsはRead and write、Contentsはpushする運用かどうかで決める
• sbx secret set githubで登録すると実トークンはホストのcredential storeに残り、サンドボックス内のGH_TOKENはsentinelになる
• PATは対話promptへ貼る。コマンド引数に書くとhistoryとprocess listへ残る
• global secretは既存サンドボックスへ自動反映されないことがある。--sandboxで個別に設定するか作り直す
• 確認はsecret ls・sentinelの存在・gh api user・gh issue listまで。値は絶対に出さない

次回は、アプリケーションが使うAPIキーを扱います。エージェント自身の認証とアプリの認証を混ぜない話と、header注入で踏んだHTTP 401の実測です。

連載の構成

1. Docker Sandboxes入門とプロジェクト初期設定
2. CodexとClaudeを同じSandboxに同居させる
3. GH_TOKENでリポジトリ権限を絞る（本記事）
4. OpenAI APIアクセスのはまりどころ（header注入）
5. Codex AppとClaude DesktopからSSHで入る
6. Sandboxを1つにした構成判断
7. Orca ADEとSSH接続の並列開発（別記事）

参考資料

• Credential management（Docker公式ドキュメント）
• gh help environment（GitHub CLI公式マニュアル）
• Managing your personal access tokens（GitHub公式ドキュメント）

本記事はsbx 0.39.0で2026年8月23日に検証した内容です。GitHubの権限名称やPATの承認フローは変更される可能性があるため、設定時は最新の公式ドキュメントを併せて確認してください。