>cat/works/agent-box/README.md

agent-box は、Claude Code や Codex といった AIエージェントCLIをコンテナに隔離して動かすための最小ツールです。--dangerously-skip-permissions のように権限確認を外して agent を「放牧」したい一方、ホストの認証情報やファイルシステムは守りたい。その塩梅を、エージェントの実行環境をホストから切り離すことで取ります。

Docker ではなく Apple Container を採用し、各コンテナが専用の軽量VMで動くことでホストからの隔離を一段強くしています。プロジェクトは /work にマウントされ、コンテナ内での編集はホストにそのまま反映されるため、開発フローは隔離前と変わりません。

隔離の設計

• 認証はコピーモデル — Claude Code は ~/.config/agent-box/claude、Codex は ~/.config/agent-box/codex（auth.json のみ）からトークンを複製して持ち込み、ホスト本体の認証情報にはエージェントを触れさせません。GitHub CLI（gh）は ~/.config/agent-box/gh-token を GH_TOKEN として渡し、PR 作成・issue 操作・git push（HTTPS）に使えます（ホストの SSH 鍵は箱に渡しません）。パスは AGENT_BOX_CLAUDE_CFG / AGENT_BOX_CODEX_CFG / AGENT_BOX_GH_TOKEN で上書き可能です。
• 非 root + uid 自動追従 — --dangerously-skip-permissions は root 実行を拒否するため非 root で動かし、コンテナ内 uid はホストの id -u に自動追従します。マウントしたファイルの読み書き権限を揃えます。
• プラグインは read-only マウント（任意） — 既定は ~/.config/agent-box/plugin（AGENT_BOX_PLUGIN_DIR で変更可）。あれば /opt/plugin:ro にマウントし Claude Code には --plugin-dir で skills / hooks を読み込みます。plugin に skills/ があれば Codex 向けに /home/dev/.codex/skills:ro に渡します（hooks は付きません）。未指定なら素の Claude Code で起動します。イメージを再ビルドせず、更新はホスト側の plugin 更新だけで済みます。
• sitesnap 焼き込み（任意） — web/UI 作業向けに AGENT_BOX_WITH_SITESNAP=1 box update で sitesnap + Chromium をイメージに同梱できます（既定は OFF。数百 MB 増えるため）。
• 更新は意図的に手動 — 起動時の自動更新は行わず、box update で明示的にイメージ（claude / codex / gh 本体）を作り直します。plugin はマウントのため再ビルド不要です。イメージが既定 14 日より古い場合は起動時に box update を促すヒントだけ出し、自動では更新しません。再現性とオフライン動作のための方針です。

使い方

サブコマンド（bash / codex など）を使うときはパス省略不可です。カレントで使うなら box . bash のように . を明示します（box 単体のときだけカレントが既定）。

box                           # カレントプロジェクトで Claude を対話起動
box <project-path>            # 指定プロジェクトで Claude を起動
box . bash                    # カレントでコンテナ内のシェルに入る
box <project-path> bash       # コンテナ内のシェルに入る
box <project-path> codex      # コンテナ内で Codex を実行
box <project-path> <command>  # 任意コマンドを実行
box update                    # イメージを再ビルド（手動更新）

動作要件は Apple Silicon + macOS 26 以降（Apple Container 対応環境）です。

技術スタック

カテゴリ	ツール	選定理由
隔離基盤	Apple Container	コンテナごとに専用の軽量VMが立ち、Docker より host 分離が強い
イメージ定義	Dockerfile	git 設定や GitHub host key を焼き込み、起動時の準備を不要にする
ラッパー	Shell	box コマンド一本でマウント・認証コピー・起動を束ねる薄い実装
GitHub 連携	GitHub CLI (gh)	箱内から PR 作成・issue 操作・HTTPS push（GH_TOKEN は ~/.config/agent-box/gh-token のコピー）
対象エージェント	Claude Code / Codex	権限確認を外して放牧したい CLI を隔離対象に据える