Letta App Server selbst hosten: KI-Agenten mit Langzeitgedächtnis per Docker

Letta, früher MemGPT, baut KI-Agenten, die sich über einzelne Gespräche hinaus erinnern: an Vorlieben, Projektwissen und frühere Entscheidungen. Der Hersteller hat die Plattform 2026 grundlegend umgebaut. Der alte Python-Server mit PostgreSQL und REST-API auf Port 8283 ist laut Letta am Ende seiner Lebenszeit und erhält keine Sicherheitsupdates mehr. An seine Stelle tritt der Letta App Server aus dem Paket Letta Code, der Agenten, Gedächtnis und Werkzeugausführung auf Ihrem eigenen Server hält. Diese Anleitung beschreibt den offiziellen Weg per Docker Compose mit dem Image letta/letta:0.34.0, Token-Authentifizierung, OpenAI-kompatibler Schnittstelle und optional lokalen Modellen über Ollama.

Voraussetzungen

• Server: Linux x86_64 oder ARM64 mit Docker Engine und Compose-Plugin, etwa Debian 12 oder Ubuntu 24.04. Das Image gibt es für beide Architekturen.
• CPU und RAM: 2 Kerne und 4 GB RAM genügen für den App Server. Im Test belegte der ruhende Container rund 170 MB. Mehr brauchen Sie nur, wenn Ollama auf derselben Maschine Modelle ausführt.
• Speicher: etwa 3 GB für das Image (entpackt 1,64 GB) und den Zustand der Agenten.
• Modellzugang: mindestens ein Anbieter, etwa ein API-Schlüssel für OpenAI oder Anthropic, oder ein lokaler Ollama-Server. Letta empfiehlt für den Einstieg große Modelle; schwächere Modelle können Agenten laut Hersteller zu unerwartetem Verhalten bringen.
• Für den Zugriff von außen: eine Domain und ein Reverse Proxy mit HTTPS, der WebSockets weiterleitet.

Grundlagen zu Compose finden Sie in Docker Compose unter Linux als Grundlage für Selfhosting.

Schritt 1: Architektur und neuen Weg verstehen

Die Dokumentation zum alten Docker-Server steht bei Letta nur noch im Bereich „V1 SDK (legacy)“ mit dem Hinweis, das Docker-Image sei kein aktiv gepflegtes Produkt mehr. Gemeint ist der Python-Server bis Version 0.16.8 vom Mai 2026. Die Tags 0.16.x bleiben laut Docker Hub nur zur Nachvollziehbarkeit erhalten und sollen nicht produktiv laufen. Unter demselben Image-Namen erscheint jetzt Letta Code, aktuell 0.34.0 vom 30.09.2026, Lizenz Apache-2.0.

Merkmal	Alter Letta-Server	Letta App Server
Tags	bis 0.16.8	ab 0.30, aktuell 0.34.0
Port	8283, REST	4500, WebSocket /ws und optional /v1
Datenhaltung	PostgreSQL	Dateien und Git-Repositorys unter /root/.letta
Authentifizierung	SECURE, LETTA_SERVER_PASSWORD	Token-Datei oder signierte Bearer-Token
Gedächtnis	Core, Recall, Archival in der Datenbank	MemFS: Markdown-Dateien in einem Git-Repository je Agent

Das Gedächtnis heißt jetzt MemFS. Dateien unter system/ lädt der Agent in jeden Prompt, andere Dateien liest er bei Bedarf. Jede Änderung ist ein Git-Commit, damit lässt sich nachvollziehen, was ein Agent wann gelernt hat. Eine Vektorsuche ist standardmäßig nicht enthalten.

Wichtig für die Sicherheitsbewertung: Der App Server führt Werkzeuge der Agenten selbst aus und hat laut Letta Shell- und Dateisystemzugriff auf seinem Host. Im Container bedeutet das Zugriff auf den Container und seine Volumes. Planen Sie ihn deshalb wie einen Dienst mit Administratorrechten.

Verifizieren: Prüfen Sie auf https://hub.docker.com/r/letta/letta/tags, ob 0.34.0 noch der neueste nummerierte Tag ist. Ein älterer Stack mit PostgreSQL-Volume unter /var/lib/postgresql/data gehört zum alten Server und bleibt bis zur Migration unangetastet.

Schritt 2: Projektordner, Token und Compose-Datei anlegen

sudo mkdir -p /opt/letta
cd /opt/letta
openssl rand -hex 32 | sudo tee app-server-token > /dev/null
sudo chmod 600 app-server-token

Die Compose-Datei folgt dem Startbefehl aus der Beschreibung auf Docker Hub. Das offizielle Deployment-Repository letta-ai/letta-app-server-deploy erzeugt dasselbe über ein eigenes Dockerfile und ein Startskript; die direkte Variante kommt ohne Build aus.

services:
  letta:
    image: letta/letta:0.34.0
    container_name: letta-app-server
    restart: unless-stopped
    command:
      - letta
      - server
      - --backend
      - local
      - --listen
      - ws://0.0.0.0:4500
      - --ws-auth
      - capability-token
      - --ws-token-file
      - /run/secrets/app-server-token
      - --openai-api
    env_file: .env
    ports:
      - "127.0.0.1:4500:4500"
    volumes:
      - letta-state:/root/.letta
      - letta-workspace:/workspace
      - ./app-server-token:/run/secrets/app-server-token:ro

volumes:
  letta-state:
  letta-workspace:

In die Datei .env gehören die Schlüssel der Modellanbieter, zum Beispiel OPENAI_API_KEY=… oder ANTHROPIC_API_KEY=…. Legen Sie sie auch dann an, wenn Sie nur Ollama nutzen, sonst bricht Compose wegen der fehlenden Datei ab.

Parameter	Zweck
--backend local	Agentenzustand bleibt auf diesem Server, kein Letta-Konto nötig
--ws-auth capability-token	Pflicht bei einer Adresse außerhalb von 127.0.0.1
--openai-api	zusätzlich /v1/models, /v1/chat/completions, /v1/responses
/root/.letta	Agenten, Unterhaltungen, MemFS, Einstellungen
/workspace	Arbeitsverzeichnis für Werkzeuge der Agenten

Verifizieren: sudo touch .env und danach docker compose config -q enden ohne Ausgabe.

Schritt 3: App Server starten und Absicherung prüfen

docker compose pull
docker compose up -d
docker compose logs

Im Test meldete der Server nach wenigen Sekunden:

Listening on ws://0.0.0.0:4500
WebSocket: ws://0.0.0.0:4500/ws
OpenAI:  http://0.0.0.0:4500/v1

Prüfen Sie danach, dass die Authentifizierung greift. Die Endpunkte /readyz und /healthz sind für Healthchecks offen, alles andere verlangt das Token:

TOKEN=$(sudo cat /opt/letta/app-server-token)
curl -s http://127.0.0.1:4500/readyz
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4500/v1/models
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:4500/v1/models

Verifizieren: /readyz antwortet ok, /v1/models ohne Token mit 401 und mit Token mit {"object":"list","data":[]}. docker compose exec letta letta --version meldet 0.34.0 (Letta Code).

Schritt 4: Modellanbieter verbinden und Agenten anlegen

Anbieter richten Sie mit der Letta-CLI im Container ein. Für API-Schlüssel genügen die Variablen aus .env; lokale Server verbinden Sie ausdrücklich. Läuft Ollama als eigener Compose-Dienst oder auf einem anderen Rechner, geben Sie dessen Adresse an:

docker compose exec letta letta --backend local connect ollama --base-url http://OLLAMA-HOST:11434/v1
docker compose exec letta letta --backend local agents create --name assistenz --personality blank
docker compose exec letta letta --backend local agents list

Ohne Angabe von --model erhält ein neuer Agent im Test das Modell openai/gpt-5.5. Wählen Sie das Modell beim Anlegen mit --model oder später über letta model. Für lokale und OpenAI-kompatible Endpunkte setzt Letta Chat Completions mit Tool-Aufrufen voraus; wählen Sie also ein Modell, das Tool-Calling beherrscht. Die Einrichtung von Ollama selbst beschreibt Ollama und Open WebUI mit Docker, die Modellwahl Ollama-Modelle richtig auswählen.

Verifizieren: agents list zeigt den neuen Agenten mit einer ID agent-local-…. Mit Token liefert /v1/models nun einen Eintrag mit "id":"assistenz", denn der App Server stellt jeden Agenten als Modell bereit. Unter /root/.letta/lc-local-backend/memfs/<agent-id>/memory liegen persona.md und human.md mit einem ersten Git-Commit.

Schritt 5: Anwendungen anbinden

Letta empfiehlt für eigene Anwendungen das TypeScript-Paket @letta-ai/letta-agent-sdk mit dem Backend remote, das die URL in eine WebSocket-Verbindung auf /ws umsetzt:

import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";

const client = new LettaAgentClient({
  backend: "remote",
  url: process.env.LETTA_APP_SERVER_URL,
  authToken: process.env.LETTA_APP_SERVER_TOKEN,
});

Für vorhandene Werkzeuge wie Open WebUI oder LibreChat nutzen Sie die OpenAI-kompatible Schnittstelle: Basis-URL https://letta.example.de/v1, als API-Schlüssel das Token, als Modell den Namen des Agenten. Eine Unterhaltung bleibt laut Dokumentation nur erhalten, wenn der Client den Header X-Letta-Chat-Key mitsendet; sonst beginnt jede Anfrage eine neue, temporäre Unterhaltung, das Langzeitgedächtnis des Agenten bleibt davon unberührt.

Das Token gehört in das Backend Ihrer Anwendung und nie in Code, der im Browser läuft. Wer es kennt, kann über die Agenten Befehle im Container ausführen.

Verifizieren: Eine WebSocket-Anfrage ohne Token auf /ws beantwortet der Server mit 401, mit gültigem Token mit 101 Switching Protocols. Im Test lieferte ein falsches Token auf /v1/models die Meldung invalid websocket bearer token.

