Erste Schritte mit selbst gehostetem Claude Managed Agents

In diesem Schnellstart startest du selbst gehostetes Claude Managed Agents auf einem Rechner mit Docker Compose. Der Compose-Stack besteht aus dem Server, seiner PostgreSQL-Datenbank und einer Reihe von Workern, die jede Sitzung in einem eigenen Sandbox-Container ausführen. Anschließend chattest du über dein Terminal mit einem Agenten und bestätigst, dass seine Tool-Aufrufe in einem Sandbox-Container ausgeführt wurden. Danach kannst du die Sitzung in der Konsole auf deinem Server öffnen.

Für die Produktion empfiehlt Anthropic die beiden Helm-Charts des Releases. Siehe Auf Kubernetes bereitstellen.

Voraussetzungen

• Das Release-Archiv: Um Zugriff auf den Download anzufordern, wende dich an dein Anthropic-Account-Team.
• Ein Claude API-Key: Der Server verwendet ihn für Modellaufrufe. Erstelle einen in der Claude Console.
• Docker: Die neueste Version von Docker Engine mit dem Compose-Plugin (docker compose, nicht das ältere docker-compose).
• Ein Host mit mindestens zwei CPUs: x86-64 oder Arm. Setze auf einem kleineren Host CMA_SANDBOX_CPUS auf dessen CPU-Anzahl, wenn du .env erstellst.
• Netzwerkzugriff beim ersten Start: Der erste Build lädt Daten von Docker Hub, den Alpine-Paket-Repositories und GitHub-Releases.
• Tools: Auf dem Rechner, auf dem du Docker ausführst, benötigst du openssl und die ant CLI.

Den Stack starten

1. 1

   Das Archiv entpacken

   Entpacke das Archiv und arbeite in seinem Verzeichnis compose. Ersetze im Befehl <archive> durch den Namen deines Archivs, ohne .tar.gz.

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

   

   Wenn deine umask strenger als 022 ist, verlieren die Binärdateien ihre Ausführungsberechtigung für andere Benutzer, und der Server-Container kann sie nicht starten. Setze sie in diesem Fall auf 022 und entpacke das Archiv erneut.

2. 2

   Die .env-Datei erstellen

   Compose liest die Secrets des Stacks aus einer .env-Datei neben docker-compose.yml. Erstelle die Datei:

   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

   

   Öffne .env in einem Editor und ersetze sk-ant-... durch deinen Claude API-Key. Der Block generiert den Rest: das Datenbankpasswort, den Server-API-Key, den deine Anwendungen senden, und den Schlüssel, der die gespeicherten Secrets des Servers verschlüsselt.

3. 3

   Die Container starten

   Baue und starte den Stack und verfolge dann das Log des Servers:

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

   

   Sobald das Log eine Zeile mit msg="cma-server listening" anzeigt, drücke Strg+C, um das Verfolgen zu beenden.

4. 4

   Prüfen, ob der Server bereit ist

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

   

   Ein bereiter Server antwortet mit "status":"ready". Direkt nach dem Start kann er einige Sekunden lang mit "status":"degraded" antworten, während seine ersten Prüfungen laufen. Wenn er bei degraded bleibt oder mit "status":"not_ready" antwortet, siehe Fehlerbehebung.

Deine erste Sitzung ausführen

Erstelle einen Agenten und chatte mit ihm über dein Terminal mit der ant CLI.

1. 1

   Die CLI auf deinen Server ausrichten

   Öffne ein zweites Terminal im selben Verzeichnis und verwende es für ant. Die folgenden Befehle setzen ANTHROPIC_API_KEY auf deinen Server-API-Key, nicht auf deinen Claude API-Key, wie Die API auf einem selbst gehosteten Server aufrufen erklärt:

   export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
   export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

   

   Führe docker compose-Befehle weiterhin im ersten Terminal aus. Wenn du docker compose up in diesem Terminal ausführst, übergibt Compose diese Variablen an den Server, und der Server ruft sich selbst statt der Claude API auf.

2. 2

   Einen Agenten erstellen

   Speichere die Datei, die auf den Befehl folgt, als quickstart-agent.md und führe dann den Befehl aus. Die Datei gibt dem Agenten die integrierten Tools und erlaubt ihm, diese auszuführen, ohne dich vorher zu fragen.

   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.

   Der Befehl gibt zuerst eine Warnung aus, dass er could not determine the organization and workspace, mit einem 404-Fehler, und erstellt dann den Agenten. Das ist auf deinem eigenen Server zu erwarten.

3. 3

   Eine Sitzung starten

   Diese Befehle finden den Agenten und die Umgebung des Stacks, starten eine Sitzung und speichern die ID der Sitzung in SESSION_ID. Der Stack nennt seine Umgebung 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

   Den Agenten bitten, einen Befehl auszuführen

   Verbinde dein Terminal mit der Sitzung:

   ant beta:sessions connect "$SESSION_ID"

   

   Der Befehl öffnet eine Chat-Ansicht der Sitzung. Sende diese Nachricht:

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

   

   Der Agent antwortet mit einem Hostnamen, der mit cma-sandbox- beginnt. Das ist der Name des Sandbox-Containers, der den Befehl ausgeführt hat, was bestätigt, dass das Tool in einer Sandbox und nicht auf deinem Rechner lief.

5. 5

   Den Sandbox-Container finden

   Lass den Chat geöffnet. Liste im ersten Terminal die Sandbox-Container auf:

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

   

   Die Liste zeigt den Container, den der Agent gemeldet hat. Der Container wird etwa eine Minute nach dem Ende eines Turns beendet, und die nächste Nachricht der Sitzung startet einen neuen Container. Wenn die Liste leer ist, bitte den Agenten, hostname erneut auszuführen, und liste die Container erneut auf, während er antwortet.

   Um den Chat zu verlassen, drücke Strg+C in seinem Terminal. Die Sitzung läuft weiter.

Die Konsole auf deinem Server ausprobieren

Dieser Abschnitt ist optional. Die Konsole erfordert Single Sign-on. Um sie auszuprobieren, starte den Stack mit dem Mock-Anmeldeanbieter des Releases neu. Port 8080 auf deinem Rechner muss frei sein.

1. 1

   Den Stack mit dem Mock-Anmeldeanbieter neu starten

   Führe diese Befehle im ersten Terminal aus:

   export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
   docker compose up --build -d

   

   Die export-Zeile gilt nur für das erste Terminal. Führe sie daher in jedem neuen Terminal, das du für docker compose öffnest, erneut aus. Um die Einstellungen des Servers in diesem Stack zu ändern, bearbeite compose.config.oidc.yaml, nicht compose.config.yaml, und führe dann docker compose restart cma-server aus.

2. 2

   Die Sitzung öffnen

   Öffne in einem Browser auf demselben Rechner http://127.0.0.1:8400/, klicke auf Continue with SSO und wähle alice, die Demo-Administratorin. Wähle in der Seitenleiste Sessions und dann die Sitzung aus.

   Die Seite wird aktualisiert, während der Agent arbeitet, und du kannst dem Agenten von dort aus eine Nachricht senden.

Um in der Konsole auch Agenten zu erstellen und Sitzungen zu starten, siehe Einen Agenten über die Konsole ausführen.

Den Stack stoppen

Führe im ersten Terminal diesen Befehl aus:

docker compose down --remove-orphans

Der Befehl löscht die Container und behält die Datenbank. Um auch die Datenbank zu löschen, mit jedem Agenten, jeder Sitzung und jedem Sitzungsverlauf darin, führe docker compose down --remove-orphans -v aus.

Fehlerbehebung

• Dein Archiv hat kein Verzeichnis compose: Das Archiv enthält ein früheres Release, und die Befehle dieser Seite passen nicht dazu. Frage dein Anthropic-Account-Team nach dem aktuellen Release. Um ein laufendes Deployment auf das aktuelle Release zu bringen, siehe Selbst gehostetes Claude Managed Agents aktualisieren.
• Der Server startet nie: Führe docker compose logs migrate aus. Der einmalige migrate-Container erstellt die Datenbanktabellen. Er muss mit Status 0 beendet werden, bevor der Server startet.
• Die Bereitschaftsprüfung bleibt bei degraded, oder jeder Turn schlägt fehl: Wenn du docker compose up in einem Terminal ausgeführt hast, in dem ANTHROPIC_BASE_URL auf http://127.0.0.1:8400 gesetzt ist, ruft der Server sich selbst statt der Claude API auf. Führe docker compose up -d erneut im ersten Terminal aus, in dem die Variable nicht gesetzt ist. Andernfalls zeigt das Server-Log, was fehlgeschlagen ist. Um es zu lesen, führe erneut docker compose logs -f cma-server aus.
• Die Bereitschaftsprüfung antwortet mit not_ready: Suche in der Antwort die Prüfung mit dem Status failed:
  • upstream: Die Claude API hat deinen Claude API-Key abgelehnt. Korrigiere ANTHROPIC_API_KEY in .env und führe dann im ersten Terminal erneut docker compose up -d aus. Wenn deine Shell ebenfalls ANTHROPIC_API_KEY setzt, verwendet Compose den Wert der Shell. Führe daher zuerst unset ANTHROPIC_API_KEY aus.
  • database: Entweder hat die Datenbank die Anmeldung des Servers abgelehnt, zum Beispiel wegen eines falschen Passworts, oder eine offene Verbindung zur Datenbank ist abgebrochen. Um zu sehen, was davon zutrifft, führe erneut docker compose logs -f cma-server aus.
• Der Agent antwortet, aber sein Tool-Aufruf wird nie abgeschlossen: Kein Worker fragt die Umgebung ab. Prüfe das Log der Worker mit docker compose logs sandbox. Ein Worker, der den Socket des Docker-Daemons nicht erreichen kann, wird mit einer Meldung beendet, die CMA_DOCKER_SOCKET nennt. Setze diese Variable in .env auf den Socket-Pfad deines Daemons und führe dann im ersten Terminal erneut docker compose up -d aus.
• Die Worker laufen, aber ein Tool-Aufruf wird trotzdem nie abgeschlossen: Der Stack startet 10 Worker, und jeder davon führt jeweils den Container einer einzigen Sitzung aus. Eine Sitzung belegt einen freien Worker, sobald du sie erstellst, und eine Sitzung, die nie eine Nachricht erhält, behält ihren Worker bis zu eine Stunde lang. Sind alle 10 belegt, warten die Tool-Aufrufe jeder weiteren Sitzung auf einen Worker. Wenn der docker ps-Befehl im Schritt „Den Sandbox-Container finden“ 10 Container auflistet, archiviere die Sitzungen, die du nicht verwendest:
  1. Führe im ersten Terminal docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}' aus. Der Befehl gibt die ID der Sitzung hinter jedem Container aus. Die wartende Sitzung hat noch keinen Container und steht daher nicht in der Liste.
  2. Drücke im zweiten Terminal Strg+C, um den Chat zu verlassen, und führe ant beta:sessions archive --session-id <session-id> für jede aufgelistete Sitzung aus, die du nicht verwendest.
  3. Führe erneut ant beta:sessions connect "$SESSION_ID" aus. Der Tool-Aufruf wird abgeschlossen, sobald ein Worker seine Sitzung übernimmt.

Nächste Schritte