SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

OneCLI selbst hosten: Ein Agent pro Person

OneCLI gibt jeder Person eine isolierte Agenten-Sandbox und verwaltet API-Schlüssel in einem Gateway. Setup mit Docker Compose und PostgreSQL, ab 2 GiB RAM pro Agent.

Was Sie beim Self-Hosting von OneCLI erhalten

Wenn Sie OneCLI selbst hosten, erhält jede Person in Ihrem Team einen eigenen Agenten. Jeder Agent läuft in seiner eigenen Sandbox. Die API-Schlüssel werden in einem Gateway verwaltet, auf das die Agenten nie zugreifen. Die Installation besteht aus einem Docker-Compose-Stack mit PostgreSQL im Hintergrund. Er ist unter http://localhost:10254 erreichbar. Planen Sie dafür einen dedizierten Server ein. Laut dokumentiertem Standard ist das Speicherlimit pro Agenten-Sandbox auf 2 GiB gesetzt. Planen Sie den Speicherbedarf des Basis-Stacks und den tatsächlichen Arbeitsspeicherbedarf der Agenten daher getrennt.

Dieser Stack enthält acht Komponenten. Wenn Sie deren Aufgaben kennen, lässt sich der restliche Leitfaden leichter lesen.

  • Web-Dashboard (Next.js), Port 10254. Hier verwalten Sie Agenten, Chats, den Speicher und die Skills sowie Verbindungen und Secrets.
  • API-Server, Port 10256. Die zentrale Steuerungsebene für Datenbank, Gesprächsverarbeitung und Arbeitswarteschlangen.
  • Rust-Gateway, Port 10255. Es fängt ausgehende Anfragen der Agenten ab und fügt die Zugangsdaten ein.
  • Runner. In der README wird er als Komponente beschrieben, die „Agenten-Sandboxes startet, parkt und beendet. Nur ausgehend, ohne Zugriff auf die Datenbank.“
  • Sandbox Supervisor. In der README wird er als Komponente beschrieben, die „innerhalb jeder Sandbox läuft und über eine herstellerneutrale Harness-Schnittstelle kommuniziert, sodass die Agentenlaufzeit austauschbar ist.“
  • SSH-Terminator, Port 10257. Die README bezeichnet ihn als „SSH-Eingang“. Er beendet SSH-Verbindungen mit kurzlebigen Zertifikaten, die die API ausstellt, und verbindet jede Sitzung mit der Sandbox eines Agenten. Er läuft unter demselben runner-Profil wie der Runner.
  • Channel-Adapter. Ein Daemon, der eine Slack-App verbindet, damit ein Agent unter seinem eigenen Namen in Channels und Direktnachrichten antwortet.
  • PostgreSQL. Die mitgelieferte Compose-Datei führt postgres:18-alpine mit einem pgdata-Volume aus.

Der Name klingt nach CLI, das Produkt ist ein Server

OneCLI ist eine Serverplattform. Der Name vermittelt das Bild eines Kommandozeilenprogramms, das Sie auf einem Laptop installieren. Für das Produkt in dieser Anleitung ist dieses Bild falsch. Einen separaten Kommandozeilenclient gibt es im Repository onecli/onecli-cli. Er leitet den Netzwerkverkehr eines lokalen Coding-Agenten über ein Gateway. Was Sie hier bereitstellen, ist eine Webanwendung für mehrere Benutzer: ein Kontosystem mit Organisationen und Einladungen, eine Datenbank für Konversationen und Secrets sowie ein Runner, der Container startet.

Das Modell pro Person bildet die Grundlage des gesamten Designs. In der README heißt es: „Sie erstellen pro Person einen Agenten, geben jedem Agenten die erforderlichen Zugriffsrechte und führen ihn in einer Sandbox aus. Der Netzwerkverkehr läuft über ein Gateway, das die Zugangsdaten einfügt und Ihre Richtlinien durchsetzt.“ Jeder Agent verfügt über ein eigenes Dateisystem und eine eigene Shell, eine eigene Konversationsseite, vom System verwalteten Speicher sowie Skills, die Sie nur einmal schreiben. Zugangsdaten werden entgegengesetzt zur üblichen Vorgehensweise verwaltet. Statt einen API-Key in die Umgebung jeder Person zu kopieren, speichern Sie den Key einmalig und geben ihn nur für die Agenten frei, die ihn verwenden dürfen.

Was das System vor dem Start benötigt

  • Docker mit dem Compose-Plugin in Version 2.24.0 oder neuer. Die mitgelieferte Compose-Datei verwendet optionale env_file-Zuordnungen mit required: false, die Docker ab 2.24.0 unterstützt. Die Migrationskommentare erklären die angegebene Mindestversion 2.19 mit der Unterstützung für One-Shot-Abhängigkeiten unter up --wait. Das deckt jedoch nicht die optionalen Umgebungsdateien der Datei ab.
  • Arbeitsspeicher als eigentliche Einschränkung. Lesen Sie den folgenden Abschnitt zur Dimensionierung, bevor Sie einen Tarif auswählen.
  • Freie Loopback-Ports 10254, 10255, 10256, 10257 und 5432. Port 10257 ist der SSH-Einstiegspunkt. Er wird mit dem runner-Profil gestartet, das diese Anleitung aktiviert.

PostgreSQL müssen Sie nicht selbst installieren: Die Compose-Datei führt es als Dienst aus. Der folgende Einrichtungsassistent benötigt Node.js und pnpm auf dem Host. Für die Arbeit am Code wird außerdem mise verwendet, um die Toolchain einschließlich Rust für das Gateway festzulegen.

Wie viele Agent-Sandboxen passen auf Ihren VPS?

Die Dokumentation des Runners nennt konkrete Werte statt vager Angaben. Jede Sandbox ist auf 2048 MB Arbeitsspeicher (RUNNER_SANDBOX_MEMORY_MB), eine CPU (RUNNER_SANDBOX_CPUS) und 512 Prozesse (RUNNER_SANDBOX_PIDS) begrenzt. Das Parallelitätslimit beträgt 4 (RUNNER_MAX_SANDBOXES). Die Dokumentation empfiehlt zusätzlich zum Basis-Stack etwa 10 GiB freien Arbeitsspeicher, um dieses Limit abzudecken.

DiagrammAgent memory budgets per box, using the documented 2 GiB cap
Die Daten hinter diesem Diagramm
[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Diese Anzahl von Slots ist eine Berechnung und kein Benchmark: Der Gesamtspeicher wird um angenommene etwa 2 GB für PostgreSQL und andere dauerhaft laufende Dienste reduziert. Das Ergebnis wird durch das Limit von 2 GiB pro Sandbox geteilt. Auf dieser Grundlage sieht das Budget 2 GB box für 0 Sandboxen mit ihrem maximalen Speicherlimit vor. Der Wert 0 bedeutet unter diesen Annahmen, dass kein Budget für Sandboxen mit maximalem Speicherlimit vorhanden ist. Er bedeutet nicht, dass Docker den Start eines Agenten verweigert. 16 GB box lässt Platz für 7. Das liegt deutlich über dem Standardlimit von vier und über den etwa 10 GiB freiem Arbeitsspeicher, die die Runner-Dokumentation verlangt. Mit 32 GB box kommen Sie auf 15. Wenn Sie mehr als vier Sandboxen gleichzeitig ausführen, müssen Sie außerdem RUNNER_MAX_SANDBOXES erhöhen.

Zwei Faktoren verändern diese Berechnung. Eine Sandbox mit einem laufenden Hintergrundprozess wird nicht angehalten. Sie belegt ihren Slot daher dauerhaft. Für die Dimensionierung von RUNNER_MAX_SANDBOXES ist deshalb die dauerhafte Last maßgeblich, nicht die ausgelastetste Minute. Die Plattform setzt hierfür jedoch eine Obergrenze: Standardmäßig hält jeder Runner höchstens RUNNER_MAX_SANDBOXES minus eine Sandbox dauerhaft aktiv, jedoch nie weniger als eine. Über MAX_HELD_AWAKE_SANDBOXES in der API lässt sich dieser Wert überschreiben. Wird die Obergrenze überschritten, entfernt der Runner die Sandbox, die am längsten ungenutzt war, und meldet ihren überwachten Prozess als verloren. Die Nutzung von Arbeitsspeicher und CPU hängt von der jeweiligen Aufgabe ab. Jede Sandbox ist auf eine CPU begrenzt. Vier ausgelastete Agenten können daher vier Kerne verwenden. Die Einstellung von 2 GiB für den Arbeitsspeicher ist jedoch ein Limit und keine Reservierung: Vier inaktive, aber aktive Agenten verbrauchen nicht automatisch 8 GiB.

Runner-Einstellungen, die Sie möglicherweise ändern möchten
  • RUNNER_MAX_SANDBOXES (Standard 4): wie viele Sandboxen gleichzeitig ausgeführt werden.
  • RUNNER_SANDBOX_MEMORY_MB (Standard 2048): Speicherlimit pro Sandbox.
  • RUNNER_SANDBOX_CPUS (Standard 1): CPU-Limit pro Sandbox.
  • RUNNER_SANDBOX_PIDS (Standard 512): Prozesslimit pro Sandbox.
  • RUNNER_NETWORK_INTERNAL (Standard true): hält das Sandbox-Netzwerk ohne Route nach außen. Lassen Sie diese Einstellung aktiviert.
  • RUNNER_SANDBOX_NETWORK (Standard onecli-sandboxes): das Netzwerk, dem Sandboxen beitreten.
  • RUNNER_RECONCILE_SECONDS (Standard 60): wie häufig der Runner den Status abgleicht.
  • RUNNER_ORPHAN_GRACE_SECONDS (Standard 3600): Alter, ab dem verwaiste Container und Volumes gelöscht werden.
  • RUNNER_AGENT_IMAGE: überschreibt das Sandbox-Image, das ansonsten ONECLI_VERSION folgt.

OneCLI mit Docker Compose installieren

Die Rohsequenz aus dem Upstream-Dokument für das Self-Hosting schreibt drei Secrets in docker/.env neben der Compose-Datei. Diese Sequenz berücksichtigt weder das Runner-Token noch die Docker-Socket-Gruppe und die SSH-Anmeldedaten, die die aktivierten Dienste benötigen. Führen Sie daher vor dem Start des Stacks den Setup-Assistenten aus.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

Lesen Sie diesen Block, bevor Sie ihn ausführen. Der Heredoc-Marker ist nicht in Anführungszeichen gesetzt. Ihre Shell führt daher jedes head -c 32 /dev/urandom | base64 aus und schreibt das Ergebnis anstelle des wörtlichen Texts. SECRET_ENCRYPTION_KEY ist der AES-256-GCM-Schlüssel für jedes Secret in der Datenbank. GATEWAY_INTERNAL_SECRET authentifiziert das Gateway gegenüber der API. BETTER_AUTH_SECRET signiert Session-Cookies. COMPOSE_PROFILES=runner ist die wichtigste Zeile. Der Runner-Dienst befindet sich hinter einem Compose-Profil. Wenn Sie diese Zeile weglassen, startet der Stack scheinbar fehlerfrei, aber es wird keine Agent-Sandbox gestartet.

--wait wartet, bis die Dienste ausgeführt werden oder den Status healthy haben und die Abhängigkeit für die Migration erfolgreich abgeschlossen ist. Ein Exit-Code ungleich 0 ist daher Ihr erstes Signal für ein Problem. Prüfen Sie anschließend, welche Dienste tatsächlich gestartet wurden.

docker compose ps
docker compose logs migrations

Fixieren Sie die Version. ONECLI_VERSION setzt das Tag für alle Dienste gleichzeitig. Das Image der Agent-Sandbox verwendet diese Version ebenfalls, sofern RUNNER_AGENT_IMAGE nicht auf ein anderes Image verweist. Verwenden Sie ausschließlich die Versionsnummer. Die veröffentlichten Image-Tags enthalten kein Präfix v. Am 1. November 2026 ist v2.17.0 die aktuelle Version, die am 31. Oktober 2026 veröffentlicht wurde. Fügen Sie die Version in dieselbe Datei ein. Verwenden Sie anschließend den dokumentierten Upgrade-Pfad, damit bereits laufende Sandboxes ebenfalls auf dieses Image wechseln.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

Es gibt auch ein Installationsprogramm: curl -fsSL https://onecli.sh/install | sh. Es schreibt seine Konfiguration nach ~/.onecli/.env und führt dieselben Schritte aus. Für den eigenen Lauf setzt es ONECLI_VERSION=latest. Dadurch wird eine Version überschrieben, die ausschließlich in .env festgelegt ist. Beim Compose-Weg können Sie jede Datei prüfen, bevor etwas ausgeführt wird. Verwenden Sie diesen Weg auf einem System, auf dem bereits andere Compose-Stacks laufen. Das Setup aus dem Checkout aktualisieren Sie mit pnpm run setup --upgrade. Dafür müssen Node.js und pnpm auf dem Host installiert sein. Wenn Sie direkt am Code arbeiten, benötigen Sie außerdem mise und Rust für das Gateway. Dieser Weg eignet sich daher für Personen, die OneCLI ändern möchten. Für Kubernetes wurde mit Release v2.11.0 (8. Oktober 2026) ein Helm-Chart hinzugefügt. Das aktuelle Chart führt Agent-Sandboxes als Jobs mit persistenten Volumes und ohne Docker-Daemon aus. Es dokumentiert außerdem die erforderlichen Secrets sowie die Konfiguration für Datenbank und Routing.

Das Dashboard von Ihrem Laptop aus erreichen

Jeder veröffentlichte Port in der mitgelieferten Compose-Datei wird an ${ONECLI_BIND_HOST:-127.0.0.1} gebunden. Auf einem VPS bedeutet das, dass das Dashboard läuft und von außerhalb des Servers niemand darauf zugreifen kann. Diese Voreinstellung ist korrekt. Behalten Sie sie bei und verwenden Sie einen Tunnel:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Öffnen Sie nun http://localhost:10254 auf Ihrem Laptop. Der Datenverkehr läuft über die SSH-Verbindung. Dadurch ist das Dashboard nicht unverschlüsselt im öffentlichen Internet erreichbar, und Sie müssen keinen zusätzlichen Port in der Firewall freigeben.

Mit ONECLI_BIND_HOST=0.0.0.0 wird das Dashboard über unverschlüsseltes HTTP veröffentlicht. Gleichzeitig wird PostgreSQL veröffentlicht, und zwar mit dem in der Compose-Datei voreingestellten Passwort onecli, sofern Sie POSTGRES_PASSWORD nicht setzen. Außerdem wird der SSH-Zugang auf Port 10257 veröffentlicht. Dieser Dienst bindet den Docker-Socket ein. Wenn mehrere Personen das Dashboard benötigen, setzen Sie einen Reverse Proxy mit TLS (Transport Layer Security) davor und lassen Sie den Bind-Host unverändert. Setzen Sie ONECLI_EXTERNAL_URL auf die HTTPS-URL des Dashboards und verwenden Sie die Reverse-Proxy-Konfiguration des Upstream-Projekts. Sie leitet die Pfade für Dashboard, API und Gateway an die jeweiligen Dienste weiter. Ein Proxy allein hält keine fremden Personen fern. In der Self-Hosting-Dokumentation steht, dass die Registrierung absichtlich offen ist und nicht deaktiviert werden kann: Jede Person, die das Dashboard erreicht, kann ein Konto erstellen. Dieses Konto erhält eine eigene Organisation. Nur der Beitritt zu Ihrer Organisation erfordert eine Einladung. Die Dokumentation empfiehlt, das Dashboard hinter Ihrer Netzwerkgrenze zu halten. Wenn dieser Proxy bereits Ihre anderen selbst gehosteten Anwendungen bereitstellt, bringt die Weiterleitung der Authentifizierung über eine selbst gehostete Single-Sign-on-Schicht das Dashboard hinter die Anmeldung, die Ihr Team bereits verwendet. Wenn Sie eine Person dort entfernen, schließen Sie damit auch diesen Zugang.

Erstellen Sie zuerst das erste Konto und weisen Sie anschließend einen Modellschlüssel zu

Öffnen Sie das Dashboard und erstellen Sie umgehend Ihr Konto. Jedes neue Konto erhält eine eigene Organisation. Teammitglieder treten Ihrer Organisation per Einladung bei. Danach bleibt die Registrierung geöffnet. Das ist ein weiterer Grund, warum das Dashboard hinter dem Tunnel oder einem authentifizierten Proxy liegen sollte. Wenn Sie von einer Version aktualisieren, die noch keine Anmeldungen unterstützt, registrieren Sie sich sofort: In der Self-Hosting-Dokumentation steht, dass die vorhandenen Daten dem ersten Konto zugewiesen werden, das sich registriert. Auf einem erreichbaren Host sollte dieses Konto daher Ihnen gehören.

Speichern Sie anschließend einen Modellschlüssel, bevor Sie einen Agenten erstellen. Ein gehosteter Agent benötigt einen zugewiesenen Modellschlüssel. Die Reihenfolge ist wichtig: Speichern Sie den Schlüssel im Dashboard, weisen Sie ihn dem Agenten zu und starten Sie erst danach eine Unterhaltung. Ohne diese Zuweisung wird die Sandbox nicht gestartet. Der Agent antwortet im Thread mit dem Hinweis, dass er einen Modellschlüssel benötigt.

Nehmen Sie die Zuweisung möglichst restriktiv vor. Jeder Agent erhält nur die von Ihnen zugewiesenen Berechtigungen. Das Gateway erzwingt diese bei jeder Anfrage. Ein Agent, der ein Repository liest, kann dadurch nicht auf den Schlüssel Ihres Zahlungsanbieters zugreifen. Über dieselbe Liste der Zuweisungen steuern Sie auch die Kosten. Ein persönlicher Agent, der jedes Modell in Ihrem Besitz aufrufen kann, verursacht eine persönliche Rechnung. Lesen Sie daher zunächst, wie Sie die Ausgaben eines Agenten für Modellaufrufe begrenzen, bevor Sie zehn solcher Agenten einrichten.

Wie das Gateway Schlüssel aus den Agents heraushält

Das Gateway ist ein in Rust geschriebener HTTPS-Proxy, der auf Port 10255 lauscht. Der HTTP-Client eines Agents wird darauf ausgerichtet. Der Agent verwendet dabei ein Platzhalter-Credential anstelle eines echten Credentials. Das Gateway gleicht die ausgehende Anfrage mit den Berechtigungen dieses Agents ab, entschlüsselt das echte Secret, ersetzt damit das Platzhalter-Credential in der Anfrage und leitet sie weiter. Die Secrets liegen mit AES-256-GCM (Advanced Encryption Standard, 256 Bit, Galois/Counter Mode) verschlüsselt in PostgreSQL und werden nur zum Zeitpunkt der Anfrage entschlüsselt. Jeder Aufruf wird mit der Identität des Agents und seinem Ziel protokolliert. Dadurch entsteht ein Audit-Trail, den Sie nicht erhalten, wenn die Schlüssel in den Shell-Profilen von zehn Personen liegen.

Zwei Aspekte bestimmen, wie Sie das System bereitstellen.

  • Die HTTPS-Überwachung erfolgt als Man-in-the-Middle. Das Gateway erzeugt eine lokale Zertifizierungsstelle. Der Agent vertraut dieser Zertifizierungsstelle. Das Gateway beendet anschließend die TLS-Verbindung des Agents und öffnet eine neue Verbindung zum Upstream-Dienst. Deshalb schlägt ein Agent, dessen HTTP-Client der Zertifizierungsstelle des Gateways nicht vertraut, mit einem Zertifikatsprüffehler und nicht mit einem Authentifizierungsfehler fehl.
  • Der Agent weist sich mit einem Proxy-Authorization-Header aus. Auf einem einzelnen Host, auf dem Agents und Gateway dasselbe interne Docker-Netzwerk verwenden, verlässt dieser Header kein Netzwerk, das Sie nicht kontrollieren. Wenn Sie einen Agent auf einem anderen Host auf das Gateway ausrichten, schützen Sie die Verbindung mit einem VPN oder einem TLS-Transport, weil dieser Header ein Bearer-Token ist. Der Upstream empfiehlt für den direkten CONNECT-Proxy-Port ein VPN.

Der ehrliche Nachteil: Das Gateway liest absichtlich jede Anfrage, die Ihre Agents senden, im Klartext. Es ist der sensibelste Prozess auf dem Rechner. Behandeln Sie den Host entsprechend. Halten Sie außerdem die Zahl der Personen mit Anmeldemöglichkeit gering und verwenden Sie Linux-Benutzer mit geringsten Berechtigungen.

Warum der Runner keinen eingehenden Port benötigt

Der Runner arbeitet ausschließlich ausgehend. In der Dokumentation heißt es: „Er stellt keine Ports bereit, die aus dem externen Netz erreichbar sind. Daher funktionieren ein Laptop, ein Homelab oder eine VPC hinter NAT ohne eingehenden Zugriff, Tunnel oder TLS-Terminierung.“ NAT steht für Network Address Translation und bezeichnet die Funktion eines Heimrouters. Der Runner baut die Verbindung zur Steuerungsebene ausgehend auf und ruft dort seine Aufgaben ab. Daher muss nichts weitergeleitet und kein Port geöffnet werden.

Dieses Design wirkt sich im Sandbox-Netzwerk aus. Die Compose-Datei definiert ein zweites Netzwerk mit dem Attribut internal: true. In Docker bedeutet das, dass keine externe Netzwerkverbindung besteht. Die Sandboxes werden diesem Netzwerk hinzugefügt. Das Gateway ist an beide Netzwerke angebunden und stellt daher den einzigen Ausgang dar. Die Dokumentation des Runners formuliert den Zweck eindeutig: „Ein internal-Netzwerk, an das das Gateway an beide Netzwerke angebunden ist, macht den ausschließlich über das Gateway möglichen ausgehenden Datenverkehr zu einer Abgrenzung und nicht nur zu einer Empfehlung.“ Ein Agent kann das Gateway nicht umgehen, indem er direkt eine Verbindung zu einer externen Adresse öffnet. Die Richtlinien des Gateways bestimmen weiterhin, welche Anfragen zulässig sind.

Überprüfen Sie dies auf Ihrem eigenen System, statt dem obigen Abschnitt zu vertrauen.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

Sie sollten "Internal": true sehen. Wenn false ausgegeben wird, ist die Kontrolle des ausgehenden Datenverkehrs deaktiviert und das Gateway stellt wieder nur eine Empfehlung dar. Verwenden Sie den Namen des Sandbox-Netzwerks, den docker network ls ausgibt, da onecli-sandboxes nur der Standardwert ist.

Wie stark ist die OneCLI-Sandbox?

Lesen Sie diesen Abschnitt langsam. Die Bezeichnung „sandboxed“ hat in der Beschreibung des Projekts großes Gewicht. Der Mechanismus selbst ist jedoch in der Runner-Dokumentation und im Backend-Code beschrieben.

Die README sagt, dass jeder Agent „seine eigene isolierte Sandbox mit einem Dateisystem und einer Shell“ erhält. Außerdem bezeichnet sie den Sandbox Supervisor als Komponente, die „innerhalb jeder Sandbox ausgeführt wird und über eine herstellerneutrale Harness-Schnittstelle kommuniziert, sodass die Agent-Laufzeit austauschbar ist“. Keiner dieser Sätze erklärt, woraus die Isolation besteht. Das beschreibt die Runner-Dokumentation: Das Standard-Backend ist Docker (RUNNER_BACKEND=docker). Eine Sandbox ist ein Docker-Container mit einer Speicherbegrenzung, einer CPU-Begrenzung und einer Prozessbegrenzung, der mit dem internen Netzwerk verbunden ist. Der Code enthält eine Schnittstelle für andere Backends. Der aktuelle Runner-Code implementiert außerdem ein Kubernetes-Backend, das das Helm-Chart für Sandbox-Jobs und persistente Volumes verwendet. Bei der Compose-Installation in diesem Leitfaden ist eine Sandbox ein Docker-Container.

Die Runner-Dokumentation beschreibt die Docker-Grenze inzwischen genauer: Der Agent läuft als node, mit no-new-privileges, wobei alle Linux-Capabilities entfernt sind und das Standard-seccomp-Profil von Docker verwendet wird. Das Backend bindet nur das dauerhafte Home-Verzeichnis des Agents in dessen Sandbox ein. Wählen Sie daher die enge Auslegung. Die Begrenzungen sind Ressourcenbegrenzungen. Das interne Netzwerk ist eine echte Kontrolle des ausgehenden Datenverkehrs. Die Isolation zwischen einem Agent und Ihrem Host beruht auf diesen Container-Kontrollen. Ein Container verwendet jedoch den Kernel des Hosts gemeinsam.

Ein zweiter Aspekt ist ebenfalls wichtig. Der Runner-Dienst bindet /var/run/docker.sock ein, weil er damit Sandboxes erstellt. Der Zugriff auf den Socket eines rootful Docker-Daemons entspricht root-Rechten auf dem Host. Wer diese API aufrufen kann, kann einen Container starten und darin das Dateisystem des Hosts einbinden. Der mitgelieferte Docker-basierte Runner verwendet diesen Socket. Deshalb ist der Runner-Prozess genauso schützenswert wie das Gateway. Der SSH-Terminierer bindet denselben Socket ein, damit er Befehle in Sandbox-Containern ausführen kann. Auch die Kommentare in der Compose-Datei bezeichnen dieses Einbinden als gleichbedeutend mit root-Rechten auf dem Host. Lassen Sie Port 10257 daher an loopback gebunden, sofern es keinen Grund gibt, ihn zu öffnen.

Behandeln Sie die Grenze durch den gemeinsam genutzten Kernel konservativ. In der Praxis bedeutet das drei Regeln.

  1. Betreiben Sie OneCLI auf einem System, das keine anderen Aufgaben erfüllt. Darauf sollten weder ein unabhängiger Produktionsdienst noch eine gemeinsam genutzte Datenbank oder Daten eines anderen Teams laufen.
  2. Gehen Sie davon aus, dass ein Agent mit beliebiger Codeausführung innerhalb seiner Sandbox den Host erreichen könnte. Sorgen Sie mit Backups außerhalb dieses Systems dafür, dass ein solcher Vorfall beherrschbar bleibt.
  3. Lesen Sie apps/runner/src oder fragen Sie beim Upstream-Projekt nach, bevor Sie einem Kollegen sagen, dass der Agent eingeschlossen ist.

Einen Eindruck davon, wie eine dokumentierte Grenze aussieht, und welche Fragen Sie beim Upstream-Projekt stellen sollten, erhalten Sie im Vergleich mit wie eine echte Agent-Sandbox-Grenze aussieht. Entscheidend ist, ob der dokumentierte Mechanismus die Bedrohungen abdeckt, die er abwehren soll.

Die Lizenzaufteilung und warum Sie vor dem Build prüfen sollten

Der Kern von OneCLI steht unter Apache-2.0. Das Self-Hosting in der Produktion ist zulässig. Verzeichnisse mit dem Namen ee/ unterliegen einer separaten OneCLI Enterprise License. Sie sind für Entwicklung, Tests und Evaluierung kostenlos. Für den Produktionseinsatz ist ein Abonnement erforderlich. In den Release Notes zu v2.0.1 vom 18 August 2026 wird erwähnt, dass eine von GitHub erkennbare Apache-2.0-Lizenzdatei wiederhergestellt wurde. Daher hat sich das Badge auf der Repository-Seite kürzlich geändert. Prüfen Sie das Tag, das Sie tatsächlich bereitstellen, statt einer Zusammenfassung, die an einem anderen Datum erstellt wurde.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Alles unter diesen Pfaden gehört zum kommerziellen Teil. Wenn eine Funktion, von der Sie abhängig sein möchten, dort liegt, klären Sie die Kosten, bevor Sie einen Prozess darauf aufbauen.

Upgrades, Migrationen und die eine Datei, die Sie nicht verlieren dürfen

Upgrades müssen die Service-Images und das separate Agent-Image aktualisieren und anschließend laufende Sandboxes neu starten. Bei jedem up wird vor der API ein einmaliger Migrationsdienst ausgeführt. Wenn eine Migration fehlschlägt, startet der Stack nicht, statt mit einem teilweise migrierten Schema Anfragen zu bedienen. Dieses Verhalten ist erwünscht, weil ein fehlgeschlagenes Upgrade dann wie ein Ausfall sichtbar wird und nicht wie eine unbemerkte Beschädigung. docker compose logs migrations erklärt den Grund.

Ein Schritt wird leicht übersehen. Die Self-Hosting-Dokumentation warnt davor, ein Upgrade mit einem einfachen docker compose pull && docker compose up -d durchzuführen, weil das Sandbox-Image des Agents kein Compose-Service ist. Es ist der Wert RUNNER_AGENT_IMAGE auf dem Runner. Daher erkennt docker compose pull die Änderung nicht, und gehostete Agents können unbemerkt ein altes Sandbox-Image verwenden. Aktualisieren Sie den Checkout, ändern Sie den Pin und führen Sie das dokumentierte Upgrade-Tool aus. Es lädt das Sandbox-Image herunter und startet laufende Sandboxes neu.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

Ersetzen Sie 2.17.0 durch das Release, auf das Sie aktualisieren. Neustarts von Sandboxes unterbrechen laufende Arbeiten. Der dauerhafte Arbeitsbereich jedes Agents bleibt erhalten.

Wenn Sie stattdessen mit dem Installationsskript installiert haben, führen Sie dieses Skript erneut aus, anstatt das Image manuell herunterzuladen. Dadurch bleibt die Compose-Datei mit den referenzierten Images synchron. Exportieren Sie zuerst ONECLI_VERSION, wenn Sie ein bestimmtes Release verwenden möchten, da das Skript einen Pin überschreibt, der nur in seiner .env-Datei gespeichert ist.

Erstellen Sie Sicherungen der Datenbank, der Konfiguration und der Volume-Daten der Agent-Arbeitsbereiche. PostgreSQL enthält die Agents, Konversationen, den Speicher und die verschlüsselten Secrets. Die Datei docker/.env enthält SECRET_ENCRYPTION_KEY. Ohne diesen Schlüssel können die verschlüsselten Secrets nicht gelesen werden, selbst wenn der übrige Datenbankinhalt wiederhergestellt wird. Der /workspace jedes Agents befindet sich auf einem separaten dauerhaften Volume und benötigt eine eigene Sicherung.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Bewahren Sie diese Kopien und die Sicherungen der Arbeitsbereiche außerhalb des Servers auf. Das Vorgehen entspricht dem für jeden zustandsbehafteten Compose-Stack. Wenn Sie bereits einen Docker Compose-Stack regelmäßig sichern und aktualisieren, nehmen Sie die Datenbank-, Konfigurations- und Workspace-Volumes in diesen Ablauf auf und müssen sich nicht weiter darum kümmern.

Wenn es nicht funktioniert

  • Der Stack wird nie gesund, und docker compose up -d --wait wird mit einem Fehlercode beendet. Lesen Sie zuerst docker compose logs migrations, weil die API bewusst auf diesen Dienst wartet.
  • Ein Agent bleibt untätig, und keine Sandbox wird erstellt. Prüfen Sie, ob COMPOSE_PROFILES=runner in docker/.env enthalten ist und ob docker compose ps einen Runner auflistet. Prüfen Sie anschließend, ob dem Agent ein freigegebener Modellschlüssel zugewiesen ist, da Sandboxes ohne einen solchen Schlüssel nicht gestartet werden.
  • Keine Slots verfügbar. RUNNER_MAX_SANDBOXES ist standardmäßig auf 4 gesetzt. Eine Sandbox mit laufendem Hintergrundprozess belegt ihren Slot, bis die maximale Haltezeit sie beendet. docker ps zeigt, welche Prozesse tatsächlich aktiv sind.
  • Der Stack lässt sich nicht starten, und Docker meldet, dass ein Port bereits verwendet wird. Wenn das Profil runner aktiviert ist, benötigt der SSH-Einstiegspunkt zusätzlich zu den vier anderen Ports auch 10257.
  • Container verschwinden, oder der Host reagiert sehr langsam. Prüfen Sie mit dmesg -T | grep -i oom, ob der Arbeitsspeicher erschöpft ist. Das standardmäßige Speicherlimit erlaubt einer einzelnen Sandbox eine Nutzung von bis zu 2048 MB.
  • Die HTTPS-Aufrufe eines Agents schlagen mit Fehlern bei der Zertifikatsprüfung statt mit Authentifizierungsfehlern fehl. Sein HTTP-Client vertraut der Zertifizierungsstelle des Gateways nicht.
  • Nach dem Löschen eines Agents bleiben alte Container oder Volumes bestehen. Der Runner führt alle 60 Sekunden einen Abgleich durch und löscht verwaiste Ressourcen, die älter als RUNNER_ORPHAN_GRACE_SECONDS sind. Der Standardwert ist 3600. Warten Sie daher eine Stunde, bevor Sie von einem Fehler ausgehen.

Ist das die richtige Lösung für Sie?

Der Eignungstest ist kurz. OneCLI lohnt sich, wenn mehrere Personen jeweils einen Agent benötigen und Sie die Zugangsdaten zentral verwalten möchten: ein Speicher für die Rotation, ein Audit-Log zur Auswertung und ein Dashboard, über das der Entzug des Zugriffs einer Person tatsächlich wirksam wird. Das ist ein echtes Betriebsproblem. Einen API-Schlüssel auf sechs Laptops zu kopieren, ist dafür keine bessere Lösung.

Für eine einzelne Person ist das ein großer technischer Aufwand ohne entsprechenden Nutzen. Sie würden PostgreSQL, eine Control Plane, ein Gateway und einen Runner betreiben, um einen einzelnen Agent bereitzustellen. Das Berechtigungsproblem, das das Gateway löst, ist kaum relevant, wenn nur Sie selbst den Schlüssel besitzen. Betreiben Sie stattdessen einen einzelnen Harness auf einer kleineren Maschine: ein einzelner Agent-Harness auf einem VPS erfüllt diese Aufgabe mit einem Bruchteil des Arbeitsspeichers. Wenn Sie noch keine Richtung festgelegt haben, ist der Überblick Self-Hosted-AI-Agenten im Vergleich der kostengünstigere erste Schritt. Wenn Ihnen nicht die Server, auf denen Agenten laufen, sondern die Agenten selbst noch nicht vertraut sind, arbeiten Sie zuerst den stufenweisen Lernpfad zur Funktionsweise von Agenten durch. Denn erst wenn Sie wissen, was ein Tool-Aufruf und ein Memory Store tatsächlich tun, können Sie festlegen, welche Berechtigungen der Agent jeder Person erhalten sollte.

FAQ

Welche Mindestanforderungen muss der Server für das Self-Hosting von OneCLI erfüllen?

Er benötigt Docker mit dem Compose-Plugin in Version 2.24.0 oder neuer, Node.js und pnpm für den hier verwendeten Einrichtungsassistenten sowie ausreichend Arbeitsspeicher. PostgreSQL ist in der Compose-Datei enthalten und muss daher nicht separat installiert werden. Der Arbeitsspeicher bestimmt die Planung: Der Runner begrenzt jede Agent-Sandbox standardmäßig auf 2048 MB. In der Dokumentation werden zusätzlich zum Basis-Stack etwa 10 GiB freier Arbeitsspeicher empfohlen, um die standardmäßige Obergrenze von vier Sandboxes zu bedienen. Unter dem in der Grafik angenommenen Budget von 2 GB für den Basis-Stack reicht ein System mit 4 GB für eine Sandbox mit ihrer maximalen Größe. Ein System mit 16 GB deckt die standardmäßige Parallelitätsgrenze ab. Diese Werte dienen der Planung. Sie sind weder gemessene Mindestanforderungen noch feste Speicherzuweisungen.

Benötigt OneCLI PostgreSQL, oder kann es SQLite verwenden?

OneCLI benötigt PostgreSQL. DATABASE_URL ist als PostgreSQL-Verbindungszeichenfolge dokumentiert. Die mitgelieferte Compose-Datei startet postgres:18-alpine mit einem pgdata-Volume. Ein separater Migrationsdienst wendet das Schema an, bevor die API startet. Eine SQLite-Option ist nicht dokumentiert. Wenn Sie einen externen PostgreSQL-Server verwenden, konfigurieren Sie sowohl den API- als auch den Migrationsdienst für diesen Server. Die mitgelieferte Compose-Datei setzt deren Verbindungszeichenfolgen auf den enthaltenen PostgreSQL-Dienst.

Ist die OneCLI-Agent-Sandbox eine echte Sicherheitsgrenze?

Der dokumentierte Compose-Mechanismus verwendet einen Docker-Container mit Begrenzungen für Arbeitsspeicher, CPU und Prozesse. Der Container ist an ein Netzwerk mit der Markierung internal: true angebunden, sodass externer Datenverkehr über das Gateway läuft. Die Ausgangskontrolle ist wirksam und kann mit docker network inspect überprüft werden. Der Agent wird als node ausgeführt, mit no-new-privileges, ohne Linux-Capabilities und mit dem standardmäßigen seccomp-Profil von Docker. Der Container verwendet weiterhin den Kernel des Hosts. Der Runner und der SSH-Terminierungsdienst binden beide /var/run/docker.sock ein. Das entspricht root-Zugriff auf einem Host, der einen rootful Docker-Daemon verwendet. Betreiben Sie OneCLI auf einem dedizierten System und speichern Sie Backups außerhalb dieses Systems.

Muss ich eingehende Ports für OneCLI öffnen?

Nein. Der Runner arbeitet ausschließlich ausgehend und stellt keine Ports bereit, die von außen erreichbar sind. Daher funktioniert er hinter NAT ohne Tunnel. Die Compose-Datei bindet das Dashboard, das Gateway, die API, PostgreSQL und unter dem Profil runner auch den SSH-Einstiegspunkt auf 10257 standardmäßig an 127.0.0.1. Greifen Sie über einen SSH-Tunnel auf das Dashboard zu. Alternativ können Sie die Reverse-Proxy-Konfiguration des Upstream-Projekts mit TLS sowie den erforderlichen Routen für Dashboard, API und Gateway verwenden, wenn mehrere Personen Zugriff benötigen. Beachten Sie dabei, dass die Registrierung für alle erreichbar bleibt, die den Dienst erreichen können. Das Gateway auf Port 10255 ist für Agents vorgesehen. Auf einem einzelnen System erreichen diese Agents es über das interne Docker-Netzwerk.

Kann ich OneCLI innerhalb eines Unternehmens kostenlos verwenden?

Der Kern steht unter der Apache-2.0-Lizenz. Der produktive Self-Hosting-Einsatz ist ohne kommerzielle Lizenz zulässig. Verzeichnisse mit dem Namen ee/ unterliegen der OneCLI Enterprise License. Diese ist für Entwicklung, Tests und Evaluierung kostenlos, erfordert in der Produktion jedoch ein Abonnement. Die Aufteilung ändert sich zwischen Releases. In den Hinweisen zu v2.0.1 vom 18. August 2026 wird erwähnt, dass eine von GitHub erkennbare Apache-2.0-Lizenzdatei wiederhergestellt wurde. Prüfen Sie daher LICENSE und die Verzeichnisse ee/ im exakt eingesetzten Tag, bevor Sie einen Workflow von einem einzelnen Feature abhängig machen.

War dieser Artikel hilfreich?