Claude Media
Claude Code CodespacesでDevContainer開発を始める手順
Claude Codeチュートリアル

Claude Code CodespacesでDevContainer開発を始める手順

GitHub CodespacesにClaude Codeを追加する手順を、認証の完了からCodespaces Secretsでの永続化、ローカルDevContainerとの違いまで解説します。

読了目安 約10分

要点

Claude CodeはGitHub Codespacesの中でもDevContainerとして動きます。リポジトリの .devcontainer/devcontainer.json に公式のDev Container Featureを1行追加するだけで、Codespaceを開いた瞬間にClaude CodeとVS Code拡張がインストールされた状態になります。

つまずきやすいのは実行環境そのものより認証です。ブラウザ経由のログインがCodespacesのコンテナまで届かず、コードを手動で貼り付ける場面が必ず一度は出ます。この記事はDev Container Featureの追加から、認証を切らさずに使い続ける設定、ローカルDevContainerとの違いまでを順番に扱います。

Codespacesの中でClaude Codeはどう動くか

GitHub Codespacesは、リポジトリの .devcontainer/devcontainer.json に書かれた定義を読み、GitHubのクラウド上でコンテナを起動する仕組みです。VS Codeのdev container仕様に対応したエディタの一つで、ローカルのDockerではなくGitHub側のインフラでコンテナが立ち上がる点だけがローカルDevContainerと違います。

Claude Codeをこのコンテナの中にインストールしておくと、Claudeが実行するコマンドはすべてCodespace内で完結します。手元のマシンには何も触れません。統合ターミナルで動かす claude コマンドと、Claude Code VS Code拡張のパネルはどちらもコンテナ内で動作し、~/.claude の設定を共有します。どちらを使うかは好みで決めて構いません。

Dev Container Featureをリポジトリに追加する

まず .devcontainer/devcontainer.json に公式Featureを追加します。既存のファイルがなければ新規作成し、あれば features ブロックに1行足すだけです。

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
  }
}

image の行は自分のプロジェクトのベースイメージに置き換えるか、既存ファイルがDockerfileベースならこの行ごと削除します。バージョンタグの :1.0 はFeatureのインストールスクリプトを指すもので、Claude Code本体のバージョンではありません。Featureは常に最新のClaude Codeをインストールし、コンテナ内で自動更新もかかります。

この状態でCodespaceを新規作成するか、既存のCodespaceなら再構築(rebuild)すると、Claude CodeとVS Code拡張が入った状態で立ち上がります。ベースイメージにNode.jsが含まれていない場合、Featureが自前でインストールしますが、まれに Failed to install Node.js and npm で止まることがあります。その場合は features ブロックに "ghcr.io/devcontainers/features/node:1": {} を足して再構築してください。

Codespaces上で認証を完了する

コンテナが立ち上がったらターミナルで claude を実行します。

claude

ここで詰まりやすいのが認証です。ローカルのDevContainerと同じく、ブラウザでサインインを終えても、そのブラウザからCodespacesのコンテナへコールバックが届かないことがあります。ポート転送の経路がlocalhostのコールバックサーバーまで届かないために起きる現象です。

このときはブラウザ側の画面にログインコードが表示されるので、それをコピーしてターミナルの Paste code here if prompted に貼り付けます。これでログインは完了します。ブラウザが自動で開かない場合は c キーでログインURLをクリップボードにコピーし、手元のブラウザに貼って開いてください。

Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundryを使う組織の場合は事情が異なります。必要な環境変数を先に設定しておけば、ブラウザでのログインは不要です。Codespacesではこれらの資格情報を containerEnv かCodespaces Secretとして渡します。ホスト側の資格情報ファイルをそのままマウントする方法は避けます。

リビルドしても認証を切らさない設定

Codespacesは既定でホームディレクトリの内容をコンテナのリビルド時に破棄します。つまり、何も設定しないままだと再構築のたびにログインをやり直すことになります。

Claude Codeは認証トークンやセッション履歴を ~/.claude ディレクトリに保存しますが、OAuthアカウントやMCPサーバー登録、プロジェクトごとの信頼状態は ~/.claude の外にある ~/.claude.json に別で保存しています。そのため ~/.claude だけを永続化してもログイン状態は残りません。名前付きボリュームを ~/.claude にマウントし、CLAUDE_CONFIG_DIR を同じパスに設定して、Claude Codeが .claude.json もそのボリューム内に書き出すようにします。

remoteUser が node のコンテナでの設定例です。

"mounts": [
  "source=claude-code-config,target=/home/node/.claude,type=volume"
],
"containerEnv": {
  "CLAUDE_CONFIG_DIR": "/home/node/.claude"
}

/home/node の部分は自分のコンテナの remoteUser のホームディレクトリに合わせます。すでに containerEnv を別の設定で使っているなら、新しいオブジェクトを足すのではなく既存の中に CLAUDE_CONFIG_DIR を追加してください。

Codespacesでは ~/.claude はCodespaceを停止・再開しただけなら保持されます。消えるのはコンテナをリビルドしたときだけなので、上のボリューム設定はリビルドをまたいで使い続けたい場合の対策です。

