Wie man AgentGPT mit Docker selbst hostet und lokale oder private LLM-Endpunkte anbindet

Das Self-Hosting von AgentGPT auf eigener Infrastruktur ermöglicht es Entwicklungs- und Sicherheitsteams, autonome KI-Agenten (Autonomous Agents) zu betreiben, ohne vertrauliche Prompts, strategische Projektziele oder Kundendaten an externe Cloud-APIs weiterzugeben. Da autonome Agenten Zielvorgaben rekursiv in Teilaufgaben zerlegen, Zwischenergebnisse bewerten und das Sprachmodell pro Durchlauf dutzende Male abfragen, schützt der Einsatz lokaler oder privater LLM-Endpunkte zudem vor unkontrollierbaren API-Token-Kosten und Kontingentgrenzen.

AgentGPT (als Open-Source-Projekt von Reworkd entwickelt) stellt eine webbasierte Plattform zur Orchestrierung autonomer Agenten bereit. Sie besteht aus einem Next.js-Frontend, einem FastAPI-Plattform-Backend und einer MySQL-Datenbank. Zwar ist das System standardmäßig auf die OpenAI-Cloud vorkonfiguriert, doch durch gezielte Anpassungen des Docker-Netzwerks, der Umgebungsvariablen und den Einsatz OpenAI-kompatibler lokaler Inferenz-Engines wie Ollama, LocalAI oder vLLM lässt sich eine vollständig autarke, datenschutzkonforme Umgebung einrichten.

Architekturüberblick und die Docker-Netzwerkfalle

Die Bereitstellung von AgentGPT via Docker Compose basiert auf drei primären Containern:

1. Frontend (next): Port 3000, Benutzeroberfläche zur Definition von Agenten und zur Live-Überwachung von Aufgabenschritten.
2. Plattform-Backend (platform): Port 8000, FastAPI-Dienst zur Steuerung des autonomen Ausführungszyklus und der LLM-Kommunikation.
3. Datenbank (db): Port 3306, MySQL-Instanz zur Speicherung von Ausführungshistorien, Aufgabenstatus und Einstellungen.

+-------------------------------------------------------------------------+
| Internes Docker-Netzwerk (agentgpt-network)                             |
|                                                                         |
|  [ Frontend: Next.js ] <---> [ Backend: FastAPI Platform ] <---> [ DB ] |
|         (:3000)                         (:8000)                (:3306)  |
+--------------------------------------------|----------------------------+
                                             | (REWORKD_PLATFORM_OPENAI_API_BASE)
                                             v
                     +--------------------------------------------+
                     | Host-System / Privates Netzwerk            |
                     | host.docker.internal:11434/v1              |
                     | [ Ollama / vLLM / LocalAI Endpunkt ]       |
                     +--------------------------------------------+

Die Netzwerkgrenze zwischen Container und Host

Der häufigste Fehler bei der Einbindung lokaler Modelle besteht darin, als Basis-URL http://localhost:11434 oder http://127.0.0.1:11434 zu konfigurieren. Innerhalb eines Docker-Containers verweist localhost auf den isolierten Netzwerk-Namespace des Containers selbst und erreicht nicht den auf dem Host-Betriebssystem laufenden Inferenzserver.

Die saubere Auflösung erfolgt je nach Plattform:

• macOS und Windows (Docker Desktop): Verwenden Sie http://host.docker.internal:11434/v1.
• Linux-Umgebungen: Fügen Sie extra_hosts: ["host.docker.internal:host-gateway"] zum platform-Dienst in der docker-compose.yml hinzu, damit der Container die Host-Gateway-IP auflösen kann.
• Gemeinsames Compose-Netzwerk: Läuft Ollama oder LocalAI als Container im selben Compose-Verbund, wird direkt der Dienstname verwendet (z. B. http://ollama:11434/v1).

Schritt 1: Lokalen oder privaten LLM-Endpunkt bereitstellen

Der Inferenzserver muss eine OpenAI-kompatible HTTP-REST-Schnittstelle bereitstellen (insbesondere /v1/chat/completions und /v1/models).

Option A: Ollama (Empfohlen für Workstations und Entwicklung)

Starten Sie Ollama mit Bindung an alle Schnittstellen, um Docker-Verbindungen zu ermöglichen:

# Unter Linux via systemd oder per Umgebungsvariable starten
OLLAMA_HOST=0.0.0.0:11434 ollama serve

Laden Sie ein Modell mit hoher logischer Zuverlässigkeit und präziser JSON-Formatierung:

ollama pull qwen2.5:14b
# oder
ollama pull llama3.1:8b

Prüfen Sie den Endpunkt mit cURL:

curl http://localhost:11434/v1/models

Option B: vLLM (Empfohlen für GPU-Server und Hochdurchsatz)

Starten Sie den vLLM-Server auf einem GPU-Server:

python3 -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000

Schritt 2: AgentGPT klonen und Umgebungsvariablen anpassen

Klonen Sie das offizielle Repository:

git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT

Erstellen Sie die Konfigurationsdatei aus der Vorlage:

cp .env.example .env

Relevante Konfigurationswerte in .env

Passen Sie die Datei .env im Hauptverzeichnis an (bei modularem Build auch platform/.env):

# ----------------------------------------
# LLM-Endpunkt-Konfiguration
# ----------------------------------------
# Zeigt via host.docker.internal auf den lokalen Inferenzdienst
# WICHTIG: Kein abschließender Schrägstrich (/v1 und nicht /v1/)
REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1

# OpenAI-Clients erfordern einen nicht-leeren String zur Validierung
# Lokale Server ignorieren diesen Wert; ein Dummy-Wert genügt
OPENAI_API_KEY=local-secret-key

# ----------------------------------------
# Datenbankeinstellungen
# ----------------------------------------
DATABASE_URL=mysql://root:password@db:3306/agentgpt
MYSQL_ROOT_PASSWORD=password
MYSQL_DATABASE=agentgpt

# ----------------------------------------
# Authentifizierungsschlüssel
# ----------------------------------------
NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
NEXTAUTH_URL=http://localhost:3000

Wichtiger Hinweis: Fügen Sie an REWORKD_PLATFORM_OPENAI_API_BASE weder /chat/completions noch einen doppelten Schrägstrich / an. Das Plattform-Backend hängt Pfadsegmente automatisch an; ein zusätzlicher Slash führt zu ungültigen Pfaden wie //chat/completions und HTTP-404-Fehlern.

Schritt 3: docker-compose.yml für Linux anpassen

Ergänzen Sie auf Linux-Systemen die Host-Auflösung unter dem Dienst platform:

services:
  platform:
    build:
      context: ./platform
      dockerfile: Dockerfile
    environment:
      - REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1
      - OPENAI_API_KEY=local-secret-key
      - DATABASE_URL=mysql://root:password@db:3306/agentgpt
    ports:
      - "8000:8000"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on:
      - db

  frontend:
    build:
      context: ./next
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NEXTAUTH_URL=http://localhost:3000
      - NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
    depends_on:
      - platform

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: agentgpt
    ports:
      - "3306:3306"
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Schritt 4: Container erstellen und starten

Starten Sie die Umgebung mit Docker Compose:

docker compose up -d --build

Überprüfen Sie die Protokolle, um den fehlerfreien Start von Plattform und Datenbank zu bestätigen:

docker compose logs -f platform

Sobald alle Container den Status "healthy" bzw. "running" aufweisen, öffnen Sie http://localhost:3000 im Browser.

Schritt 5: Agenten im Webinterface konfigurieren und starten

1. Einstellungen aufrufen: Klicken Sie auf das Zahnrad-Symbol (Settings) links unten in der Benutzeroberfläche.
2. Modellbezeichnung eintragen: Geben Sie den exakten Namen des auf dem lokalen Server geladenen Modells an (z. B. qwen2.5:14b oder llama3.1:8b).
3. Ausführungsparameter festlegen:
   • Temperature: Auf 0.2 bis 0.4 absenken. Autonome Aufgabenplanung erfordert strikte Schema-Treue und saubere JSON-Ausgaben; zu hohe Werte führen zu Formatfehlern oder Endlosschleifen.
   • Maximale Schleifen (Max Loops): Begrenzen Sie den Durchlauf zunächst auf 5 bis 10 Zyklen, um die lokale Rechenkapazität nicht zu blockieren.
4. Agent starten:
   • Agent Name: Local-Compliance-Reviewer
   • Goal: Analysiere die Datenschutzrisiken beim Einsatz lokaler Sprachmodelle und formuliere drei priorisierte technische Schutzmaßnahmen.
   • Klicken Sie auf Deploy Agent.
5. Ablauf beobachten: Verfolgen Sie im Dashboard, wie der Agent das Ziel strukturiert, Teilaufgaben generiert, diese über das lokale Modell ausführt und einen konsolidierten Abschlussbericht erstellt.

Praxishinweise und Modellwahl

1. Mindestanforderungen an das lokale Sprachmodell

Autonome Agenten stellen erheblich höhere Anforderungen an die logische Konsistenz als einfache Chat-Assistenten:

• Das Modell muss System-Prompts strikt befolgen und kontinuierlich valides JSON generieren.
• Es muss zuverlässig beurteilen können, ob eine Aufgabe erledigt ist, um redundante Wiederholungen zu vermeiden.

Modelle mit weniger als 7 Milliarden Parametern (7B) oder Modelle ohne spezifisches Instruction-Tuning brechen häufig aufgrund von Syntaxfehlern ab. Empfohlene Mindeststandards:

• Einstiegsbasis: Llama-3.1-8B-Instruct oder Qwen-2.5-7B-Instruct.
• Produktionsstandard: Qwen-2.5-14B/32B oder Llama-3.1-70B (quantisiert auf Multi-GPU-Systemen).

2. Kontextfenster (Context Window) erweitern

Im Verlauf mehrstufiger Agentenläufe wächst der Kontextverlauf rasch an:

• Konfigurieren Sie in Ollama via Modelfile den Parameter PARAMETER num_ctx 16384, um unbemerkte Kürzungen des Prompts während komplexer Durchläufe zu verhindern.

3. Status des Upstream-Repositories

Das GitHub-Repository reworkd/AgentGPT wurde im Januar 2026 archiviert und ist schreibgeschützt. Die Architektur eignet sich hervorragend als Referenz und stabiler Ausgangspunkt für interne Projekte; Unternehmen sollten jedoch eigene Docker-Images vorhalten, Abhängigkeiten fest pinnen und eine eigene Secrets-Verwaltung etablieren.

Referenzen

• GitHub - reworkd/AgentGPT: 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser.
• Docker Compose | Docker Docs
• GitHub - ollama/ollama: Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.