OneCLI selbst hosten: Ein Agent pro Person

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 einer eigenen Sandbox. Die API-Schlüssel werden in einem Gateway verwaltet, auf das die Agenten nicht zugreifen können. Die Installation besteht aus einem Docker-Compose-Stack mit PostgreSQL. Er ist unter http://localhost:10254 erreichbar. Planen Sie einen eigenen Server ein. Laut dokumentiertem Standardwert sind 2 GiB Arbeitsspeicher pro Agenten-Sandbox vorgesehen. Daher ist diese Auslastung nicht für einen VPS mit 1 GB Arbeitsspeicher geeignet.

Dieser Stack besteht aus sieben Komponenten. Wenn Sie ihre Aufgaben kennen, lässt sich der restliche Leitfaden leichter nachvollziehen.

• Web-Dashboard (Next.js), Port 10254. Agentenerstellung, Chats, Bearbeitung von Speicher und Skills sowie Verbindungen und Secrets.
• API-Server, Port 10256. Die Steuerungsebene: Datenbank, Verarbeitung von Konversationen und Arbeitswarteschlangen.
• Rust-Gateway, Port 10255. Fängt ausgehende Anfragen der Agenten ab und fügt Zugangsdaten ein.
• Runner. Die README beschreibt ihn als Komponente, die „Agenten-Sandboxen startet, pausiert und beendet. Nur ausgehend, ohne Zugriff auf die Datenbank.“
• Sandbox Supervisor. Die README beschreibt ihn als Komponente, die „innerhalb jeder Sandbox läuft und über eine herstellerneutrale Harness-Schnittstelle kommuniziert, sodass die Agentenlaufzeit austauschbar ist.“
• 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 einer CLI, aber das Produkt ist ein Server

OneCLI ist eine Serverplattform. Der Name erinnert an ein Befehlszeilenwerkzeug, das Sie auf einem Laptop installieren. Dieses Bild passt jedoch nicht zu dem Produkt in dieser Anleitung. Es gibt einen separaten Befehlszeilenclient im Repository onecli/onecli-cli. Er leitet den Datenverkehr eines lokalen Coding-Agenten über ein Gateway. Was Sie hier bereitstellen, ist eine Webanwendung für mehrere Benutzer: ein Kontosystem, bei dem das erste Konto die Instanz besitzt, eine Datenbank für Unterhaltungen und Secrets sowie ein Runner, der Container startet.

Das Modell mit einem Agenten pro Person ist die Grundlage des gesamten Designs. In der README steht: „Sie erstellen für jede Person einen Agenten, geben jedem Agenten die erforderlichen Zugriffsrechte und lassen ihn in einer Sandbox arbeiten. Der Datenverkehr wird über ein Gateway geleitet, das die Zugangsdaten einfügt und Ihre Richtlinien durchsetzt.“ Jeder Agent verfügt über ein eigenes Dateisystem und eine eigene Shell, eine eigene Unterhaltungsseite, vom System gespeicherten Speicher sowie Skills, die Sie einmal erstellen. Zugangsdaten werden entgegengesetzt zur üblichen Vorgehensweise verwaltet. Statt einen API-Schlüssel in die Umgebung jeder Person zu kopieren, speichern Sie den Schlüssel einmal und geben ihn nur für die Agenten frei, die ihn verwenden dürfen.

Was die Umgebung vor dem Start benötigt

• Docker mit dem Compose-Plugin in Version 2.19 oder neuer. Die Compose-Datei verwendet einen einmalig ausgeführten Migrationsdienst, auf den die API wartet. Diese Form der Abhängigkeit erfordert Version 2.19.
• Arbeitsspeicher als eigentliche Einschränkung. Lesen Sie den Abschnitt zur Dimensionierung weiter unten, bevor Sie einen Tarif auswählen.
• Freie Loopback-Ports 10254, 10255, 10256 und 5432.

Sie müssen PostgreSQL nicht selbst installieren: Die Compose-Datei führt es als Dienst aus. Node.js und Rust benötigen Sie ebenfalls nicht. Diese Komponenten werden nur für den Build-from-Source-Weg benötigt, bei dem mise die Toolchain festlegt.

