---
title: セルフホスト型Claude Managed Agentsを始める
url: https://platform.claude.com/docs/ja/managed-agents/self-hosted/quickstart
description: Docker Composeを使って1台のマシンでセルフホスト型Claude Managed Agentsを起動し、サンドボックスコンテナで最初のセッションを実行します。
---
セルフホスト型Claude Managed Agentsへのアクセスをリクエストするには、Anthropicのアカウントチームにお問い合わせください。
このクイックスタートでは、Docker Composeを使ってセルフホスト型Claude Managed Agentsを1台のマシンで起動します。Composeスタックは、サーバー、そのPostgreSQLデータベース、そして各セッションをそれぞれ専用のサンドボックスコンテナで実行する一連の「worker」（ワーカー）で構成されます。その後、ターミナルからエージェントとチャットし、そのツール呼び出しがサンドボックスコンテナ内で実行されたことを確認します。その後、[サーバー上のコンソール](https://platform.claude.com/docs/ja/managed-agents/self-hosted/console)でセッションを開くこともできます。
Composeスタックは開発向けであり、本番環境向けではありません。プレーンなHTTPで提供され、デフォルトではポート8400をDockerホストのループバックアドレスである`127.0.0.1`でのみ公開します。28.3.3より前の一部のDocker Engineリリースでは、ホストのローカルネットワーク上のマシンもそのポートに到達できます。エージェントのツールはそのホスト上のコンテナで実行されるため、保護が必要なものを何も保持していないマシンを使用してください。
本番環境では、Anthropicはリリースに含まれる2つのHelmチャートを使用することを推奨します。[Kubernetesにデプロイする](https://platform.claude.com/docs/ja/managed-agents/self-hosted/kubernetes)を参照してください。
このクイックスタートをClaude Codeに実行させる
```text
https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md に従って、このマシンにセルフホスト型Claude Managed Agentsをセットアップしてください。リリースアーカイブはすでにダウンロード済みです。
```
あなたが人に代わってこれらの手順を実行するエージェントである場合：
* **リリースアーカイブ：**アーカイブの場所をその人に尋ねてください。ダウンロードできるのはその人だけです。
* **Claude APIキー：**`.env`はその人自身に編集してもらってください。キーを尋ねたり、`.env`の内容を出力したりしないでください。
* **変数：**シェルがコマンド間で変数を保持しない場合は、各`ant`コマンドで`ANTHROPIC_BASE_URL`と`ANTHROPIC_API_KEY`を改めて設定してください。これらがないと、`ant`はホスト型サービスを呼び出します。
* **Compose：**シェルの値がサーバーに渡らないように、各`docker compose`コマンドの前に`env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN`を付けてください。
* **チャット：**`ant beta:sessions connect`には対話型ターミナルが必要です。対話型ターミナルがない場合は、`ant beta:sessions:events send`でメッセージを送信し、`ant beta:sessions:events list`で応答を読み取ってください。[イベントを送信する](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#send-events)と[過去のイベントを一覧表示する](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#list-past-events)に例があります。
* **コンソール：**「サーバー上でコンソールを試す」のセクションは、その人から求められた場合にのみ実行してください。シェルがコマンド間で変数を保持しない場合は、そのセクション以降の各`docker compose`コマンドの前に`COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml`も付けてください。
## 前提条件
* **リリースアーカイブ：**ダウンロードへのアクセスをリクエストするには、Anthropicのアカウントチームにお問い合わせください。
* **Claude APIキー：**サーバーはモデル呼び出しにこれを使用します。[Claude Console](https://platform.claude.com/settings/keys)で作成してください。
* **Docker：** Composeプラグインを備えた[Docker Engineの最新バージョン](https://docs.docker.com/engine/install/)（旧来の`docker-compose`ではなく`docker compose`）が必要です。
* **少なくとも2つのCPUを備えたホスト：** x86-64またはArm。これより小さいホストでは、`.env`を作成する際に`CMA_SANDBOX_CPUS`をそのホストのCPU数に設定してください。
* **初回起動時のネットワークアクセス：**初回のビルドでは、Docker Hub、Alpineのパッケージリポジトリ、GitHubのリリースからプルします。
* **ツール：**Dockerを実行するマシンには、`openssl`と[`ant` CLI](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/quickstart#installation)が必要です。
## スタックを起動する
アーカイブを展開し、その`compose`ディレクトリで作業します。コマンド内の``を、`.tar.gz`を除いたアーカイブの名前に置き換えてください。
```bash
tar -xzf .tar.gz && cd /compose
```
umaskが`022`より厳しい場合、バイナリは他のユーザーに対する実行権限を失い、サーバーコンテナから起動できません。その場合は、umaskを`022`に設定してから、アーカイブをもう一度展開してください。
Composeは、`docker-compose.yml`と同じ場所にある`.env`ファイルからスタックのシークレットを読み取ります。ファイルを作成します。
```bash
cat > .env <
スタックをビルドして起動し、その後サーバーのログを追跡します。
```bash
docker compose up --build -d
docker compose logs -f cma-server
```
ログに`msg="cma-server listening"`を含む行が表示されたら、Ctrl+Cを押してログの追跡を停止します。
```bash
curl -s http://127.0.0.1:8400/cma-server/readyz
```
準備ができたサーバーは`"status":"ready"`で応答します。起動直後は、最初のチェックが実行されている数秒間、`"status":"degraded"`で応答することがあります。`degraded`のままの場合、または`"status":"not_ready"`で応答する場合は、[トラブルシューティング](https://platform.claude.com/docs/ja/managed-agents/self-hosted/quickstart#troubleshooting)を参照してください。
## 最初のセッションを実行する
`ant` CLIを使って、エージェントを作成し、ターミナルからチャットします。
同じディレクトリで2つ目のターミナルを開き、`ant`専用にしてください。[セルフホスト型サーバーでAPIを呼び出す](https://platform.claude.com/docs/ja/managed-agents/self-hosted/call-the-api)で説明しているように、次のコマンドは`ANTHROPIC_API_KEY`にClaude APIキーではなくサーバーAPIキーを設定します。
```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)
```
`docker compose`コマンドは最初のターミナルで実行してください。このターミナルで`docker compose up`を実行すると、Composeがこれらの変数をサーバーに渡し、サーバーはClaude APIではなく自分自身を呼び出します。
コマンドの後に示すファイルを`quickstart-agent.md`として保存してから、コマンドを実行します。このファイルにより、エージェントは組み込みツールを使用でき、事前に確認を求めることなくそれらを実行できます。
```bash CLI
ant apply --yes quickstart-agent.md
```
```markdown
---
name: Quickstart agent
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful assistant.
```
コマンドはまず、`404`エラーとともに`could not determine the organization and workspace`という警告を出力し、その後エージェントを作成します。これは自身のサーバーでは想定どおりの動作です。
これらのコマンドは、エージェントとスタックの環境を見つけてセッションを開始し、セッションのIDを`SESSION_ID`に保持します。スタックは環境に`compose-sandbox`という名前を付けます。
```bash
AGENT_ID=$(ant beta:agents list --format raw \
--transform 'data.#(name=="Quickstart agent").id' --raw-output)
ENVIRONMENT_ID=$(ant beta:environments list --format raw \
--transform 'data.#(name=="compose-sandbox").id' --raw-output)
SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
--environment-id "$ENVIRONMENT_ID" --transform id --raw-output)
```
ターミナルをセッションに接続します。
```bash
ant beta:sessions connect "$SESSION_ID"
```
このコマンドは、セッションの[チャットビュー](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/sessions-connect)を開きます。次のメッセージを送信してください。
```text wrap
Run `hostname` with the bash tool and tell me the output.
```
エージェントは`cma-sandbox-`で始まるホスト名を返します。これはコマンドを実行したサンドボックスコンテナの名前であり、ツールが手元のマシンではなくサンドボックス内で実行されたことを示しています。
チャットは開いたままにしておきます。最初のターミナルで、サンドボックスコンテナを一覧表示します。
```bash
docker ps --filter label=cma-server.sandbox
```
一覧には、エージェントが報告したコンテナが表示されます。コンテナはターンが終了してから約1分後に終了し、セッションの次のメッセージで新しいコンテナが起動します。一覧が空の場合は、エージェントにもう一度`hostname`の実行を依頼し、エージェントが応答している間にもう一度コンテナを一覧表示してください。
チャットを終了するには、そのターミナルでCtrl+Cを押します。セッションは引き続き実行されます。
## サーバー上でコンソールを試す
このセクションは省略可能です。コンソールにはシングルサインオンが必要です。これを試すには、リリースに含まれるモックのサインインプロバイダーを使ってスタックを再起動します。マシンのポート8080が空いている必要があります。
モックプロバイダーは使い捨てのデータでのみ使用してください。モックプロバイダーは、そこにアクセスできる誰にでも管理者のトークンを渡します。Docker Desktopでは、これにはサンドボックスコンテナも含まれます。28.3.3より前の一部のDocker Engineリリースでは、ネットワーク上のマシンも含まれます。
最初のターミナルで次のコマンドを実行します。
```bash
export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
docker compose up --build -d
```
`export`行は最初のターミナルでのみ有効なため、`docker compose`用に新しいターミナルを開いた場合は、そのターミナルでもう一度実行してください。このスタックでサーバーの設定を変更するには、`compose.config.yaml`ではなく`compose.config.oidc.yaml`を編集してから、`docker compose restart cma-server`を実行してください。
同じマシン上のブラウザで`http://127.0.0.1:8400/`を開き、**Continue with SSO**をクリックして、デモ管理者である**alice**を選択します。サイドバーで**Sessions**を選択し、次にセッションを選択します。
ページはエージェントの作業に合わせて更新され、そこからエージェントにメッセージを送信することもできます。
コンソールでエージェントを作成したりセッションを開始したりするには、[コンソールからエージェントを実行する](https://platform.claude.com/docs/ja/managed-agents/self-hosted/console#run-an-agent-from-the-console)を参照してください。
## スタックを停止する
最初のターミナルで、次のコマンドを実行します。
```bash
docker compose down --remove-orphans
```
このコマンドはコンテナを削除し、データベースは保持します。データベースも削除し、それとともにその中のすべてのエージェント、セッション、セッション履歴を削除するには、`docker compose down --remove-orphans -v`を実行してください。
## トラブルシューティング
* **アーカイブに`compose`ディレクトリがない：**アーカイブは以前のリリースのものであり、このページのコマンドはそれに対応していません。現在のリリースについては、Anthropicのアカウントチームにお問い合わせください。実行中のデプロイメントを現在のリリースに移行するには、[セルフホスト型Claude Managed Agentsをアップグレードする](https://platform.claude.com/docs/ja/managed-agents/self-hosted/upgrade)を参照してください。
* **サーバーが起動しない：**`docker compose logs migrate`を実行してください。一度だけ実行される`migrate`コンテナがデータベースのテーブルを作成します。サーバーが起動する前に、このコンテナがステータス`0`で終了している必要があります。
* **準備状況チェックが`degraded`のままになる、またはすべてのターンが失敗する：**`ANTHROPIC_BASE_URL`が`http://127.0.0.1:8400`に設定されているターミナルで`docker compose up`を実行した場合、サーバーはClaude APIではなく自分自身を呼び出します。この変数が設定されていない最初のターミナルで、もう一度`docker compose up -d`を実行してください。それ以外の場合は、サーバーのログに失敗の内容が表示されます。ログを読むには、もう一度`docker compose logs -f cma-server`を実行してください。
* **準備状況チェックが`not_ready`で応答する：**応答の中で、状態が`failed`になっているチェックを探してください。
* **`upstream`：**Claude APIがClaude APIキーを拒否しました。`.env`の`ANTHROPIC_API_KEY`を修正してから、最初のターミナルでもう一度`docker compose up -d`を実行してください。シェルでも`ANTHROPIC_API_KEY`が設定されている場合、Composeはシェルの値を使用するため、先に`unset ANTHROPIC_API_KEY`を実行してください。
* **`database`：**データベースがサーバーのログインを拒否した（たとえばパスワードが間違っている場合）か、データベースへの開いている接続が切断されました。どちらであるかを確認するには、もう一度`docker compose logs -f cma-server`を実行してください。
* **エージェントは応答するが、ツール呼び出しが完了しない：**環境をポーリングしているワーカーがありません。`docker compose logs sandbox`でワーカーのログを確認してください。Dockerデーモンのソケットに到達できないワーカーは、`CMA_DOCKER_SOCKET`を示すメッセージを出して終了します。`.env`でその変数にデーモンのソケットパスを設定してから、最初のターミナルで、もう一度`docker compose up -d`を実行してください。
* **ワーカーは実行されているが、それでもツール呼び出しが完了しない：**スタックは10個のワーカーを起動し、各ワーカーは一度に1つのセッションのコンテナを実行します。セッションは作成時に空いているワーカーを1つ占有し、メッセージを一度も受け取らないセッションは最大1時間そのワーカーを保持し続けます。10個すべてが占有されていると、他のセッションのツール呼び出しはワーカーを待ちます。「サンドボックスコンテナを見つける」の手順の`docker ps`コマンドで10個のコンテナが一覧表示される場合は、使用していないセッションをアーカイブしてください。
1. 最初のターミナルで`docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'`を実行します。各コンテナの背後にあるセッションのIDが出力されます。待機しているセッションにはまだコンテナがないため、一覧には含まれません。
2. 2つ目のターミナルでCtrl+Cを押してチャットを終了し、一覧に表示されたセッションのうち使用していないものごとに`ant beta:sessions archive --session-id `を実行します。
3. もう一度`ant beta:sessions connect "$SESSION_ID"`を実行します。ワーカーがセッションを引き受けると、ツール呼び出しが完了します。
## 次のステップ
SDKと`ant` CLIをサーバーに向けます。
動作が異なる機能や利用できない機能を確認します。
サインインを設定し、ブラウザでエージェントを作成してセッションを実行します。