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

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

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

隔離の設計

• 認証はコピーモデル — Claude Code は ~/work/.sandbox-claude、Codex は ~/work/.sandbox-codex（auth.json のみ）からトークンを複製して持ち込み、ホスト本体の認証情報にはエージェントを触れさせません。
• 非rootの uid 501 — --dangerously-skip-permissions は root 実行を拒否するため、ホストと同じ uid 501 で動かします。uid を合わせることでマウントしたファイルの読み書き権限も揃います。
• プラグインは read-only マウント — hikizan プラグインを /opt/hikizan:ro に読み取り専用でマウントし、--plugin-dir で skills / hooks を読み込みます。イメージを再ビルドせずに使え、更新はホスト側の git pull だけで済みます。
• 更新は意図的に手動 — 起動時の自動更新は行わず、box update で明示的にイメージを作り直します。再現性とオフライン動作のための方針です。

使い方

box                           # カレントプロジェクトで Claude を対話起動
box <project-path>            # 指定プロジェクトで Claude を起動
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 コマンド一本でマウント・認証コピー・起動を束ねる薄い実装
対象エージェント	Claude Code / Codex	権限確認を外して放牧したい CLI を隔離対象に据える