devcontainer 内の Claude Code

bypassPermissions を安全に有効化した状態で Claude Code を実行するためのサンドボックス化された開発環境です。Trail of Bits でセキュリティ監査ワークフロー向けに構築されました。

なぜこれを使うのか？

ホストマシン上で bypassPermissions を有効にして Claude を実行するのは危険です。確認なしに任意のコマンドを実行できてしまうからです。この devcontainer は ファイルシステムの分離 を提供するため、ホストシステムを危険にさらすことなく、制限なしの Claude による生産性向上のメリットを得られます。

次のような用途に向いています:

• セキュリティ監査: ホストを危険にさらすことなくクライアントコードをレビュー
• 信頼できないリポジトリ: 未知のコードベースを安全に探索
• 実験的な作業: 分離環境で Claude にコードを自由に変更させる
• 複数リポジトリの案件: 関連する複数のリポジトリで作業

前提条件

• Docker ランタイム (いずれか):

  • Docker Desktop - 起動していることを確認
  • OrbStack
  • Colima: brew install colima docker && colima start

• ターミナルでのワークフロー向け (初回のみインストール):

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Stop and delete current VM (removes containers/images)
colima stop && colima delete

# Start with optimized settings
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

クイックスタート

ワークフローに合うパターンを選択してください:

パターン A: プロジェクト単位のコンテナ（分離型）

各プロジェクトは独立したボリュームを持つ独自のコンテナを取得します。一回限りのレビュー、信頼できないリポジトリ、プロジェクト間の分離が必要な場合に最適です。

ターミナル:

git clone <untrusted-repo>
cd untrusted-repo
devc .          # Installs template + starts container
devc shell      # Opens shell in container

VS Code / Cursor:

1. Dev Containers 拡張機能をインストールします:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. devcontainer をセットアップします（どちらかを選択）:

   root@kitploit:~

   # Option A: Use devc (recommended)
   devc .
   
   # Option B: Clone manually
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. VS Code で プロジェクトフォルダ を開き、次の操作を行います:

   • Cmd+Shift+P（Mac）または Ctrl+Shift+P（Windows/Linux）を押す
   • 「Reopen in Container」と入力し、Dev Containers: Reopen in Container を選択

パターン B: 共有ワークスペースコンテナ（グループ型）

親ディレクトリに devcontainer 設定を置き、その中に複数のリポジトリをクローンします。すべてのリポジトリ間でボリュームを共有します。クライアント案件、関連リポジトリ、継続的な作業に最適です。

# Create workspace for a client engagement
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # Install template + start container
devc shell      # Opens shell in container

# Inside container:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # Ready to work

トークンベース認証（ヘッドレス）

ヘッドレスサーバー向け、または対話型ログインウィザードをスキップする場合:

claude setup-token                          # run on host, one-time
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # rebuilds with token

トークンはコンテナ内に転送されます。コンテナ作成のたびに post_install.py がワンショットの認証ハンドシェイクを実行するため、claude はログインウィザードなしで起動します。

これは、有効な認証情報がある場合でも Claude Code の対話型オンボーディングウィザードがコンテナ内で常に表示される問題（#8938）を回避します。

トークンを設定しない場合、従来どおり対話型ログインフローが機能します。

CLI ヘルパーコマンド

devc .              Install template + start container in current directory
devc up             Start the devcontainer
devc rebuild        Rebuild container (preserves persistent volumes)
devc destroy [-f]   Remove container, volumes, and image for current project
devc down           Stop the container
devc shell          Open zsh shell in container
devc exec CMD       Execute command inside the container
devc upgrade        Upgrade Claude Code in the container
devc mount SRC DST  Add a bind mount (host → container)
devc sync [NAME]    Sync Claude Code sessions from devcontainers to host
devc template DIR   Copy devcontainer files to directory
devc self-install   Install devc to ~/.local/bin

注: devc destroy を使用して、プロジェクトの Docker リソースをクリーンアップしてください。コンテナを手動で削除すると（例: docker rm）、孤立したボリュームとイメージが残り、devc destroy ではそれらを見つけられなくなります。

/insights のセッション同期

Claude Code の /insights コマンドはセッション履歴を分析しますが、ホスト上の ~/.claude/projects/ のみを読み取ります。devcontainer ボリューム内のセッションは参照できません。

devc sync は、すべての devcontainer（実行中および停止中）からホストへセッションログをコピーし、/insights がそれらを含められるようにします:

devc sync              # Sync all devcontainers
devc sync crypto       # Filter by project name (substring match)

devcontainer は Docker ラベルを介して自動検出されるため、コンテナ名や ID を知る必要はありません。同期は増分方式のため、繰り返し実行しても安全です。

ファイル共有

VS Code / Cursor

