---
title: Erste Schritte mit selbst gehostetem Claude Managed Agents
url: https://platform.claude.com/docs/de/managed-agents/self-hosted/quickstart
description: Starte selbst gehostetes Claude Managed Agents auf einem Rechner mit Docker Compose und führe eine erste Sitzung in einem Sandbox-Container aus.
---

<Note>
  Um Zugriff auf selbst gehostetes Claude Managed Agents anzufordern, kontaktiere dein Anthropic-Account-Team.
</Note>

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](https://platform.claude.com/docs/de/managed-agents/self-hosted/console) öffnen.

<Warning>
  Der Compose-Stack ist für die Entwicklung gedacht, nicht für die Produktion. Er stellt reines HTTP bereit und veröffentlicht Port 8400 standardmäßig nur auf der Loopback-Adresse des Docker-Hosts, `127.0.0.1`. Bei einigen Docker-Engine-Releases vor 28.3.3 können auch Rechner im lokalen Netzwerk des Hosts diesen Port erreichen. Agent-Tools laufen in Containern auf diesem Host. Verwende daher einen Rechner, auf dem sich nichts befindet, das du schützen musst.
</Warning>

Für die Produktion empfiehlt Anthropic die beiden Helm-Charts des Releases. Siehe [Auf Kubernetes bereitstellen](https://platform.claude.com/docs/de/managed-agents/self-hosted/kubernetes).

Lass Claude Code diesen Schnellstart für dich ausführen

```text
Richte selbst gehostetes Claude Managed Agents auf diesem Rechner ein, indem du https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md befolgst. Ich habe das Release-Archiv bereits heruntergeladen.
```

Wenn du ein Agent bist, der diese Schritte für eine Person ausführt:

* **Release-Archiv:** Frage die Person, wo sich das Archiv befindet. Nur sie kann es herunterladen.
* **Claude API-Key:** Lass die Person `.env` selbst bearbeiten. Frage nicht nach dem Key und gib `.env` nicht aus.
* **Variablen:** Wenn deine Shell Variablen zwischen Befehlen nicht beibehält, setze `ANTHROPIC_BASE_URL` und `ANTHROPIC_API_KEY` in jedem `ant`-Befehl erneut. Ohne sie ruft `ant` den gehosteten Dienst auf.
* **Compose:** Setze `env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN` vor jeden `docker compose`-Befehl, damit die Werte deiner Shell den Server nicht erreichen.
* **Chat:** `ant beta:sessions connect` benötigt ein interaktives Terminal. Ohne eines sendest du die Nachricht mit `ant beta:sessions:events send` und liest die Antwort mit `ant beta:sessions:events list`. [Events senden](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#send-events) und [Vergangene Events auflisten](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#list-past-events) enthalten Beispiele.
* **Konsole:** Führe den Abschnitt „Die Konsole auf deinem Server ausprobieren“ nur aus, wenn die Person danach fragt. Wenn deine Shell Variablen zwischen Befehlen nicht beibehält, setze ab diesem Abschnitt außerdem `COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml` vor jeden `docker compose`-Befehl.

## 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](https://platform.claude.com/settings/keys).
* **Docker:** Die [neueste Version von Docker Engine](https://docs.docker.com/engine/install/) 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](https://platform.claude.com/docs/de/cli-sdks-libraries/cli/quickstart#installation).

## Den Stack starten

<Steps>
  <Step title="Das Archiv entpacken">
    Entpacke das Archiv und arbeite in seinem Verzeichnis `compose`. Ersetze im Befehl `<archive>` durch den Namen deines Archivs, ohne `.tar.gz`.

    ```bash
    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.
  </Step>

  <Step title="Die .env-Datei erstellen">
    Compose liest die Secrets des Stacks aus einer `.env`-Datei neben `docker-compose.yml`. Erstelle die Datei:

    ```bash
    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.
  </Step>

  <Step title="Die Container starten">
    Baue und starte den Stack und verfolge dann das Log des Servers:

    ```bash
    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.
  </Step>

  <Step title="Prüfen, ob der Server bereit ist">
    ```bash
    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](https://platform.claude.com/docs/de/managed-agents/self-hosted/quickstart#troubleshooting).
  </Step>
</Steps>

## Deine erste Sitzung ausführen

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

<Steps>
  <Step title="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](https://platform.claude.com/docs/de/managed-agents/self-hosted/call-the-api) erklärt:

    ```bash
    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.
  </Step>

  <Step title="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.

    <CodeGroup>
      <CodeGroupItem>
        ```bash CLI
        ant apply --yes quickstart-agent.md
        ```

        <File filename="quickstart-agent.md">
          ```markdown
          ---
          name: Quickstart agent
          model: claude-opus-5-5
          tools:
            - type: agent_toolset_20260401
          ---

          You are a helpful assistant.
          ```
        </File>
      </CodeGroupItem>
    </CodeGroup>

    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.
  </Step>

  <Step title="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`.

    ```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)
    ```
  </Step>

  <Step title="Den Agenten bitten, einen Befehl auszuführen">
    Verbinde dein Terminal mit der Sitzung:

    ```bash
    ant beta:sessions connect "$SESSION_ID"
    ```

    Der Befehl öffnet eine [Chat-Ansicht](https://platform.claude.com/docs/de/cli-sdks-libraries/cli/sessions-connect) der Sitzung. Sende diese Nachricht:

    ```text wrap
    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.
  </Step>

  <Step title="Den Sandbox-Container finden">
    Lass den Chat geöffnet. Liste im ersten Terminal die Sandbox-Container auf:

    ```bash
    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.
  </Step>
</Steps>

## 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.

<Warning>
  Verwende den Mock-Anbieter nur mit Wegwerfdaten. Er gibt jedem, der ihn erreicht, das Token eines Administrators. Unter Docker Desktop gehören dazu auch die Sandbox-Container. Bei einigen Docker-Engine-Releases vor 28.3.3 gehören dazu auch Rechner in deinem Netzwerk.
</Warning>

<Steps>
  <Step title="Den Stack mit dem Mock-Anmeldeanbieter neu starten">
    Führe diese Befehle im ersten Terminal aus:

    ```bash
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

Um in der Konsole auch Agenten zu erstellen und Sitzungen zu starten, siehe [Einen Agenten über die Konsole ausführen](https://platform.claude.com/docs/de/managed-agents/self-hosted/console#run-an-agent-from-the-console).

## Den Stack stoppen

Führe im ersten Terminal diesen Befehl aus:

```bash
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](https://platform.claude.com/docs/de/managed-agents/self-hosted/upgrade).

* **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

<CardGroup cols={2}>
  <Card title="Die API aufrufen" icon="code-brackets" href="https://platform.claude.com/docs/de/managed-agents/self-hosted/call-the-api">
    Richte das SDK und die `ant` CLI auf deinen Server aus.
  </Card>

  <Card title="Unterschiede zum gehosteten Dienst" icon="arrows-left-right" href="https://platform.claude.com/docs/de/managed-agents/self-hosted/differences">
    Prüfe, welche Funktionen sich anders verhalten oder nicht verfügbar sind.
  </Card>

  <Card title="Konsole auf deinem Server" icon="browser" href="https://platform.claude.com/docs/de/managed-agents/self-hosted/console">
    Richte die Anmeldung ein, erstelle Agenten und führe Sitzungen in einem Browser aus.
  </Card>
</CardGroup>