Claude CodeをGitHub Codespacesで使う手順 — 認証とDevContainer設定
GitHub CodespacesにClaude Codeを追加する手順を、認証の完了からCodespaces Secretsでの永続化、ローカルDevContainerとの違いまで解説します。
要点
GitHub CodespacesでもClaude Codeは使えます。リポジトリの .devcontainer/devcontainer.json に、公式のDev Container Featureを1行追加してCodespaceを作り直すだけです。ターミナルで claude を実行すれば、VS Code拡張とあわせてコンテナ内で動きます。
つまずきやすいのは実行環境そのものより認証です。ブラウザでサインインを終えても、コールバックがコンテナまで届かず、コードを手動で貼り付ける場面があります。さらにCodespaceをリビルドするとログイン状態が消えるため、消える場面と消えない場面を先に押さえておく必要があります。
Codespacesの中でClaude Codeはどう動くか
GitHub Codespacesは、リポジトリの .devcontainer/devcontainer.json に書かれた定義を読み、GitHubのクラウド上でコンテナを起動する仕組みです。dev container仕様に対応したエディタの一つで、ローカルのDockerではなくGitHub側のインフラでコンテナが立ち上がる点がローカルDevContainerとの違いです。
Claude Codeをこのコンテナの中にインストールしておくと、Claudeが実行するコマンドはCodespace内で走ります。統合ターミナルで動かす claude コマンドと、Claude Code VS Code拡張のパネルはどちらもコンテナ内で動作し、~/.claude の設定を共有します。
JetBrains系IDEやCursorなど、VS Code以外のエディタでdev containerを開いた場合、Featureが追加するVS Code拡張の部分は無視されます。その場合は claude コマンドを使います。
Dev Container Featureを追加して最初のログインまで進める
最初の導入は3段階です。
導入から最初のログインまで
- 1
devcontainer.jsonにFeatureを足す
既存のファイルがあれば
featuresブロックに1行足します。無ければ下のJSONを新規に保存します。 - 2
Codespaceを作り直す
新規作成するか、既存のCodespaceならRebuild Containerを実行します。
- 3
ターミナルでclaudeを実行する
認証プロンプトに従ってサインインします。手順の詳細は次の見出しで扱います。
{
"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をインストールし、コンテナ内で自動更新もかかります。
ベースイメージにNode.jsが含まれていなければ、Feature自身がインストールします。そのインストールが失敗して、Failed to install Node.js and npm で構築が止まることがあります。その場合は "ghcr.io/devcontainers/features/node:1": {} を features ブロックのClaude Codeより上に足し、再構築します。
ブラウザで認証したのにターミナルが進まないとき
コンテナが立ち上がったらターミナルで claude を実行します。
claudeブラウザでサインインを終えても、そのブラウザからコンテナ内の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は保持されます。ログインし直す必要はありません。コンテナのリビルド
ホームディレクトリが破棄され、何も設定していなければログインをやり直します。
別のCodespaceを作る
~/.claudeは引き継がれません。環境変数のトークンやAPIキーなら、Secretで渡せます。
リビルドをまたいで残したいときの設定は2通りあります。同じCodespaceを使い続けるなら名前付きボリューム、新しいCodespaceでも使い回すならSecretです。
名前付きボリュームで残す
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 を追加します。
ボリュームの名前にプロジェクトごとの値を混ぜたい場合は、${devcontainerId} 変数をソース名に入れます。Anthropicのリファレンス構成は source=claude-code-config-${devcontainerId} として、リポジトリごとに状態を分けています。
Codespaces Secretで引き継ぐ
複数のCodespaceをまたいで同じ認証を使うなら、トークンをSecretに登録します。認証を引き継ぐときに登録するのは、ANTHROPIC_API_KEY か、claude setup-token で発行する CLAUDE_CODE_OAUTH_TOKEN のどちらかです。Codespacesはこれらをコンテナ内の環境変数として自動で展開します。
claude setup-token はブラウザでの承認が必要で、発行するのは1年間有効なOAuthトークンです。トークンは端末に表示されるだけで、どこにも保存されないため、コピーしてSecretに登録します。ブラウザで承認できる環境で実行します。v2.1.287の --help では、コマンドの説明が次のように出ます。
claude setup-token --helpUsage: claude setup-token [options]
Set up a long-lived authentication token (requires Claude subscription)
Options:
-h, --help Display help for command説明に requires Claude subscription とあるとおり、このコマンドにはPro、Max、Team、Enterpriseのいずれかのプランが要ります。Consoleで発行したAPIキーで使う場合は、setup-token を使わず ANTHROPIC_API_KEY を直接Secretに登録します。
setup-token のトークンにはモデルへのリクエストしか許可がありません。Remote Controlのセッションを開始することも、claude.aiのコネクタを取得することもできません。ローカルで設定したMCPサーバーは従来どおり動きます。また、bare modeは CLAUDE_CODE_OAUTH_TOKEN を読みません。
Secretには、アクセスを許すリポジトリを選べます。選んだリポジトリから作ったCodespaceだけで使えます。同名のSecretが組織やリポジトリにもある場合は、より下位のレベルのものが優先されます。
Secretには制約もあります。登録できるのは100個までで、1つあたり48KBが上限です。名前を GITHUB_ で始めることはできません。
2つを同時に登録したときの優先順位
ANTHROPIC_API_KEY と CLAUDE_CODE_OAUTH_TOKEN の両方が環境変数にあると、Claude Codeが使う認証はAPIキーのほうです。対話モードでは初回にキーを使うか承認を求められ、-p では常にAPIキーが使われます。認証の選択順では、APIキーが3番目、CLAUDE_CODE_OAUTH_TOKEN が5番目、/login のサブスクリプション認証が7番目に並びます。サブスクリプションの枠で使うつもりなら、ANTHROPIC_API_KEY を同じCodespaceに残さないようにします。
また、Secretを入れた環境で /login を実行すると、そのセッションは新しいログインに切り替わります。ただし CLAUDE_CODE_OAUTH_TOKEN は新しいセッションのたびに読み直されます。環境変数を外すまで、トークンが優先され続けます。
追加したSecretが見えないとき
既存のCodespaceにSecretを足した直後は、環境変数に出てきません。Secretは新しいCodespaceの作成時か、Codespaceの再開時に読み込まれます。実行中のCodespaceで使いたければ、一度停止して再開します。作り直す必要はありません。
長時間の自律実行でCodespaceが止まる
Claude Codeに長いタスクを任せて席を離れると、Codespaceのほうが先に止まることがあります。Codespacesは既定で30分操作が無いと停止します。
延長は個人設定のタイムアウトか、gh codespace create の --idle-timeout で行います。指定できるのは5分から240分(4時間)の範囲です。個人設定の変更が及ぶのは、変更後に作る新しいCodespaceだけです。
タイムアウトを240分にしても、Codespaceの最大寿命は12時間です。組織のポリシーが既定より短い上限を決めている場合は、個人設定ではなく組織側の値が使われます。ターミナルの入力や出力があると、アイドル時間のカウントはリセットされます。
gh codespace create --idle-timeout 90mCodespacesでバージョンを固定する・権限を絞る
Dev Container Featureは常に最新のClaude Codeをインストールします。再現性のあるビルドが要る場合は、Featureを使わずDockerfileから入れます。コマンドは npm install -g @anthropic-ai/claude-code@X.Y.Z です。あわせて containerEnv に DISABLE_AUTOUPDATER を "1" で設定します。
組織のポリシーを入れるなら、Linuxで読まれる /etc/claude-code/managed-settings.json をDockerfileからコピーします。ここに書いた値は、個人の ~/.claude やプロジェクトの .claude/ より優先されます。ただしDockerfileはリポジトリの書き込み権限があれば誰でも変更できるため、迂回させたくないポリシーはサーバー管理設定やMDMで配ります。
テレメトリ関連の環境変数にも注意点があります。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC を containerEnv に入れると、フィーチャーフラグの取得も止まります。Remote Controlなど、その取得に頼る機能はコンテナ内で使えなくなります。
--dangerously-skip-permissions を付けた無人運転では、コンテナ内のあらゆる情報が悪意あるプロジェクトの持ち出し対象になり得ます。~/.claude にある認証情報も含みます。このフラグはroot起動では拒否されるため、remoteUser に非rootのアカウントを指定します。信頼できるリポジトリだけで使い、~/.ssh などのホスト側のシークレットはマウントしません。
このフラグ自体を使わせたくない場合は、管理設定で permissions.disableBypassPermissionsMode を "disable" にします。
MCPサーバーをCodespacesで使う
チームのMCPサーバー設定をCodespacesでも有効にしたい場合は、.mcp.json をリポジトリのルートに置き、プロジェクトスコープで定義します。DevContainer設定と一緒にコミットしておけば、誰がCodespaceを開いても同じMCPサーバーが使えます。ローカルのstdioサーバーが依存するバイナリはDockerfileでインストールし、リモートサーバーのドメインはネットワーク許可リストに追加します。設定項目の細部やスコープの使い分けはClaude Code MCP設定ガイドにあります。
ローカルDevContainer・Docker sandbox・self-hosted runnerとの違い
Codespacesは選択肢の一つです。ローカルのDevContainerとは、コンテナが動く場所と、認証を残す手段が違います。
Codespacesでは、停止して再開しても ~/.claude は残り、リビルドで消えます。Secretは新しいCodespaceの作成時か再開時に読み込まれます。コンテナがGitHubのクラウドで動くため、ローカルのDockerを使うDevContainerとは、認証を残す設定の置き場所が変わります。
セキュリティ境界を厳格に設計したい場合は、DevContainer / Docker sandbox完全実装がcapability制限やネットワーク遮断まで扱っています。自社インフラでクラウドセッションを完結させたい場合は、Claude Code self-hosted-runnerとはが導入手順を扱います。
まとめ
長い自律実行を任せるなら、アイドルタイムアウトを240分に伸ばしても、最大寿命の12時間が先に上限になります。認証は、同じCodespaceを使い続けるか、使い捨てで作り直すかで、手当ての置き場所が決まります。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。