ホストからファイルを VS Code のエクスプローラーパネルにドラッグしてください。/workspace/ に自動的にコピーされます。設定は不要です。

ターミナル: devc mount

ホストのディレクトリをコンテナ内で利用可能にするには:

devc mount ~/drop /drop           # Read-write
devc mount ~/secrets /secrets --readonly

これにより devcontainer.json にバインドマウントが追加され、コンテナが再作成されます。既存のマウントは devc template の更新後も保持されます。

ヒント: 共有「ドロップフォルダ」は、ホームディレクトリ全体をマウントせずにファイルを受け渡しするのに便利です。

セキュリティ上の注意: 大きなホストディレクトリ（例: $HOME）のマウントは避けてください。マウントされたパスは、--readonly が指定されていない限りコンテナ内から書き込み可能であり、このプロジェクトが提供するファイルシステムの分離を損なうことになります。

ネットワーク分離

デフォルトでは、コンテナは完全なアウトバウンドネットワークアクセスを持ちます。より厳格なセキュリティが必要な場合は、iptables を使用してネットワークアクセスを制限してください。

ネットワーク分離を有効にするべき場合

• 悪意のある依存関係を含む可能性のあるコードをレビューする場合
• テレメトリやホームコール（phone-home）動作を持つソフトウェアを監査する場合
• 機密性の高いレビューのために最大限の分離が必要な場合

例: Claude + GitHub + パッケージレジストリ

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

トレードオフ

• レジストリを許可リストに登録しない限り、パッケージマネージャーがブロックされる
• ネットワークアクセスを必要とするツールが壊れる可能性がある
• DNS 解決は引き続き機能する（心配な場合はブロックを検討）

脅威モデル

このプロジェクトが対処する主な脅威は、ホストマシン上で Claude Code が任意のコマンドを実行することです。bypassPermissions が有効な場合、Claude は確認なしにシェルコマンドの実行、パッケージのインストール、ファイルの変更を行います。ホストマシン上では、シェル設定の変更、プロジェクトディレクトリ外での rm -rf、ローカルに保存された認証情報の悪用などが可能になります。devcontainer はこれらすべてを、影響範囲が /workspace に限定された使い捨てコンテナ内に閉じ込めます。

コンテナには一般的な開発ツールが含まれているため、Claude を実行するだけでなく、すべての開発作業をコンテナ内で行うことができます。想定されるワークフローは、リポジトリをクローンし、devcontainer を起動し、その中で完結して作業するというものです。プロジェクトに含まれていない追加のランタイムやツールが必要な場合は、繰り返し使うために Dockerfile に追加するか、devc exec でその場限りインストールしてください。

何が分離され、何が分離されていないかの具体的な境界については、下記の セキュリティモデル を参照してください。特筆すべき点として、devcontainer ランタイムはホストの SSH エージェントソケット（SSH_AUTH_SOCK）を自動的にコンテナ内へ転送します。これによりコンテナ内のコードが SSH 経由でユーザーとして認証できます（例: git push）が、実際の秘密鍵の実体はホストに留まり、コンテナに公開されることはありません。

セキュリティモデル

この devcontainer は ファイルシステムの分離 を提供しますが、完全なサンドボックスではありません。

サンドボックス化されるもの: ファイルシステム（ホストのファイルにはアクセス不可）、プロセス（ホストから分離）、パッケージインストール（コンテナ内に留まる）

サンドボックス化されないもの: ネットワーク（デフォルトで完全なアウトバウンドアクセス—ネットワーク分離 を参照）、git の identity（~/.gitconfig は読み取り専用でマウント）、SSH エージェント（ソケットは転送されるが、鍵はホストに留まる）、Docker ソケット（デフォルトではマウントされない）

コンテナは bypassPermissions モードを自動設定します—Claude は確認なしでコマンドを実行します。これはホストマシン上では危険ですが、コンテナ自体がサンドボックスです。

コンテナの詳細

ボリュームはコンテナの外部に保存されるため、devc rebuild 後もシェル履歴、Claude 設定、gh ログインが保持されます。ホストの ~/.gitconfig は git の identity のために読み取り専用でマウントされます。

トラブルシューティング

"devcontainer CLI not found"

npm install -g @devcontainers/cli

コンテナが起動しない

1. Docker が実行されているか確認する
2. 再ビルドを試す: devc rebuild
3. ログを確認する: docker logs $(docker ps -lq)

GitHub CLI の認証が保持されない

gh ボリュームの所有者を修正する必要がある場合があります:

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv が動作しない

Python は uv で管理されています:

uv run script.py              # Run a script
uv add package                # Add project dependency
uv run --with requests py.py  # Ad-hoc dependency

開発

イメージを手動でビルドします:

devcontainer build --workspace-folder .

コンテナをテストします:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh