agency-orchestrator auf einem VPS betreiben: selbstgehostete KI-Agenten-Workflows

Kurz gesagt. agency-agents ist eine Bibliothek spezialisierter KI-Personas, agency-orchestrator das Framework, das sie als dauerhaft erreichbaren, selbstgehosteten Agenten-Server ausführt. Ein Satz oder ein YAML-Workflow schickt mehrere KI-Rollen parallel an dieselbe Aufgabe. Diese Anleitung zeigt die Installation von agency-orchestrator per Docker auf einem Contabo VPS, erreichbar von jedem Gerät. Rechne mit etwa 25 Minuten auf einem Cloud VPS 8.

Was agency-orchestrator ist und wie es zu agency-agents passt

agency-orchestrator ist das KI-Agenten-Framework, das die Persona-Bibliothek agency-agents in einen dauerhaft laufenden Multi-Agenten-Server verwandelt, den du auf einem VPS betreiben kannst. Die beiden Projekte werden häufig verwechselt, deshalb lohnt sich die Abgrenzung, bevor du irgendetwas ausrollst.

agency-agents von msitarzewski steht unter MIT-Lizenz und ist eine Sammlung von 184 englischsprachigen KI-Persona-Dateien mit über 129.000 GitHub-Sternen zum Zeitpunkt dieses Artikels. Jede Persona ist ein Markdown-Prompt, den du in Claude Code, Cursor, GitHub Copilot oder ein vergleichbares Coding-Tool einbindest. Eine Serverkomponente gibt es hier nicht und auch nichts zu deployen: agency-agents lebt vollständig in deinem lokalen Coding-Assistenten.

agency-orchestrator von jnMetaCode steht unter Apache-2.0 und ist ein eigenständiges Projekt, das genau diese agency-agents-Personas als KI-Rollen nutzt, dazu eine eigene chinesischsprachige Persona-Bibliothek. Es ergänzt eine YAML-basierte Workflow-Engine, parallele Ausführung über einen DAG, Unterstützung für 10 LLM-Provider und ein Web Studio als Oberfläche, und liefert das Ganze als Docker-Image aus. agency-orchestrator ist damit der quelloffene Teil, der auf dem VPS läuft, und der Teil, den diese Anleitung installiert.

Der Betrieb auf einem VPS statt auf dem Notebook ändert vier Dinge: deine Workflows sind dauerhaft erreichbar, sie lassen sich per API oder MCP-Aufruf aus einer CI/CD-Pipeline auslösen, ihre Ergebnisse landen immer am selben Ort, und das ganze Setup ist von jedem Gerät im Netz aus nutzbar.

Voraussetzungen

Für den Betrieb als selbstgehosteter KI-Agent brauchst du einen VPS, Docker und Zugang zu einem der zehn unterstützten LLM-Provider.

• Contabo Cloud VPS 8 (8 vCPU Cores, 24 GB RAM, 300 GB SSD) für Workflows mit hoher Parallelität und API-basierten Providern, oder Cloud VPS 4 (4 vCPU Cores, 8 GB RAM) für leichtere Workflows mit key-freien Providern wie Claude Code oder Gemini CLI
• Contabo Cloud VDS S (6 dedizierte vCores, AMD EPYC 7282, 24 GB RAM, 180 GB NVMe), wenn du lokale Ollama-Inferenz mit Modellen ab 13B Parametern planst
• Docker Engine und das Docker-Compose-Plugin
• Eine Domain und Caddy für HTTPS (optional, für das Web Studio empfohlen)
• Ein LLM-Zugang: ein API-Key von Anthropic, DeepSeek oder OpenAI, oder ein bestehendes Abo für Claude Pro/Max, Gemini oder GitHub Copilot für den key-freien Weg

Schritt 1: VPS bereitstellen und absichern

Dieser Schritt liefert dir einen gehärteten Ubuntu-Server, der bereit ist, deinen selbstgehosteten KI-Agenten unter Docker auszuführen.

1. Erstelle einen Contabo Cloud VPS 8, wähle deine Region und nimm Ubuntu 24.04 LTS.
2. Verbinde dich per SSH als root: ssh root@<your-ip>
3. Lege einen Nutzer ohne Root-Rechte an: adduser ao && usermod -aG sudo ao
4. Richte SSH-Key-Authentifizierung ein und deaktiviere die Passwort-Anmeldung.
5. Konfiguriere UFW so, dass SSH (22), HTTP (80), HTTPS (443) und der Studio-Port (8088, beschränkt auf deine IP oder hinter Caddy) erreichbar sind.
6. Aktiviere die Firewall: ufw enable

Schritt 2: Docker und Docker Compose installieren

agency-orchestrator kommt als Docker-Image, deshalb beginnt die Installation mit der Docker Engine und dem Compose-Plugin.

apt update && apt install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update && apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable --now docker
usermod -aG docker ao

Prüfe die Installation:

docker run hello-world

Schritt 3: agency-orchestrator mit Docker ausrollen

Zwei Wege bringen agency-orchestrator samt der agency-agents-Personas auf deinen VPS: ein einzelnes docker run für den schnellen Test, oder Docker Compose für ein Setup, das dauerhaft bleiben soll.

Quickstart:

docker run -d \
  --name agency-orchestrator \
  --restart unless-stopped \
  -p 8088:8088 \
  -v ao-data:/data \
  ghcr.io/jnmetacode/agency-orchestrator:latest

Docker Compose (für den Produktivbetrieb empfohlen, weil hier Volume-Mounts für Ausgaben und persistente Konfiguration mitkommen):