Schritt 6: Reverse Proxy, Backup und Updates

Für den Zugriff von außen genügt ein Reverse Proxy mit HTTPS, der WebSocket-Verbindungen durchreicht. Caddy erledigt das ohne Zusatzkonfiguration:

letta.example.de {
    reverse_proxy 127.0.0.1:4500
}

Die Einrichtung beschreibt Caddy als Reverse Proxy einrichten. Bei nginx setzen Sie die Header Upgrade und Connection sowie lange Lese-Timeouts, weil Agentenläufe mehrere Minuten dauern können.

Letta sichert selbst gehostete Agenten nicht automatisch. Sichern Sie das Volume regelmäßig, am besten bei gestopptem Dienst:

cd /opt/letta
docker compose stop
docker run --rm -v letta_letta-state:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/letta-state-$(date +%F).tgz -C /data .
docker compose start

Den Volume-Namen zeigt docker volume ls; Compose stellt den Projektnamen voran. Für ein Update ändern Sie den Tag in compose.yaml, führen docker compose pull und docker compose up -d aus und prüfen erneut /readyz.

Verifizieren: tar tzf letta-state-*.tgz | head zeigt ./lc-local-backend/ und ./settings.json. Nach einem Neustart listet agents list dieselben Agenten, und curl -s -o /dev/null -w '%{http_code}\n' https://letta.example.de/readyz liefert 200.

Typische Fehler

Container beendet sich mit Exit-Code 64

Das neue Image erkennt Einstellungen des alten Servers und bricht ab. Im Test mit dem alten Startbefehl lautete die Meldung: The retired Python Letta server is end-of-life and this image now contains Letta Code. Auslöser sind die Variablen SECURE, LETTA_SERVER_SECURE, LETTA_SERVER_PASSWORD, ein Volume unter /var/lib/postgresql/data oder der alte Startbefehl. Bauen Sie den Dienst nach Schritt 2 neu auf und bewahren Sie die alte Datenbank als Sicherung auf.

„refusing to start non-loopback websocket listener“

Der Server verweigert den Start auf 0.0.0.0 ohne Authentifizierung: Error: refusing to start non-loopback websocket listener 0.0.0.0:4600 without auth. Ergänzen Sie --ws-auth capability-token und --ws-token-file.

HTTP 426 beim Verbinden

Ältere Clients verbinden sich mit ?channel=control oder ?channel=stream. Der App Server lehnt das mit 426 ab und erwartet eine einzige Verbindung auf /ws.

Ollama „verbunden“, aber keine Antworten

Im Test meldete connect ollama auch dann Connected Ollama (local), wenn unter der angegebenen Adresse kein Ollama lief. Prüfen Sie die Erreichbarkeit vorher aus dem Container mit docker compose exec letta curl -s http://OLLAMA-HOST:11434/api/tags. localhost zeigt im Container auf den Container selbst.

Häufige Fragen

Kann ich meine Agenten aus dem alten Server übernehmen?

Nicht durch Umhängen des Volumes. Letta schreibt ausdrücklich, dass die alte PostgreSQL-Datenbank nicht in den neuen Server eingebunden werden kann. Sichern Sie sie und legen Sie die Agenten neu an; wichtige Inhalte des alten Kerngedächtnisses übernehmen Sie in persona.md und human.md.

Gibt es eine Weboberfläche?

Der App Server selbst hat keine. Sie bedienen ihn über das Agent SDK, die WebSocket-Schnittstelle oder OpenAI-kompatible Clients wie Open WebUI, wenn --openai-api aktiv ist.

Brauche ich eine GPU?

Für den App Server nicht. Eine GPU brauchen Sie nur, wenn lokale Modelle über Ollama auf derselben Maschine laufen.

Wo liegen die Daten genau?

Unter /root/.letta/lc-local-backend: Agenten als JSON-Dateien, Unterhaltungen und je Agent ein Git-Repository unter memfs/<agent-id>/memory. Mit git log in diesem Ordner sehen Sie jede Änderung am Gedächtnis.

Fazit

Wer Letta selbst betreibt, sollte vom alten Docker-Server auf den App Server wechseln: Er ist gepflegt, schlank und hält Agenten samt Gedächtnis nachvollziehbar in Git-Repositorys auf dem eigenen Server. Der Preis ist ein Neuanfang ohne Datenübernahme und ein Dienst, der Befehle ausführen darf. Binden Sie ihn deshalb an 127.0.0.1, schützen Sie das Token wie ein Administratorpasswort und sichern Sie das Volume regelmäßig.

Weiterführende Anleitungen und Quellen

• Ollama und Open WebUI mit Docker
• Ollama-Modelle richtig auswählen
• Caddy als Reverse Proxy einrichten
• Docker Compose absichern: Secrets, Healthchecks und Non-Root
• Letta: Self-hosting
• Letta App Server
• App Server Quickstart mit OpenAI-kompatibler API
• MemFS
• letta/letta auf Docker Hub
• Offizielles Deployment-Repository
• Letta Code auf GitHub