Wie viele Agent-Sandboxen passen auf Ihren VPS?

Die Dokumentation des Runners nennt konkrete Werte. Jede Sandbox erhält 2048 MB Arbeitsspeicher (RUNNER_SANDBOX_MEMORY_MB), eine CPU (RUNNER_SANDBOX_CPUS) und 512 Prozesse (RUNNER_SANDBOX_PIDS). Die Parallelitätsgrenze liegt bei 4 (RUNNER_MAX_SANDBOXES). Für diese Grenze empfiehlt die Dokumentation zusätzlich zum Basis-Stack etwa 10 GiB freien Arbeitsspeicher.

[
  {
    "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 Slot-Anzahlen sind eine Rechenvorgabe, kein Benchmark: Der Gesamtspeicher wird um ungefähr 2 GB für PostgreSQL und die vier dauerhaft laufenden Dienste reduziert. Das Ergebnis wird durch das Sandbox-Limit von 2 GiB geteilt. Auf dieser Grundlage passen 2 GB box Sandboxen auf 0, sodass der günstigste Plan überhaupt keinen gehosteten Agenten ausführen kann. 16 GB box lässt Platz für 7 und liegt damit deutlich über der Standardgrenze von 4 sowie über den ungefähr 10 GiB freien Arbeitsspeicher, die die Runner-Dokumentation verlangt. Mit 32 GB box kommen Sie auf 15.

Zwei Faktoren weichen von dieser Rechnung ab. Eine Sandbox mit einem laufenden Hintergrundprozess wird nicht angehalten. Sie belegt ihren Slot daher dauerhaft. Deshalb dimensionieren Sie RUNNER_MAX_SANDBOXES für die dauerhafte Last und nicht für die Auslastung während der geschäftigsten Minute. Außerdem ist der Arbeitsspeicher vor der CPU erschöpft. Jede Sandbox ist auf eine CPU begrenzt. Vier ausgelastete Agenten benötigen daher vier Kerne. Vier inaktive, aber aktive Agenten belegen trotzdem 8 GiB.

OneCLI mit Docker Compose installieren

Das Self-Hosting-Dokument des Upstream-Projekts gibt genau diese Sequenz vor. Sie schreibt drei Geheimnisse in docker/.env neben der Compose-Datei und startet anschließend den Stack.

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
docker compose up -d --wait

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

--wait hält die Shell an, bis jeder Dienst den Status healthy meldet. Ein Exit-Code ungleich 0 ist daher Ihr erstes Signal dafür, dass etwas nicht stimmt. Prüfen Sie anschließend, was tatsächlich gestartet wurde.

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 folgt diesem Tag, sofern RUNNER_AGENT_IMAGE nicht auf einen anderen Ort verweist. Am 19. August 2026 ist v2.0.1 die aktuelle Version, veröffentlicht am 18. August 2026. Fügen Sie sie in dieselbe Datei ein und starten Sie den Stack erneut.

echo 'ONECLI_VERSION=v2.0.1' >> .env
docker compose up -d --wait

Es gibt auch ein Installationsprogramm namens curl -fsSL https://onecli.sh/install | sh. Es schreibt seine Konfiguration nach ~/.onecli/.env und führt dieselben Schritte aus. Der Compose-Weg ermöglicht es Ihnen, jede Datei zu prüfen, bevor etwas ausgeführt wird. Verwenden Sie ihn daher auf einem System, auf dem bereits andere Compose-Stacks laufen. Das Erstellen aus dem Quellcode ist ein dritter Weg. Im geklonten Repository ist er unter pnpm install und anschließend pnpm run setup dokumentiert. Dafür werden mise, Rust für das Gateway und trotzdem Docker benötigt. Dieser Weg ist für Personen vorgesehen, die den Code ändern möchten.

Das Dashboard vom 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 veröffentlichen Sie das Dashboard über unverschlüsseltes HTTP. Gleichzeitig veröffentlichen Sie PostgreSQL. Wenn mehrere Personen das Dashboard benötigen, setzen Sie einen Reverse Proxy mit TLS (Transport Layer Security) vor Port 10254 und lassen Sie den Bind-Host unverändert. Richten Sie das ein, bevor die Instanz einen Besitzer hat. Die Upstream-Dokumentation erklärt den Grund ausdrücklich: „Bis Sie das tun, hat die Instanz keinen Besitzer, und auf einem erreichbaren Host wird derjenige zuerst zum Besitzer, der zuerst darauf zugreift.“ Wenn der Proxy bereits vor Ihren anderen selbst gehosteten Anwendungen steht, bringt die Weiterleitung der Authentifizierung durch eine selbst gehostete Single-Sign-on-Schicht das Dashboard hinter den Login, den Ihr Team bereits verwendet. Wenn Sie eine Person an einer Stelle entfernen, schließen Sie damit auch diesen Zugang.

Erstellen Sie zuerst das erste Konto und weisen Sie ihm anschließend einen Model-Key zu

Öffnen Sie das Dashboard und erstellen Sie das Konto sofort. Dieses Konto besitzt die Instanz. Sobald es existiert, ist für den Beitritt eine Einladung erforderlich.

Speichern Sie anschließend einen Model-Key, bevor Sie einen Agenten erstellen. Ein gehosteter Agent benötigt einen zugewiesenen Model-Key. Die Reihenfolge ist wichtig: Speichern Sie den Key im Dashboard, weisen Sie ihn dem Agenten zu und starten Sie erst danach eine Unterhaltung. Wenn die Zuweisung fehlt, wird die Sandbox nicht gestartet. Der Agent bleibt dann scheinbar untätig.

Vergeben Sie Berechtigungen möglichst eng. Jeder Agent erhält nur die Berechtigungen, die Sie ihm zugewiesen haben. Das Gateway erzwingt diese Vorgabe bei jeder Anfrage. Ein Agent, der ein Repository liest, kann dadurch nicht auf den Key Ihres Zahlungsanbieters zugreifen. Über dieselbe Liste der Zuweisungen steuern Sie auch die Kosten. Ein Agent pro Person, der jedes von Ihnen besessene Modell aufrufen kann, erzeugt eine Rechnung pro Person. Lesen Sie daher, wie Sie die Ausgaben eines Agenten für Modellaufrufe begrenzen, bevor Sie zehn solcher Agenten bereitstellen.

Wie das Gateway Schlüssel von den Agents fernhält

Das Gateway ist ein in Rust geschriebener HTTPS-Proxy, der auf Port 10255 lauscht. Der HTTP-Client eines Agents wird darauf verwiesen, und der Agent verwendet anstelle eines echten Zugangsschlüssels eine Platzhalter-Credential. Das Gateway gleicht die ausgehende Anfrage mit den Berechtigungen dieses Agents ab, entschlüsselt das echte Secret, setzt es in die Anfrage ein 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 erst 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 Schlüssel in den Shell-Profilen von zehn Personen liegen.

Zwei technische Aspekte bestimmen die Bereitstellung.

• Die HTTPS-Überwachung ist ein Man-in-the-Middle-Verfahren. Das Gateway generiert eine lokale Zertifizierungsstelle, der Agent vertraut ihr, und das Gateway beendet die TLS-Verbindung des Agents. Anschließend öffnet es eine neue Verbindung zum Upstream-Dienst. Deshalb schlägt ein Agent, dessen HTTP-Client der Zertifizierungsstelle des Gateways nicht vertraut, mit einem Fehler bei der Zertifikatsprüfung fehl und nicht mit einem Authentifizierungsfehler.
• Der Agent identifiziert sich mit einem Proxy-Authorization-Header. Auf einem einzelnen Host, auf dem Agents und Gateway ein internes Docker-Netzwerk gemeinsam verwenden, verlässt dieser Header kein Netzwerk, das Sie nicht kontrollieren. Wenn Sie einen Agent außerhalb des Hosts auf das Gateway verweisen, benötigt der Proxy-Port eine eigene TLS-Konfiguration, weil dieser Header ein Bearer-Token ist.

Der wichtigste Nachteil: Das Gateway liest absichtlich jede Anfrage Ihrer Agents im Klartext. Es ist der sensibelste Prozess auf dem Rechner. Sichern Sie den Host entsprechend ab, und halten Sie die Zahl der Personen mit Anmeldemöglichkeit gering, indem Sie Linux-Benutzer mit geringsten Berechtigungen verwenden.

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 von außerhalb erreichbar sind. Daher funktionieren ein Laptop, ein Homelab oder eine VPC hinter NAT ohne Ingress, Tunnel oder TLS-Terminierung.“ NAT steht für Network Address Translation. Das ist die Funktion eines Heimrouters. Der Runner baut eine ausgehende Verbindung zur Control Plane auf und ruft dort Aufträge ab. Daher muss kein Port weitergeleitet oder geöffnet werden.

Dieses Design wirkt sich im Sandbox-Netzwerk aus. Die Compose-Datei definiert ein zweites Netzwerk mit der Markierung internal: true. In Docker bedeutet das, dass überhaupt keine Route aus dem Host heraus führt. Die Sandboxes werden diesem Netzwerk hinzugefügt. Das Gateway ist an beide Netzwerke angebunden und stellt daher den einzigen Ausgang dar. Die Runner-Dokumentation formuliert den Zweck eindeutig: „Ein internal-Netzwerk, an das das Gateway mit beiden Netzwerkschnittstellen angebunden ist, macht den ausschließlich über das Gateway möglichen ausgehenden Datenverkehr zu einer Grenze und nicht nur zu einer Empfehlung.“ Ein Agent, der Ihren Quellcode an eine selbst gewählte Adresse senden möchte, hat dafür keine Route.

Überprüfen Sie das 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 angezeigt wird, ist die Kontrolle des ausgehenden Datenverkehrs deaktiviert, und das Gateway ist wieder nur eine Empfehlung. Verwenden Sie den Namen des Sandbox-Netzwerks, den docker network ls ausgibt, da onecli-sandboxes nur der Standardwert ist.

Wie sicher ist die OneCLI-Sandbox?

Lesen Sie diesen Abschnitt langsam, denn die Bezeichnung „Sandbox“ hat in der eigenen Projektbeschreibung großes Gewicht, während der Mechanismus genau an einer Stelle dokumentiert ist.

In der README steht, dass jeder Agent „seine eigene isolierte Sandbox mit einem Dateisystem und einer Shell“ erhält. Außerdem wird der Sandbox Supervisor als Komponente bezeichnet, die „innerhalb jeder Sandbox ausgeführt wird und über eine herstellerneutrale Harness-Schnittstelle kommuniziert, sodass die Agentenlaufzeit austauschbar ist“. Keine der beiden Aussagen erklärt, woraus die Isolation besteht. Die Dokumentation des Runners tut dies: Das Standard-Backend ist Docker (RUNNER_BACKEND=docker), und 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. In der Dokumentation werden Kubernetes und MicroVMs als Module genannt, die jemand erst schreiben müsste. Heute ist eine Sandbox auf Ihrem Rechner ein Container.

Ebenso wichtig ist, was die Dokumentation nicht sagt. Es gibt kein Bedrohungsmodell. Es gibt keine Aussage dazu, ob der Docker-Daemon rootless ausgeführt wird, ob User-Namespace-Remapping aktiviert ist oder ob über die Docker-Standards hinaus seccomp- oder AppArmor-Profile verwendet werden. Auch gibt es keine Zusicherung einer Kernel-Grenze wie bei gVisor oder einer MicroVM. Gehen Sie daher von der engen Auslegung aus. Die Begrenzungen gelten für Ressourcen. Das interne Netzwerk ist eine echte Kontrolle des ausgehenden Datenverkehrs. Die Isolation zwischen einem Agenten und Ihrem Host entspricht dem, was ein gewöhnlicher Docker-Container bietet. Ein Container verwendet denselben Kernel wie der Host.

Ein zweiter Fakt ist zu berücksichtigen. Der Runner-Dienst bindet /var/run/docker.sock ein, weil er darüber Sandboxes erstellt. Der Zugriff auf den Docker-Socket entspricht root auf dem Host. Wer diese API aufrufen kann, kann einen Container mit dem Dateisystem des Hosts als Mount starten. Jeder Docker-basierte Runner funktioniert auf diese Weise. Daher ist der Runner-Prozess genauso schützenswert wie das Gateway.

Behandeln Sie diese Grenze als nicht nachgewiesen, bis das Upstream-Projekt sie dokumentiert. In der Praxis bedeutet das drei Gewohnheiten.

1. Führen Sie OneCLI auf einem Rechner aus, der nichts anderes erledigt. Kein unabhängiger Produktionsdienst, keine gemeinsam genutzte Datenbank und keine Daten eines anderen Teams.
2. Gehen Sie davon aus, dass ein Agent mit beliebiger Codeausführung innerhalb seiner Sandbox den Host erreichen könnte. Sorgen Sie dafür, dass dieser Fall durch Backups außerhalb des Rechners überstanden werden kann.
3. Lesen Sie apps/runner/src, oder fragen Sie beim Upstream-Projekt nach, bevor Sie einem Kollegen sagen, dass der Agent eingeschlossen ist.

Ein Beispiel dafür, wie eine dokumentierte Grenze beschrieben wird, und welche Fragen Sie beim Upstream-Projekt stellen sollten, finden Sie unter wie eine echte Grenze für eine Agenten-Sandbox aussieht. Der Unterschied besteht darin, ob jemand den Mechanismus und seine Grenzen schriftlich festgehalten hat.

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 bestehen aus einer Versionsaktualisierung und einem Neustart. Bei jedem up wird vor der API ein einmaliger Migrationsdienst ausgeführt. Wenn eine Migration fehlschlägt, verweigert der Stack den Start, statt mit einem teilweise migrierten Schema Anfragen zu bedienen. Dieses Verhalten ist erwünscht. Ein fehlgeschlagenes Upgrade äußert sich dann als Ausfall und nicht als unbemerkte Beschädigung. docker compose logs migrations erklärt den Grund.

cd onecli/docker
docker compose pull
docker compose up -d --wait
docker compose logs migrations

Wenn Sie stattdessen das Installationsskript verwendet haben, führen Sie dieses Skript erneut aus, anstatt das Image manuell abzurufen. Dadurch bleibt die Compose-Datei mit den referenzierten Images synchron.

Sichern Sie zwei Dinge. PostgreSQL enthält die Agents, Unterhaltungen, 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. Ein Datenbank-Dump allein stellt daher nichts Nutzbares wieder her.

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 beide Kopien außerhalb des Servers auf. Das Vorgehen entspricht dem für jeden zustandsbehafteten Compose-Stack. Wenn Sie bereits regelmäßig einen Docker-Compose-Stack sichern und aktualisieren, nehmen Sie diese beiden Pfade in den Ablauf auf und müssen sich nicht weiter darum kümmern.

Wenn es nicht funktioniert

• Der Stack wird nie als gesund gemeldet, 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 es wird keine Sandbox 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 Agenten ein Modellschlüssel zugewiesen wurde, da Sandboxes ohne einen solchen Schlüssel nicht gestartet werden.
• Es sind keine Slots mehr verfügbar. RUNNER_MAX_SANDBOXES verwendet standardmäßig 4, und eine Sandbox mit einem laufenden Hintergrundprozess belegt ihren Slot dauerhaft. docker ps zeigt, welche Prozesse tatsächlich noch laufen.
• Container verschwinden, oder der Host wird sehr langsam. Der Arbeitsspeicher ist erschöpft. dmesg -T | grep -i oom protokolliert vom Kernel beendete Prozesse wegen Speichermangels. Eine einzelne Sandbox kann selbst 2048 MB belegen.
• 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 gleicht den Zustand alle 60 Sekunden ab 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 Leck 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 viel Infrastruktur ohne praktischen Nutzen. Sie würden PostgreSQL, eine Control Plane, ein Gateway und einen Runner betreiben, um einen einzigen Agent bereitzustellen. Das Problem mit den Zugangsdaten, das das Gateway löst, besteht kaum, wenn nur Sie den Schlüssel besitzen. Betreiben Sie stattdessen ein einzelnes Harness auf einem kleineren System: ein einzelnes Agent-Harness auf einem VPS erfüllt diese Aufgabe mit einem Bruchteil des Arbeitsspeichers. Wenn Sie noch keine Richtung festgelegt haben, ist die Übersicht Self-hosted-AI-Agents im Vergleich der kostengünstigere erste Schritt.

FAQ

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

Docker mit dem Compose-Plugin in Version 2.19 oder neuer sowie ausreichend Arbeitsspeicher. PostgreSQL ist in der Compose-Datei enthalten und muss daher nicht separat installiert werden. Der Arbeitsspeicher bestimmt die mögliche Konfiguration: Der Runner weist standardmäßig 2048 MB pro Agent-Sandbox zu. Die Dokumentation fordert zusätzlich zum Basis-Stack etwa 10 GiB freien Speicher, um das Standardlimit von vier Sandboxes bereitzustellen. Etwa 2 GB entfallen auf PostgreSQL und die vier dauerhaft laufenden Dienste. Ein Server mit 4 GB kann jeweils einen Agenten ausführen. Ein Server mit 16 GB deckt das Standardlimit problemlos ab. Ein VPS mit 1 GB oder 2 GB kann überhaupt keinen gehosteten Agenten starten.

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 PostgreSQL bereits an anderer Stelle betreiben, setzen Sie DATABASE_URL auf diese Instanz und behalten Sie den Migrationsdienst bei. Eine fehlgeschlagene Migration stoppt den Stack, statt ihn mit einem teilweise angewendeten Schema bereitzustellen.

Ist die OneCLI-Agent-Sandbox eine echte Sicherheitsgrenze?

Der dokumentierte Mechanismus ist ein Docker-Container mit Begrenzungen für Arbeitsspeicher, CPU und Prozesse. Der Container ist an ein Netzwerk mit der Markierung internal: true angeschlossen und hat daher außer über das Gateway keine Route nach außen. Die Ausgangskontrolle ist wirksam und kann mit docker network inspect überprüft werden. Die Isolation vom Host entspricht der Stärke einer Container-Isolation. Upstream veröffentlicht jedoch weder ein Bedrohungsmodell noch eine Aussage zu rootless oder User-Namespaces und auch keine Kernel-Grenze wie gVisor oder eine microVM. Der Runner bindet außerdem /var/run/docker.sock ein. Das entspricht root-Rechten auf dem Host. Behandeln Sie die Grenze zwischen Agent und Host als nicht nachgewiesen, bis Upstream dazu eine Aussage veröffentlicht. Betreiben Sie OneCLI auf einem dedizierten Server und speichern Sie Backups außerhalb dieses Servers.

Muss ich eingehende Ports für OneCLI öffnen?

Nein. Der Runner verwendet ausschließlich ausgehende Verbindungen und stellt keine Ports bereit, die aus dem Internet erreichbar sind. Daher funktioniert er hinter NAT ohne Tunnel. Die Compose-Datei bindet Dashboard, Gateway, API und PostgreSQL standardmäßig an 127.0.0.1. Greifen Sie über einen SSH-Tunnel auf das Dashboard zu. Alternativ können Sie einen Reverse Proxy mit TLS vor Port 10254 setzen, wenn mehrere Personen Zugriff benötigen. Das Gateway auf Port 10255 ist für Agenten vorgesehen. Auf einem einzelnen Server erreichen diese Agenten das Gateway über das interne Docker-Netzwerk.

Kann OneCLI in einem Unternehmen kostenlos verwendet werden?

Der Kern steht unter Apache-2.0. Die Nutzung in einer selbst gehosteten Produktionsumgebung 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 sowie die Verzeichnisse ee/ im genau verwendeten Tag, bevor Sie einen Workflow von einem einzelnen Feature abhängig machen.