git clone https://github.com/jnMetaCode/agency-orchestrator.git
cd agency-orchestrator
docker compose up -d

Prüfe das Ergebnis mit curl http://localhost:8088, das dir das HTML des Web Studio zurückgeben sollte. Image-Tag, Port und die Provider-Umgebungsvariablen (DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, AO_DATA_DIR) oben sind gegen die aktuelle Dokumentation abgeglichen.

Schritt 4: LLM-Provider und API-Keys konfigurieren

agency-orchestrator erreicht seine agency-agents-Personas über einen von zwei Provider-Modi: einen API-Key oder einen key-freien CLI-Proxy. Deine Wahl entscheidet, wie zuverlässig der selbstgehostete Agent unbeaufsichtigt weiterläuft.

Variante A, Provider mit API-Key, ist die praktikable Wahl für einen VPS ohne Display. DeepSeek ist der kostengünstige Standard. Anthropic und OpenAI funktionieren genauso.

# In docker run or docker-compose.yml
DEEPSEEK_API_KEY=your_key_here
# Or for Anthropic
ANTHROPIC_API_KEY=your_key_here

Variante B, key-freie Provider wie Claude Code oder Gemini CLI, schickt Anfragen über ein bestehendes Abo. Dafür ist eine interaktive Anmeldung nötig, die auf einem lokalen Rechner unkompliziert ist, auf einem VPS ohne Display aber lästig bleibt. Für den Dauerbetrieb ist ein Provider mit API-Key die verlässlichere Wahl.

In beiden Fällen trägst du die Keys einmal auf der Providers-Seite im Web Studio ein. Sie landen im gemounteten Volume und bleiben so über Container-Neustarts hinweg erhalten.

Schritt 5: Web Studio mit Caddy und HTTPS veröffentlichen

Caddy vor dem Web Studio gibt deinem selbstgehosteten KI-Agenten mit wenigen Schritten eine echte Domain, HTTPS und einen Passwortschutz per Basic Auth.

ao.yourdomain.com {
    reverse_proxy localhost:8088
    basicauth /* {
        # Generate with: caddy hash-password
        admin $2a$14$...
    }
}

1. Installiere Caddy: apt install -y caddy
2. Lege den Caddyfile-Inhalt von oben unter /etc/caddy/Caddyfile ab.
3. Lade Caddy neu: systemctl reload caddy
4. Öffne https://ao.yourdomain.com. Das Studio sollte über HTTPS laden.

Im Studio liegen deine LLM-API-Keys. Sichere es also mit Basic Auth ab oder beschränke den Zugriff auf ein VPN oder einen bekannten IP-Bereich.

Schritt 6: Den ersten Multi-Agenten-Workflow starten

Als KI-Agenten-Framework nimmt agency-orchestrator Workflows über das Web Studio, über die CLI oder über eine MCP-Verbindung zu einem KI-Coding-Agenten wie Claude Code oder Cursor an. Alle drei Wege lösen dieselbe Persona-Verteilung aus.

Über das Web Studio, ohne eine Zeile Code:

1. Öffne https://ao.yourdomain.com.
2. Gib einen Prompt in einem Satz ein, zum Beispiel „Analysiere die Machbarkeit eines SaaS-Rechnungstools für Freelancer.“
3. Klicke auf Run. agency-orchestrator wählt die Rollen automatisch und führt einen DAG-Workflow aus.
4. Die Ergebnisse findest du im Tab Outputs.

Über die CLI, innerhalb des Containers:

docker exec -it agency-orchestrator npx ao compose \
  "PR code review covering security and performance" \
  --run

Über MCP verbindet das offiziell dokumentierte Muster Claude Code oder Cursor mit einer ao serve-Instanz auf derselben Maschine:

{
    "mcpServers": {
      "agency-orchestrator": {
        "command": "npx",
        "args": ["agency-orchestrator", "serve"]
      }
    }
}

Schritt 7: Ausgaben dauerhaft speichern und Backups automatisieren

Dein selbstgehosteter KI-Agent schreibt jedes Ergebnis nach ao-output/ im Docker-Volume unter /data. Ein tägliches Backup bringt diese Daten vom VPS weg in Sicherheit.

docker exec agency-orchestrator tar czf - /data/ao-output | \
  s3cmd put - s3://your-bucket/ao-backup-$(date +%Y%m%d).tar.gz

Plane das Ganze als Cron-Eintrag auf dem VPS-Host:

0 2 * * * /path/to/backup-script.sh

Häufige Probleme bei der Installation beheben

Fast alle Probleme mit agency-orchestrator gehen auf drei Ursachen zurück.

Der Container startet und beendet sich sofort wieder. Sieh zuerst in docker logs agency-orchestrator. Meist fehlt eine API-Key-Umgebungsvariable oder ihr Name ist falsch geschrieben, prüfe also, ob der Name mit den in Schritt 3 genannten übereinstimmt.

Das Web Studio ist unter deiner Domain nicht erreichbar. Prüfe, ob UFW die Ports 80 und 443 freigibt, ob Caddy fehlerfrei neu geladen hat (systemctl status caddy) und ob die reverse_proxy-Zeile im Caddyfile auf localhost:8088 zeigt.

Ein key-freier Provider scheitert mit einem Authentifizierungsfehler. Auf einem VPS ohne Display ist das zu erwarten. Wechsle zu einem Provider mit API-Key (Schritt 4), statt eine interaktive CLI-Sitzung ohne Display zu reparieren.

FAQ: agency-orchestrator auf einem VPS