セルフホスト型Claude Managed Agentsを始める

このクイックスタートでは、Docker Composeを使ってセルフホスト型Claude Managed Agentsを1台のマシンで起動します。Composeスタックは、サーバー、そのPostgreSQLデータベース、そして各セッションをそれぞれ専用のサンドボックスコンテナで実行する一連の「worker」（ワーカー）で構成されます。その後、ターミナルからエージェントとチャットし、そのツール呼び出しがサンドボックスコンテナ内で実行されたことを確認します。その後、サーバー上のコンソールでセッションを開くこともできます。

本番環境では、Anthropicはリリースに含まれる2つのHelmチャートを使用することを推奨します。Kubernetesにデプロイするを参照してください。

前提条件

• リリースアーカイブ：ダウンロードへのアクセスをリクエストするには、Anthropicのアカウントチームにお問い合わせください。
• Claude APIキー：サーバーはモデル呼び出しにこれを使用します。Claude Consoleで作成してください。
• Docker： Composeプラグインを備えたDocker Engineの最新バージョン（旧来のdocker-composeではなくdocker compose）が必要です。
• 少なくとも2つのCPUを備えたホスト： x86-64またはArm。これより小さいホストでは、.envを作成する際にCMA_SANDBOX_CPUSをそのホストのCPU数に設定してください。
• 初回起動時のネットワークアクセス：初回のビルドでは、Docker Hub、Alpineのパッケージリポジトリ、GitHubのリリースからプルします。
• ツール：Dockerを実行するマシンには、opensslとant CLIが必要です。

スタックを起動する

1. 1

   アーカイブを展開する

   アーカイブを展開し、そのcomposeディレクトリで作業します。コマンド内の<archive>を、.tar.gzを除いたアーカイブの名前に置き換えてください。

   tar -xzf <archive>.tar.gz && cd <archive>/compose

   

   umaskが022より厳しい場合、バイナリは他のユーザーに対する実行権限を失い、サーバーコンテナから起動できません。その場合は、umaskを022に設定してから、アーカイブをもう一度展開してください。

2. 2

   .envファイルを作成する

   Composeは、docker-compose.ymlと同じ場所にある.envファイルからスタックのシークレットを読み取ります。ファイルを作成します。

   cat > .env <<EOF
   CMA_PG_PASSWORD=$(openssl rand -hex 32)
   ANTHROPIC_API_KEY=sk-ant-...
   CMA_SERVER__API_KEY=$(openssl rand -hex 32)
   CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
   EOF
   chmod 600 .env

   

   エディタで.envを開き、sk-ant-...をClaude APIキーに置き換えてください。残りはこのブロックが生成します。すなわち、データベースのパスワード、アプリケーションが送信するサーバーAPIキー、およびサーバーが保存するシークレットを暗号化する鍵です。

3. 3

   コンテナを起動する

   スタックをビルドして起動し、その後サーバーのログを追跡します。

   docker compose up --build -d
   docker compose logs -f cma-server

   

   ログにmsg="cma-server listening"を含む行が表示されたら、Ctrl+Cを押してログの追跡を停止します。

4. 4

   サーバーの準備ができていることを確認する

   curl -s http://127.0.0.1:8400/cma-server/readyz

   

   準備ができたサーバーは"status":"ready"で応答します。起動直後は、最初のチェックが実行されている数秒間、"status":"degraded"で応答することがあります。degradedのままの場合、または"status":"not_ready"で応答する場合は、トラブルシューティングを参照してください。

最初のセッションを実行する

ant CLIを使って、エージェントを作成し、ターミナルからチャットします。

1. 1

   CLIをサーバーに向ける

   同じディレクトリで2つ目のターミナルを開き、ant専用にしてください。セルフホスト型サーバーでAPIを呼び出すで説明しているように、次のコマンドはANTHROPIC_API_KEYにClaude APIキーではなくサーバーAPIキーを設定します。

   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ではなく自分自身を呼び出します。

2. 2

   エージェントを作成する

   コマンドの後に示すファイルをquickstart-agent.mdとして保存してから、コマンドを実行します。このファイルにより、エージェントは組み込みツールを使用でき、事前に確認を求めることなくそれらを実行できます。

   CLI

   

   ant apply --yes quickstart-agent.md

   quickstart-agent.md

   

   ---
   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という警告を出力し、その後エージェントを作成します。これは自身のサーバーでは想定どおりの動作です。

3. 3

   セッションを開始する

   これらのコマンドは、エージェントとスタックの環境を見つけてセッションを開始し、セッションのIDをSESSION_IDに保持します。スタックは環境にcompose-sandboxという名前を付けます。

   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)

   
4. 4

   エージェントにコマンドの実行を依頼する

   ターミナルをセッションに接続します。

   ant beta:sessions connect "$SESSION_ID"

   

   このコマンドは、セッションのチャットビューを開きます。次のメッセージを送信してください。

   Run `hostname` with the bash tool and tell me the output.

   

   エージェントはcma-sandbox-で始まるホスト名を返します。これはコマンドを実行したサンドボックスコンテナの名前であり、ツールが手元のマシンではなくサンドボックス内で実行されたことを示しています。

5. 5

   サンドボックスコンテナを見つける

   チャットは開いたままにしておきます。最初のターミナルで、サンドボックスコンテナを一覧表示します。

   docker ps --filter label=cma-server.sandbox

   

   一覧には、エージェントが報告したコンテナが表示されます。コンテナはターンが終了してから約1分後に終了し、セッションの次のメッセージで新しいコンテナが起動します。一覧が空の場合は、エージェントにもう一度hostnameの実行を依頼し、エージェントが応答している間にもう一度コンテナを一覧表示してください。

   チャットを終了するには、そのターミナルでCtrl+Cを押します。セッションは引き続き実行されます。

サーバー上でコンソールを試す

このセクションは省略可能です。コンソールにはシングルサインオンが必要です。これを試すには、リリースに含まれるモックのサインインプロバイダーを使ってスタックを再起動します。マシンのポート8080が空いている必要があります。

1. 1

   モックのサインインプロバイダーを使ってスタックを再起動する

   最初のターミナルで次のコマンドを実行します。

   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を実行してください。

2. 2

   セッションを開く

   同じマシン上のブラウザでhttp://127.0.0.1:8400/を開き、Continue with SSOをクリックして、デモ管理者であるaliceを選択します。サイドバーでSessionsを選択し、次にセッションを選択します。

   ページはエージェントの作業に合わせて更新され、そこからエージェントにメッセージを送信することもできます。

コンソールでエージェントを作成したりセッションを開始したりするには、コンソールからエージェントを実行するを参照してください。

スタックを停止する

最初のターミナルで、次のコマンドを実行します。

docker compose down --remove-orphans

このコマンドはコンテナを削除し、データベースは保持します。データベースも削除し、それとともにその中のすべてのエージェント、セッション、セッション履歴を削除するには、docker compose down --remove-orphans -vを実行してください。

トラブルシューティング

• アーカイブにcomposeディレクトリがない：アーカイブは以前のリリースのものであり、このページのコマンドはそれに対応していません。現在のリリースについては、Anthropicのアカウントチームにお問い合わせください。実行中のデプロイメントを現在のリリースに移行するには、セルフホスト型Claude Managed Agentsをアップグレードするを参照してください。
• サーバーが起動しない：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 <session-id>を実行します。
  3. もう一度ant beta:sessions connect "$SESSION_ID"を実行します。ワーカーがセッションを引き受けると、ツール呼び出しが完了します。

次のステップ