Octop selbst hosten: KI-Assistent für mehrere Nutzer
So deployen Sie Octop v0.9.19 mit Docker Compose auf einem VPS: getrennte Nutzer, OpenAI-kompatibles Backend, TLS und warum Sie den curl-Installer meiden sollten.
Was Octop ist und warum Sie es selbst hosten sollten
Octop ist ein selbst gehosteter KI-Assistent für einen Haushalt oder ein kleines Team. Der Grund, Octop selbst zu hosten statt nur ein einfaches Chat-Frontend zu verwenden, ist die Trennung der Benutzer voneinander. Open WebUI stellt eine Browser-Oberfläche vor einem Modell bereit und unterstützt außerdem mehrere Benutzer sowie Zugriffskontrollen. Octop kombiniert Benutzerkonten mit einer Administratorrolle, einem privaten Arbeitsbereich und einem eigenen Satz an Zugangsdaten für jeden Benutzer sowie einer Bibliothek spezialisierter Agenten, zwischen denen jeder Benutzer je nach Aufgabe wechseln kann. Dadurch kann ein einzelner VPS fünf Personen statt nur einer Person bereitstellen.
Das Projekt befindet sich unter github.com/TencentCloud/Octop. Es handelt sich um einen einzelnen Prozess, der ein Web-Dashboard, eine Kommandozeilenschnittstelle, Chat-Kanäle (Feishu, DingTalk, QQ, Discord, WeCom) und geplante Aufgaben bereitstellt. Als Datengrundlage dient eine einzelne SQLite-Datenbank unter ~/.octop/. Alle folgenden Schritte beziehen sich auf den Tag v0.9.19, der am 5 August 2026 veröffentlicht wurde. Wenn Sie noch zwischen Plattformen auswählen, behandelt der Vergleich von Open-WebUI-Alternativen, die Sie auf einem VPS betreiben können das weitere Umfeld.
Bevor Sie dafür einen Abend einplanen, sollten Sie einen Punkt kennen. Zum Zeitpunkt der Erstellung dieses Leitfadens war Octop eine Pre-1.0-Software, die aus der GitHub-Organisation eines Anbieters veröffentlicht wurde. Seitdem wurde am 14 September 2026 v1.0.0 getaggt. Am 20 November 2026 ist v1.0.3b7 der neueste Tag; diese Version wurde am 18 November 2026 veröffentlicht. Das Repository hat zu diesem Zeitpunkt etwa 12,300 Sterne. Die neueste stabile Version bleibt v1.0.2, veröffentlicht am 18 October 2026. Die folgenden Schritte wurden für v0.9.19 geschrieben und nicht erneut mit 1.x getestet. Die Entwicklung ist schnell, wie die Versionsnummern zeigen. Eine stabile Upgrade-Perspektive wird hier nicht zugesichert. Fixieren Sie einen Tag, lesen Sie das Changelog und halten Sie Backups vor.
Voraussetzungen
- Ein VPS mit Ubuntu 24.04, Docker Engine und dem Compose-Plugin. Sie kennen Compose noch nicht? Beginnen Sie mit den Docker-Compose-Grundlagen für einen VPS.
git, weil Sie ein Release-Tag auschecken und kein Image abrufen.- Ein Domainname, der auf den VPS zeigt, weil Sie davor TLS (Transport Layer Security) einsetzen möchten.
- Ein Modell-Backend, das die OpenAI-API unterstützt: ein lokales Ollama, ein selbst gehostetes Gateway oder ein kostenpflichtiger API-Schlüssel.
Octop selbst benötigt nur wenige Ressourcen. Es besteht aus einem Python-Prozess und einer SQLite-Datei. Die meiste Leistung benötigt das Modell-Backend. Wenn Sie das Modell auf demselben System ausführen möchten, wählen Sie die Größe des Systems entsprechend dem Modell.
Warum wir den curl-Installer nicht empfehlen
Die README-Datei von v0.9.19 beginnt mit einer einzeiligen Installationsanweisung:
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bashWir empfehlen nicht, diese Anweisung auf einem wichtigen Server direkt an bash weiterzuleiten. Das Repository enthält auch scripts/install.sh. Diese Kopie verfügt daher über eine Git-Historie und ist durch ein Tag abgedeckt. Die aus dem Tencent Cloud Object Storage-Bucket bereitgestellte Kopie ist durch den obigen Befehl nicht fest auf eine Version festgelegt. Der Bucket kann morgen andere Bytes ausliefern, und der Befehl würde diese trotzdem ausführen. Wenn das Ergebnis direkt an bash weitergeleitet wird, führt der Rechner das Skript außerdem aus, bevor Sie auch nur eine Zeile davon gelesen haben.
Der Installer schreibt außerdem direkt auf den Host und nicht in einen Container. Er verwendet uv, um Python 3.12 abzurufen und eine Umgebung zu erstellen, von der Ihr Paketmanager nichts weiß. Das spätere Entfernen ist daher eine manuelle Aufgabe.
Es gibt zwei bessere Optionen. Sie können das Skript abrufen, lesen und anschließend ausführen. Das kostet dreißig Sekunden: zuerst curl -fsSL <url> -o install.sh, dann less install.sh und anschließend bash install.sh. Oder Sie verwenden Docker. Das ist der restliche Teil dieser Anleitung. Das PyPI-Paket (pip install octop) ist zumindest ein versioniertes Artefakt, das Sie auf eine Veröffentlichung festlegen können.
Octop mit Docker Compose bereitstellen, fest auf v0.9.19 gesetzt
Die mit v0.9.19 ausgelieferte Compose-Datei erstellt das Image aus dem Repository. In dieser Anleitung bedeutet das Festlegen einer Version daher, einen Git-Tag auszuchecken. Veröffentlichten Images gibt es ebenfalls. Der Quellbaum von v0.9.19 enthält bereits einen docker-publish.yml-Workflow. Dieser wurde in v0.9.8 am 15 July 2026 hinzugefügt und erstellt für jeden v*-Tag ein Image, das anschließend zu Docker Hub gepusht wird. Seit dem 20 October 2026 veröffentlicht das Projekt die Images außerdem in der Container Registry von GitHub (docker pull ghcr.io/tencentcloud/octop:1.0.2). Das Erstellen aus dem ausgecheckten Tag ist weiterhin die strengere Festlegung, weil Sie genau den Code kompilieren, den Sie gelesen haben, statt einem Registry-Tag zu vertrauen. Das ist ein Schritt mehr, als die meisten Self-Hosting-Projekte verlangen. So legt beispielsweise ein selbst gehosteter AFFiNE-Arbeitsbereich nur einen veröffentlichten Image-Tag fest und erstellt auf Ihrem VPS überhaupt nichts. Die folgende Routine zum Klonen, Auschecken und Erstellen entspricht dem Ablauf in der Bereitstellungsanleitung für openGym. Wenn Sie das einmal eingerichtet haben, kennen Sie den grundsätzlichen Ablauf bereits.
git clone https://github.com/TencentCloud/Octop.git
cd Octop
git checkout v0.9.19Dies ist der vom Compose-File definierte Dienst, gekürzt auf die relevanten Teile:
services:
octop:
build:
context: ..
dockerfile: docker/Dockerfile
image: octop:latest
container_name: octop
restart: unless-stopped
ports:
- "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
volumes:
- ${OCTOP_DATA:-~/.octop}:/data/.octop
environment:
- HOME=/data
- OCTOP_BIND_HOST=0.0.0.0
- OCTOP_PORT=${OCTOP_PORT:-8088}
- OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:-octop}
- OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin}
- OPENAI_API_KEY=${OPENAI_API_KEY:-}Beachten Sie den build:-Block. image: octop:latest ist der Name Ihres eigenen Builds und kein Registry-Verweis. latest bezeichnet hier daher den zuletzt kompilierten Stand. Setzen Sie den Datenpfad auf einen expliziten Speicherort, statt ihn einem Standardwert zu überlassen. Legen Sie außerdem vor dem ersten Start ein echtes Passwort für das Administratorkonto fest. Schreiben Sie dies in docker/.env:
OCTOP_PORT=8088
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=<a long random password>
OCTOP_DATA=/srv/octop-dataEine wichtige Stolperfalle steckt hier im Umgang mit der restlichen Datei. Compose liest docker/.env ausschließlich, um ${...}-Platzhalter im YAML zu ersetzen. Ein Schlüssel, den Sie dieser Datei hinzufügen, erreicht den Container nicht, wenn er nicht zusätzlich unter environment: im Compose-File aufgeführt ist. Wenn Sie OCTOP_ACCESS_TOKEN_TTL nur zu .env hinzufügen, hat das keinerlei Wirkung. Compose meldet das auch nicht. Alternativ können Sie dieselben Schlüssel in ~/.octop/env innerhalb des eingebundenen Datenverzeichnisses eintragen. Octop lädt diese Datei beim Start. Die Anleitung zu Env-Dateien und Secrets in Docker Compose erklärt, warum diese beiden Mechanismen nicht dasselbe bewirken.
Erstellen und starten Sie den Dienst:
docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml ps
curl http://127.0.0.1:8088/api/healthEine betriebsbereite Instanz beantwortet die Health-Prüfung mit einem JSON-Objekt in der Form von {"ok":true,"started_at":...,"db":...,"users_loaded":0,"agents_running":0}. Bei jedem anderen Ergebnis lesen Sie docker compose -f docker/docker-compose.yml logs -f octop, bevor Sie den Browser verwenden.
Geben Sie dem gerade erstellten Image nun einen aussagekräftigen Namen. Der nächste --build überschreibt andernfalls octop:latest, und Sie können die beiden Images nicht mehr unterscheiden:
docker image tag octop:latest octop:0.9.19Beim ersten Start wird octop init ausgeführt und schreibt die anfänglichen Zugangsdaten in das Daten-Volume:
docker exec -it octop cat /data/.octop/credential.txtDie Standardwerte sind admin / octop. Sie werden nur bei der ersten Initialisierung angewendet. Das erklärt eine häufig gestellte Frage: Wenn Sie OCTOP_DEFAULT_PASSWORD ändern, nachdem der Container bereits einmal gestartet wurde, ändert sich nichts, weil das Konto bereits existiert. Ändern Sie das Passwort stattdessen im Dashboard.
Port 8088 nicht veröffentlichen
Die obige Zeile ports: bindet an alle Schnittstellen des VPS. Sobald der Container startet, ist das Dashboard unverschlüsselt über das öffentliche Internet erreichbar. Der eigene Standardwert OCTOP_BIND_HOST von Octop ist 127.0.0.1. Die Compose-Datei überschreibt ihn mit 0.0.0.0, weil der Prozess Datenverkehr außerhalb seines eigenen Netzwerk-Namespace annehmen muss. Diese Überschreibung ist korrekt. Der veröffentlichte Port ist die eigentliche Ursache für die Erreichbarkeit.
Bearbeiten Sie die Zeile ports: in docker/docker-compose.yml so, dass die Zuordnung nur auf dem Loopback-Interface lauscht:
ports:
- "127.0.0.1:${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"Versuchen Sie nicht, das mit einer einfachen Override-Datei zu beheben. Compose fügt die ports-Listen aus mehreren Dateien zusammen, anstatt sie zu ersetzen. Dadurch veröffentlichen Sie beide Zuordnungen, und die zweite kann nicht gebunden werden. Wenn Sie die Upstream-Datei unverändert lassen möchten, verwenden Sie das !override-Tag für die Sequenz. Das ist die dokumentierte Methode, um eine Sequenz zu ersetzen, statt sie anzuhängen. Die Erklärung zum Zusammenführen mehrerer Compose-Dateien beschreibt die übrigen Regeln für das Zusammenführen.
Das Binden an das Loopback-Interface behebt außerdem ein Problem, das sonst mit der Firewall auftritt. Docker schreibt seine Regeln für veröffentlichte Ports in die nat-Tabelle, und zwar vor den von ufw verwalteten Chains. Daher verhindert ufw deny 8088 keinen veröffentlichten Container-Port. Bei Docker Engine 28.0.0 oder neuer ist ein an 127.0.0.1 gebundener Port unabhängig von der Konfiguration von ufw nicht von außen erreichbar. Deshalb ist diese Lösung die richtige und keine Notlösung. Ältere Engine-Versionen erlauben Hosts im selben L2-Segment, beispielsweise anderen Rechnern im Switch Ihres Providers, den Zugriff auf Ports, die auf localhost veröffentlicht wurden. Führen Sie daher docker version aus und aktualisieren Sie die Engine, wenn der Server eine Version unter 28 meldet.
TLS mit einem Reverse Proxy vorschalten
Caddy ist der kürzeste Weg, weil es das Zertifikat selbst über ACME (automatic certificate management environment) anfordert und WebSockets ohne zusätzliche Konfiguration proxyt:
octop.example.com {
reverse_proxy 127.0.0.1:8088
}nginx erfordert mehr Sorgfalt, weil Octop den Chat über einen WebSocket streamt:
server {
listen 443 ssl;
server_name octop.example.com;
ssl_certificate /etc/letsencrypt/live/octop.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/octop.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8088;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_read_timeout 3600s;
}
}Jede Zeile erfüllt eine bestimmte Aufgabe. Der Chat läuft über WS /api/agents/{id}/chat/ws. Deshalb muss nginx die beiden Upgrade-Header weiterleiten und HTTP/1.1 zum Upstream verwenden. proxy_http_version 1.1 macht das ausdrücklich und wird bei nginx-Versionen vor 1.29.7 benötigt. Ohne ein erfolgreiches Upgrade wird das Dashboard normal geladen, aber der Chat kann keine Verbindung herstellen. v0.9.19 beendet den Streaming-Zustand nach einem fehlgeschlagenen Handshake, statt die Nachricht dauerhaft hängen zu lassen. proxy_buffering off ist wichtig, weil der Resume-Endpunkt für die Interaktion mit dem Menschen text/event-stream zurückgibt. SSE (server-sent events), die in einem Proxy-Puffer zurückgehalten werden, treffen andernfalls erst am Ende als ein Block ein, statt gestreamt zu werden. proxy_read_timeout deckt längere Zeiträume ohne Daten vom Upstream ab. Der Standardwert von 60 Sekunden kann den WebSocket trennen und upstream timed out (110: Connection timed out) protokollieren. v0.9.19 lässt die Aufgabe des Agents nach einer Trennung jedoch weiterlaufen. Ein expliziter Abbruch beendet die Aufgabe.
Wie sich JWT-Authentifizierung hinter dem Proxy verhält
Octop authentifiziert sich mit einem Bearer-Token, nicht mit einem Cookie. POST /api/auth/login gibt {access_token, token_type, expires_in, user} zurück, und spätere Aufrufe übertragen Authorization: Bearer <access_token>. Für einen Reverse Proxy ist das eine gute Nachricht: Es gibt keine Cookie-Domain, kein Secure-Flag und keine SameSite-Regel, die falsch konfiguriert werden kann. Daher verhält sich eine Sitzung, die auf http://127.0.0.1:8088 funktioniert hat, auf https://octop.example.com genauso.
Vor dem Einsatz mit echten Benutzern sollten Sie zwei Konsequenzen kennen.
Der WebSocket überträgt das Token in der URL. Der Endpunkt lautet WS /api/agents/{id}/chat/ws?token=<jwt>, weil JavaScript im Browser beim WebSocket-Handshake keinen Authorization-Header setzen kann. TLS schützt dieses Token bei der Übertragung. Es schützt das Token jedoch nicht vor Ihren eigenen Logs: nginx schreibt standardmäßig die vollständige Request-Zeile einschließlich Query-String nach access_log. Dadurch landet ein gültiges Token eines echten Benutzers in einer Klartextdatei auf dem Server. Protokollieren Sie den Pfad ohne Argumente. $uri ist der normalisierte Pfad, aus dem der Query-String bereits entfernt wurde. Fügen Sie dies in den http-Block ein und referenzieren Sie den Block im Server:
log_format octop_noargs '$remote_addr [$time_local] '
'"$request_method $uri $server_protocol" '
'$status $body_bytes_sent';
access_log /var/log/nginx/octop.log octop_noargs;Logout widerruft ein Token in v0.9.19 nicht. OCTOP_ACCESS_TOKEN_TTL ist standardmäßig auf 86400 gesetzt. Daher bleibt ein Token nach der Anmeldung 24 Stunden gültig. Die einzige dokumentierte Möglichkeit, ein Token ungültig zu machen, ist octop admin rotate-jwt-secret. Dabei wird der unter ~/.octop/secrets/jwt_secret gespeicherte Signaturschlüssel ausgetauscht und alle noch gültigen Token werden sofort für alle Benutzer ungültig. Wenn jemand das Team verlässt, ist die Reihenfolge daher: Benutzer löschen, Secret austauschen und die verbleibenden Benutzer anschließend zur erneuten Anmeldung auffordern. Wenn das zu aufwendig ist, verkürzen Sie die Gültigkeitsdauer. Denken Sie daran, die Variable sowohl in die environment:-Liste als auch in .env aufzunehmen:
OCTOP_ACCESS_TOKEN_TTL=28800Brute-Force-Angriffe werden behandelt: OCTOP_LOGIN_MAX_ATTEMPTS ist standardmäßig auf 5 Fehlversuche und OCTOP_LOGIN_LOCKOUT_SECONDS auf 900 gesetzt. Ein gesperrter Benutzer wartet daher einfach 15 Minuten, statt eine fehlerhafte Installation vorzufinden. Octop verfügt über einen eigenen Benutzerspeicher und bietet in v0.9.19 keine dokumentierte OIDC-Unterstützung. Wenn Sie echtes Single Sign-on benötigen, setzen Sie einen authentifizierenden Proxy davor. Dafür ist ein selbst gehosteter Authentik-Server vorgesehen. Die integrierte OIDC-Unterstützung wurde in v0.9.24 am 15 August 2026 eingeführt.
Octop mit einem Modell-Backend verbinden
Provider werden pro Agent im Dashboard konfiguriert. octop provider list zeigt Ihnen die aktuelle Konfiguration. Octop enthält Voreinstellungen für OpenAI-kompatible APIs, DashScope (Qwen) und Ollama. Die Zugangsdaten werden in der Tabelle providers Ihrer eigenen SQLite-Datenbank gespeichert. Die Auswahl bestimmt, welche Kosten entstehen und welche Daten den Server verlassen.
Ein lokales Modell mit Ollama. Der Server verlässt nicht, und Sie bezahlen mit RAM statt mit Tokens. Das wichtige Detail bei der Verbindung wird häufig übersehen: Ein Container kann Ollama auf dem Host unter 127.0.0.1:11434 nicht erreichen, weil diese Adresse auf die Loopback-Schnittstelle des Containers selbst zeigt. Fügen Sie dem Dienst einen Host-Gateway-Eintrag hinzu:
extra_hosts:
- "host.docker.internal:host-gateway"Setzen Sie anschließend die Basis-URL des Providers auf http://host.docker.internal:11434/v1. Das ist Ollallas OpenAI-kompatibler Pfad. Tragen Sie im Feld für den API-Schlüssel eine beliebige nicht leere Zeichenfolge ein, weil Ollama den Schlüssel ignoriert, OpenAI-Clients aber keinen leeren Schlüssel senden. Ollama muss außerdem über die Loopback-Schnittstelle hinaus Verbindungen annehmen. Dafür ist OLLAMA_HOST=0.0.0.0:11434 in seiner systemd-Unit erforderlich. Das ist der riskante Teil: Ollamas lokale API benötigt keine Authentifizierung. Ein offener Port 11434 auf einer öffentlichen IP-Adresse stellt daher jedem, der ihn zuerst scannt, kostenlos einen Modellserver bereit. Erlauben Sie nur den privaten Docker-Adressbereich sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp und verweigern Sie alle anderen Zugriffe. Ollama auf einem VPS betreiben behandelt die Dimensionierung des Modells. Der Vergleich von Ollama und vLLM erklärt, wann Ollama nicht mehr der geeignete Server ist.
Noch ein Hinweis zu lokalen Modellen, weil dieses Verhalten wie ein Fehler in Octop aussieht, aber keiner ist. Agenten arbeiten, indem sie Tools aufrufen. System-Prompt, Tool-Definitionen und Verlauf ergeben zusammen einen großen Prompt. Ollamas Standard-Kontextfenster hängt inzwischen vom VRAM ab: 4k bei weniger als 24 GiB, 32k ab 24 GiB bis unter 48 GiB und 256k bei 48 GiB oder mehr. Die aktuelle Empfehlung lautet, für Agenten und Coding-Tools mindestens 64,000 Tokens zu verwenden. Setzen Sie num_ctx so, dass diese Arbeitslast in den vom Modell unterstützten Kontext und den verfügbaren Speicher passt. Wählen Sie außerdem ein Modell, das Funktionsaufrufe tatsächlich gut unterstützt. Eine Antwort, die mitten im Satz endet, weist auf das gegenteilige Problem und eine andere Einstellung hin: num_predict. Wenn Antworten abgeschnitten zurückkommen, sollten Sie prüfen, wo num_predict gesetzt ist und was done_reason angibt, bevor Sie den Agenten dafür verantwortlich machen. Wenn Sie lieber mit einem bestimmten Kandidaten als mit einer Auswahlliste beginnen möchten, ist Nemotron 3.5 Lightning einen Versuch wert. Der zugehörige Artikel nennt den exakten Tag zum Abrufen, den benötigten RAM und ob die Leistung im CPU-only-Betrieb ausreicht.
Ein selbst gehostetes Gateway. Schalten Sie ein selbst gehostetes LiteLLM-Gateway zwischen Octop und alle anderen Komponenten. Dadurch erhalten Sie eine gemeinsame Basis-URL, einen separaten Schlüssel pro Benutzer, Ausgabenlimits und ein zentrales Log. Sie können das dahinter verwendete Modell außerdem austauschen, ohne etwas in Octop zu ändern.
Eine kostenpflichtige API. Sie bietet die beste Qualität, aber mit einem klaren Nachteil: Der Gesprächsinhalt verlässt Ihren Server und wird an den Provider übertragen. Das widerspricht einem wesentlichen Grund für Self-Hosting. Der Schlüssel wird in docker/.env als OPENAI_API_KEY hinterlegt. Die Compose-Datei reicht ihn bereits weiter.
Unabhängig von Ihrer Wahl enthält die Compose-Datei außerdem OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY und LANGFUSE_BASE_URL. Damit können Sie Traces an Ihre eigene Langfuse-Instanz senden und sehen, was die Agenten tatsächlich tun, statt aus dem Chatfenster zu raten.
Benutzer, Rollen und die gemeinsame Agentenbibliothek
Das Administratorkonto aus dem ersten Bootvorgang erstellt und verwaltet die anderen Konten. Jeder Benutzer erhält eigene Agenten, einen eigenen Arbeitsbereich und eigene Zugangsdaten. Diese Trennung wird durch das Token gewährleistet, das der Browser speichert. Zusätzlich stehen gebündelte Expertenschablonen und Skill-Pakete auf Instanzebene zur Verfügung. Das Teilen eigener Agenten mit anderen Benutzern wurde in v0.9.24 eingeführt, also nach der hier festgelegten Version.
Gehen Sie mit den Werkzeugen vorsichtig um. Octop bietet eine Genehmigung für Werkzeuge und Schutzmechanismen für Shell-Befehle. Beides ist tatsächlich vorhanden. Ein Agent, der Shell-Befehle ausführt, führt sie jedoch innerhalb des Octop-Containers aus, in den Ihr Datenvolume eingebunden ist. Die Schutzmechanismen begrenzen, was ein unachtsamer Prompt bewirken kann. Sie bilden keine Sandbox-Grenze. Lassen Sie die Werkzeuggenehmigung daher für alle Benutzer aktiviert, denen Sie keinen direkten Zugriff auf eine Shell geben würden. Wenn Sie diese Lösung mit anderen Optionen vergleichen, zeigt der Vergleich selbst gehosteter KI-Agenten, wie die einzelnen Lösungen damit umgehen.
Ein Projekt aktualisieren, das so schnell Releases veröffentlicht
Die Daten hinter diesem Diagramm
[
{
"version": "v0.9.16",
"days_since_previous_release": 2
},
{
"version": "v0.9.17",
"days_since_previous_release": 3
},
{
"version": "v0.9.18",
"days_since_previous_release": 1
},
{
"version": "v0.9.19",
"days_since_previous_release": 3
}
]Das sind die Tag-Daten aus dem Repository, erfasst am 7. August 2026. In neun Tagen wurden 4 getaggte Releases veröffentlicht. Der kürzeste Abstand betrug 1 Tag. v0.9.19 wurde 3 Tage nach dem vorherigen Tag veröffentlicht. Diese Kadenz spricht für das Projekt, ist aber ein schlechter Grund, latest auszuführen. Lesen Sie die Änderungen, bevor Sie sie übernehmen:
cd Octop
git fetch --tags
git tag --sort=-creatordate | head
NEW_TAG=$(git tag --sort=-creatordate | head -1)
git log --oneline "v0.9.19..$NEW_TAG"Prüfen Sie zuerst, was $NEW_TAG tatsächlich enthält, bevor Sie es auschecken. Das Projekt versieht auch Betas wie v1.0.2b9 mit Tags und veröffentlicht sie neben stabilen Releases. Am 20. November 2026 ist v1.0.3b7 der neueste Tag. Er wurde am 18. November 2026 veröffentlicht. Das neueste stabile Release bleibt v1.0.2, veröffentlicht am 18. Oktober 2026. Der Sprung von v0.9.19 umfasst das Release v1.0.0 vom 14. September 2026. Das Änderungsprotokoll ist daher lang und sollte sorgfältig gelesen werden.
Erstellen Sie jedes Mal zuerst ein Backup. Datenbankmigrationen werden beim Start ausgeführt. Eine fehlgeschlagene Migration bei einem Projekt, das so schnell Releases veröffentlicht, müssen Sie selbst beheben:
docker compose -f docker/docker-compose.yml stop
sudo tar czf octop-backup-$(date +%F).tgz -C /srv octop-data
docker compose -f docker/docker-compose.yml startChecken Sie anschließend den neuen Tag aus und erstellen Sie den Build mit docker compose -f docker/docker-compose.yml up -d --build. Wenn dabei ein Fehler auftritt, können Sie den alten Tag auschecken und den Build erneut erstellen. Dadurch wird der Code wiederhergestellt. Die Datenbank wird jedoch nur durch das Tarball-Backup wiederhergestellt.
Das Tarball enthält octop.db, config.json, das JWT-Signaturgeheimnis und credential.txt. Es ist daher genauso vertraulich wie der Server selbst. Setzen Sie den Modus auf 600 und bewahren Sie eine Kopie außerhalb des Servers auf. Für größere Installationen veröffentlicht das Projekt außerdem docker/docker-compose.postgres.yml. Damit wird PostgreSQL mit pgvector anstelle von SQLite ausgeführt.
Fehlerfälle und die dabei angezeigten Meldungen
Der Health Check antwortet nie. curl http://127.0.0.1:8088/api/health hängt oder verweigert die Verbindung. Lesen Sie docker compose -f docker/docker-compose.yml logs -f octop. Wenn ein Container während der ersten Initialisierung beendet wird, kann er normalerweise nicht in das Datenverzeichnis schreiben. Prüfen Sie daher den Eigentümer des Verzeichnisses, das Sie für OCTOP_DATA festgelegt haben.
Das Dashboard wird geladen, aber der Chat kann keine Verbindung herstellen. Ein fehlgeschlagener WebSocket-Handshake beendet in v0.9.19 den Streaming-Status. Öffnen Sie die Browserkonsole und suchen Sie nach einer fehlgeschlagenen Verbindung zu wss://octop.example.com/api/agents/.../chat/ws. Prüfen Sie, ob der Proxy das Upgrade weiterleitet. Fügen Sie die Header proxy_http_version 1.1 sowie Upgrade und Connection hinzu.
Die gesamte Antwort wird mehrere Sekunden verspätet auf einmal angezeigt. Das Streaming funktioniert, aber das Puffern ist aktiviert. Setzen Sie proxy_buffering off.
bind: address already in use. 8088 wird bereits von einem anderen Prozess verwendet. sudo ss -tlnp | grep 8088 zeigt, welcher Prozess den Port belegt. Das erhalten Sie auch, wenn Sie in einer Override-Datei einen zweiten Eintrag für ports hinzugefügt haben, anstatt den ursprünglichen Eintrag zu bearbeiten.
Das korrekte Passwort wird abgelehnt. Fünf fehlerhafte Versuche lösen eine Sperre von 900 Sekunden aus. Warten Sie die Sperrzeit ab, statt die Installation neu durchzuführen.
Das neue Passwort in .env hatte keine Wirkung. Diese Zugangsdaten werden nur bei der ersten Initialisierung verwendet. Ändern Sie das Passwort im Dashboard.
Der Agent antwortet, führt aber kein Tool aus. Prüfen Sie die Kontextzuweisung des lokalen Modells und dessen Unterstützung für Function Calling. Ollama empfiehlt inzwischen mindestens 64,000 Tokens für Agent-Workloads. Wählen Sie ein Modell und ein Speicherbudget, die dies unterstützen.
FAQ
Ist Octop ein Ersatz für Open WebUI?
Nur wenn Sie die zusätzlichen Funktionen benötigen. Open WebUI unterstützt ebenfalls mehrere Benutzer, Rollen und Zugriffskontrollen. Octop kombiniert Benutzerkonten mit einer Administratorrolle, benutzerspezifischen Arbeitsbereichen und Zugangsdaten sowie einer umschaltbaren Bibliothek spezialisierter Agents. Dadurch können mehrere Personen einen Server gemeinsam nutzen, ohne eine gemeinsame Historie zu verwenden. Wenn ein einzelnes Konto für Sie ausreicht, ist Open WebUI die einfachere und deutlich ausgereiftere Wahl.
Warum sollte ich das Octop-curl-Installationsskript nicht verwenden?
Der Einzeiler für v0.9.19 lädt ein Skript aus einem Tencent-Cloud-Object-Storage-Bucket, ohne seinen Inhalt an einen Git-Tag oder Commit zu binden. Das Repository enthält unter scripts/install.sh zwar eine versionierte Kopie, aber das Weiterleiten der Remote-Kopie an bash führt sie aus, bevor Sie sie gelesen haben. Außerdem wird die Anwendung mit einer eigenen Python-3.12-Umgebung außerhalb Ihres Paketmanagers auf dem Host installiert. Laden Sie das Skript herunter und lesen Sie es zuerst, oder stellen Sie die Anwendung mit Docker Compose aus einem ausgecheckten Tag bereit.
Kann Octop statt einer kostenpflichtigen API ein lokales Modell verwenden?
Ja. Octop unterstützt OpenAI-kompatible APIs und wird mit einem Ollama-Preset ausgeliefert. Wenn Sie http://host.docker.internal:11434/v1 angeben, funktioniert das, sobald Sie extra_hosts: ["host.docker.internal:host-gateway"] in den Container übernehmen und OLLAMA_HOST=0.0.0.0:11434 auf dem Host setzen. Begrenzen Sie Port 11434 auf den Adressbereich von Docker, da Ollamas lokale API keine Authentifizierung erfordert. Prüfen Sie das zugewiesene Kontextfenster. Ollamas Standardwerte unterscheiden sich inzwischen abhängig vom VRAM. Die aktuelle Empfehlung sieht für Agent-Aufgaben mindestens 64,000 Tokens vor, innerhalb des vom Modell unterstützten Kontexts und des verfügbaren Speichers.
Benötige ich einen Reverse Proxy, oder kann ich Port 8088 öffnen?
Sie benötigen den Proxy. Die mit Octop ausgelieferte Compose-Datei veröffentlicht Port 8088 auf allen Schnittstellen ohne TLS. Dadurch würden Passwörter und Bearer-Tokens unverschlüsselt über das Internet übertragen. Ändern Sie den veröffentlichten Port in 127.0.0.1:8088:8088 und schalten Sie Caddy oder nginx mit einem Zertifikat davor. Bei nginx müssen Sie die Header für das WebSocket-Upgrade weiterleiten und proxy_buffering off setzen. Ein fehlgeschlagenes Upgrade verhindert die Verbindung des Chats. Eine Pufferung verzögert den HITL-Resume-Stream. In v0.9.19 beendet ein fehlgeschlagener Handshake den Streaming-Zustand. Eine Trennung der Verbindung bricht eine aktive Agent-Aufgabe nicht ab.
Ist Octop für den Produktivbetrieb bereit?
Im August 2026 war Octop noch vor Version 1.0 und veröffentlichte mehrere getaggte Releases pro Woche. Am 14 September 2026 wurde v1.0.0 getaggt. Danach wurden mehrere 1.0.2-Beta-Tags veröffentlicht, bevor am 18 October 2026 v1.0.2 als stabiles Release erschien. Am 20 November 2026 ist v1.0.3b7 der neueste Tag. Er wurde am 18 November 2026 veröffentlicht. v1.0.2 bleibt das neueste stabile Release. Die Entwicklung ist weiterhin schnell. Betrachten Sie Octop daher als vielversprechend, aber noch nicht als ausgereift. Für eine Familie oder ein kleines internes Team ist der Einsatz vertretbar, wenn Sie einen exakten Tag festlegen, vor jedem Upgrade das Commit-Log lesen und vor jedem Neuaufbau ein Backup des Daten-Volumes erstellen. Betreiben Sie die Anwendung nicht auf latest. Speichern Sie dort vorerst keine Kundendaten.