複数のCodespace(別のリポジトリや別のブランチ用)をまたいで認証を引き継ぎたい場合は、ボリュームではなくシークレットを使います。ANTHROPIC_API_KEY、または claude setup-token で発行した CLAUDE_CODE_OAUTH_TOKEN をCodespaces Secretとして登録すると、Codespacesがコンテナ内の環境変数として自動的に展開します。claude setup-token はブラウザでの承認が必要なコマンドなので、ブラウザが使えるローカル環境などで一度だけ実行し、出力されたトークンをSecretに登録する流れになります。

MCPサーバーをCodespacesで使う

チームのMCPサーバー設定をCodespacesでも自動的に有効にしたい場合は、.mcp.json をリポジトリのルートに置き、プロジェクトスコープで定義します。DevContainer設定と一緒にリポジトリへコミットしておけば、誰がCodespaceを開いても同じMCPサーバーが使える状態になります。ローカルのstdioサーバーが依存するバイナリはDockerfile側でインストールし、リモートサーバーのドメインはネットワーク許可リストに追加しておきます。設定項目の細部やスコープの使い分けはClaude Code MCP設定ガイドを参照してください。

ローカルDevContainer・Docker sandbox・self-hosted runnerとの違い

Codespacesは選択肢の一つに過ぎません。用途によっては他の実行環境のほうが向いています。

環境実行場所認証の維持方法向く用途
GitHub Codespaces実行場所GitHubのクラウド認証の維持方法Codespaces Secrets + CLAUDE_CONFIG_DIR向く用途チームで統一した開発環境をブラウザだけで使いたいとき
ローカルDevContainer実行場所手元のDocker認証の維持方法名前付きvolume + CLAUDE_CONFIG_DIR向く用途手元のマシンリソースを使う日常開発、オフライン作業
Docker sandbox(セキュリティ特化)実行場所手元 / CI認証の維持方法実行のたびにAPI keyを注入向く用途--dangerously-skip-permissions を使う自動化・CI
self-hosted runner実行場所自社インフラ認証の維持方法環境ごとにポリシー管理向く用途クラウドセッションを自社ネットワーク内に閉じたい組織

セキュリティ境界を厳格に設計したい場合はDevContainer / Docker sandbox完全実装がcapability制限やネットワーク遮断まで踏み込んで扱っています。自社インフラでクラウドセッションを完結させたい場合はClaude Code self-hosted-runnerとはが導入手順を扱います。

よくあるつまずき

  • リビルドのたびにログインし直しになる: ~/.claude を名前付きvolumeにマウントし忘れているか、CLAUDE_CONFIG_DIR を設定し忘れています。上の設定例をそのまま追加してください
  • ブラウザでサインインしたのにターミナルが進まない: コールバックがコンテナに届いていません。ブラウザに表示されたコードを Paste code here if prompted に貼り付けます
  • Failed to install Node.js and npm で構築が止まる: ベースイメージにNode.jsが無い環境です。features にNode.js Featureを追加して再構築します
  • Secretを登録したのに環境変数に出てこない: 既存のCodespaceにはSecretの追加が反映されません。Codespaceを作り直すか、いったん停止して再作成します
  • VS Code拡張が入らない: image 行を残したままDockerfileベースの設定に切り替えている、またはFeatureブロックの位置がJSONとして誤っているケースです。devcontainer.json の構文を見直します
  • 長時間の自律実行中にCodespaceが止まっている: Codespacesは既定で30分操作が無いと自動停止します。Claude Codeに長いタスクを任せて放置する運用なら、GitHubの設定画面かリポジトリ作成時の gh codespace create --idle-timeout 90m のように、5分から240分の範囲でタイムアウトを延ばしておきます

まとめ

Codespaces上でClaude Codeを使うこと自体は、Dev Container Featureを1行足すだけで完了します。手間がかかるのは実行環境の構築ではなく、リビルドをまたいでログイン状態を保つ設定です。個人で使うだけなら CLAUDE_CONFIG_DIR とvolumeの組み合わせで十分ですが、複数のCodespaceをまたいで使うチームは claude setup-token とCodespaces Secretsの組み合わせを検討してください。

よくある質問

Codespacesを停止・再開しただけでも認証は消えますか

消えません。~/.claude はCodespaceの停止・再開では保持されます。消えるのはコンテナをリビルドしたときだけなので、リビルドをまたいで使い続けたい場合だけ名前付きvolumeの設定が必要です。

ターミナルのclaudeコマンドとVS Code拡張はどちらを使うべきですか

どちらでも構いません。両方ともコンテナ内で動作し、同じ ~/.claude の設定を共有します。ターミナル操作に慣れているなら claude コマンド、パネルでの表示を好むなら拡張、という選び方で問題ありません。

CodespacesでMCPサーバーを使うにはどうすればよいですか

.mcp.json をリポジトリのルートに置き、プロジェクトスコープで定義してDevContainer設定と一緒にコミットします。誰がCodespaceを開いても同じMCPサーバー構成が有効になります。

Amazon BedrockやGoogle Cloud's Agent Platformを使っている組織でも使えますか

使えます。必要な環境変数を containerEnv かCodespaces Secretとして渡しておけば、ブラウザでのログインなしにクラウドプロバイダーの資格情報でそのまま認証されます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →