OneCLI zelf hosten met Docker Compose
Geef elk teamlid een eigen sandboxed agent en houd sleutels afgeschermd in één gateway. Installeer OneCLI met Docker Compose en PostgreSQL; reken op 2 GiB per sandbox.
Wat u krijgt bij het zelf hosten van OneCLI
Host OneCLI zelf en elk teamlid krijgt een eigen agent, elk draaiend in een eigen sandbox, waarbij API-keys worden beheerd in een gateway die de agents nooit inzien. De installatie is een Docker Compose-stack met PostgreSQL als backend, bereikbaar op http://localhost:10254. Houd rekening met een volwaardige server. De gedocumenteerde standaard is een geheugenlimiet van 2 GiB per agent-sandbox, dus begroot het geheugen voor de basis-stack en het werkelijke werkgeheugen van de agents afzonderlijk.
De stack bevat acht onderdelen; inzicht in deze componenten maakt de rest van deze handleiding leesbaarder.
- Web dashboard (Next.js), poort
10254. Aanmaken van agents, chat, bewerken van geheugen en vaardigheden, verbindingen en secrets. - API server, poort
10256. Het controlepaneel: database, afhandeling van gesprekken, werkrijen. - Rust gateway, poort
10255. Onderschept uitgaande verzoeken van agents en voegt inloggegevens toe. - Runner. De README omschrijft dit als de component die "agent-sandboxes start, parkeert en opruimt. Alleen uitgaand verkeer, raakt de database nooit aan."
- Sandbox Supervisor. De README omschrijft dit als de component die "binnen elke sandbox draait en een leverancier-neutrale interface gebruikt, zodat de agent-runtime vervangbaar is."
- SSH terminator, poort
10257. De README noemt dit "de SSH-voordeur": het beëindigt SSH-verbindingen met kortstondige certificaten die door de API worden uitgegeven en koppelt elke sessie aan een agent-sandbox. Het draait onder hetzelfderunner-profiel als de runner. - Channel adapter. Een daemon die een Slack-app verbindt, zodat een agent onder zijn eigen naam antwoordt in kanalen en privéberichten.
- PostgreSQL. Het meegeleverde compose-bestand draait
postgres:18-alpinemet eenpgdata-volume.
De naam suggereert CLI, het product is een server
OneCLI is een serverplatform. De naam verwijst naar een command-line tool die u op een laptop installeert, maar dat beeld is onjuist voor het product in deze handleiding. Er bestaat wel een afzonderlijke command-line client in de onecli/onecli-cli repository, en deze leidt het verkeer van een lokale coding agent via een gateway. Wat u hier implementeert is een webapplicatie voor meerdere gebruikers: een accountsysteem met organisaties en uitnodigingen, een database met conversaties en geheimen, en een runner die containers start.
Het model per persoon vormt het volledige ontwerp. Uit de README: "U maakt een agent per persoon, geeft elke agent de benodigde toegang, en deze werkt in een sandbox, geleid door een gateway die de inloggegevens injecteert en uw beleid afdwingt." Elke agent heeft een eigen bestandssysteem en shell, een eigen conversatiepagina, geheugen dat door het platform wordt bewaard, en vaardigheden die u eenmalig schrijft. Inloggegevens werken in tegenovergestelde richting van de gebruikelijke opzet. In plaats van een API key naar de omgeving van elke persoon te kopiëren, slaat u de key eenmalig op en verleent u deze aan de agents die toestemming hebben om deze te gebruiken.
Wat de server nodig heeft voordat u begint
- Docker, met de Compose-plugin versie 2.24.0 of nieuwer. Het meegeleverde compose-bestand gebruikt optionele
env_file-mappings metrequired: false, wat Docker ondersteunt vanaf 2.24.0. De migratieopmerkingen verklaren de genoemde ondergrens van 2.19 als ondersteuning voor eenmalige afhankelijkheden onderup --wait, maar dat dekt niet de optionele omgevingsbestanden van het bestand. - Geheugen, wat de werkelijke beperkende factor is. Lees de sectie over dimensionering hieronder voordat u een plan kiest.
- Vrije loopback-poorten
10254,10255,10256,10257en5432. Poort10257is de SSH-toegangspoort, die start met hetrunner-profiel dat deze handleiding inschakelt.
U hoeft PostgreSQL niet zelf te installeren: het compose-bestand voert dit uit als een service. De installatiewizard hieronder vereist Node.js en pnpm op de host. Het werken aan de code zelf gebruikt ook mise om de toolchain vast te pinnen, inclusief Rust voor de gateway.
Hoeveel agent-sandboxes passen er op uw VPS?
De documentatie van de runner zelf geeft concrete cijfers in plaats van schattingen. Elke sandbox is begrensd op 2048 MB geheugen (RUNNER_SANDBOX_MEMORY_MB), één CPU (RUNNER_SANDBOX_CPUS) en 512 processen (RUNNER_SANDBOX_PIDS). De limiet voor gelijktijdigheid is 4 (RUNNER_MAX_SANDBOXES), en de documentatie adviseert ongeveer 10 GiB vrij geheugen bovenop de basisstack om aan die limiet te voldoen.
De gegevens achter deze grafiek
[
{
"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
}
]Deze aantallen slots zijn gebaseerd op rekenkunde, niet op een benchmark: het totale geheugen, minus een aangenomen 2 GB voor PostgreSQL en de overige langlopende services, gedeeld door de sandbox-limiet van 2 GiB. Op basis daarvan begroot het 2 GB box voor 0 sandboxes op hun volledige geheugenlimiet; nul betekent dat er onder deze aannames geen budget is voor een volledige bezetting, niet dat Docker weigert een agent te starten. Een 16 GB box laat ruimte voor 7, comfortabel boven de standaardlimiet van vier en boven de ongeveer 10 GiB vrij geheugen waar de runner-documentatie om vraagt. Het 32 GB box brengt u naar 15. Om er meer dan vier tegelijk uit te voeren, moet u ook RUNNER_MAX_SANDBOXES verhogen.
Twee factoren beïnvloeden deze berekening. Een sandbox met een achtergrondproces dat actief is, wordt nooit geparkeerd, waardoor deze zijn slot permanent bezet houdt. U moet RUNNER_MAX_SANDBOXES daarom dimensioneren op basis van de aanhoudende belasting en niet op basis van de drukste minuut. Het platform hanteert hiervoor een bovengrens: standaard houdt elke runner maximaal RUNNER_MAX_SANDBOXES minus één sandbox actief (nooit minder dan één, overschrijfbaar met MAX_HELD_AWAKE_SANDBOXES via de API). Daarboven wordt de sandbox die het langst inactief is verwijderd en wordt het bewaakte proces als verloren gerapporteerd. Geheugen- en CPU-gebruik hangen af van de werklast. Elke sandbox is begrensd op één CPU, dus vier actieve agents kunnen vier cores gebruiken, maar de geheugeninstelling van 2 GiB is een plafond, geen reservering: vier inactieve-maar-actieve agents verbruiken niet automatisch 8 GiB.
Runner-instellingen die u mogelijk wilt wijzigen
RUNNER_MAX_SANDBOXES(standaard4): hoeveel sandboxes er tegelijkertijd draaien.RUNNER_SANDBOX_MEMORY_MB(standaard2048): geheugenlimiet per sandbox.RUNNER_SANDBOX_CPUS(standaard1): CPU-limiet per sandbox.RUNNER_SANDBOX_PIDS(standaard512): proceslimiet per sandbox.RUNNER_NETWORK_INTERNAL(standaardtrue): houdt het sandbox-netwerk zonder route naar buiten. Laat dit ingeschakeld.RUNNER_SANDBOX_NETWORK(standaardonecli-sandboxes): het netwerk waar sandboxes lid van worden.RUNNER_RECONCILE_SECONDS(standaard60): hoe vaak de runner de status synchroniseert.RUNNER_ORPHAN_GRACE_SECONDS(standaard3600): leeftijd waarop wees-containers en -volumes worden verwijderd.RUNNER_AGENT_IMAGE: overschrijft de sandbox-image, die andersONECLI_VERSIONvolgt.
OneCLI installeren met Docker Compose
De documentatie voor self-hosting van de upstream schrijft drie geheimen naar docker/.env naast het compose-bestand. Die reeks laat de runner-token, de Docker socket-groep en de SSH-inloggegevens weg die vereist zijn voor de services die het inschakelt; voer daarom de installatiewizard uit voordat u de stack start.
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 --waitLees dat blok voordat u het uitvoert. De heredoc-marker is niet voorzien van aanhalingstekens, waardoor uw shell elke head -c 32 /dev/urandom | base64 uitvoert en het resultaat schrijft in plaats van de letterlijke tekst. SECRET_ENCRYPTION_KEY is de AES-256-GCM-sleutel voor elk geheim in de database. GATEWAY_INTERNAL_SECRET authenticeert de gateway bij de API. BETTER_AUTH_SECRET ondertekent sessiecookies. COMPOSE_PROFILES=runner is de regel die het belangrijkst is, omdat de runner-service achter een Compose-profiel zit: laat deze weg en de stack start gezond op, terwijl er nooit een agent-sandbox wordt gestart.
--wait wacht tot services draaien of gezond zijn en tot de migratie-afhankelijkheid succesvol is voltooid; een exit-code die niet nul is, is dus uw eerste signaal dat er iets mis is. Kijk daarna wat er daadwerkelijk is opgestart.
docker compose ps
docker compose logs migrationsZet de versie vast. ONECLI_VERSION stelt de tag in voor elke service tegelijk, en de agent-sandbox-image volgt deze tenzij RUNNER_AGENT_IMAGE naar een andere locatie wijst. Gebruik het kale versienummer: de gepubliceerde image-tags bevatten geen v-prefix. Per 1 november 2026 is de huidige release v2.17.0, gepubliceerd op 31 oktober 2026. Voeg deze toe aan hetzelfde bestand en gebruik vervolgens het gedocumenteerde upgrade-pad zodat actieve sandboxes ook naar die image overgaan.
echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd dockerEr bestaat ook een installer, curl -fsSL https://onecli.sh/install | sh, die zijn configuratie naar ~/.onecli/.env schrijft en hetzelfde werk verricht. Deze stelt ONECLI_VERSION=latest in voor zijn eigen uitvoering, wat een vastgezette versie in dat .env-bestand overschrijft. Het Compose-pad is de methode waarbij u elk bestand kunt lezen voordat er iets wordt uitgevoerd, en dit is de methode die u moet gebruiken op een server die al andere Compose-stacks bevat. De checkout-setup hierboven upgradet met pnpm run setup --upgrade. Dat pad vereist Node.js en pnpm op de host, en werken aan de code zelf voegt mise en Rust toe voor de gateway, dus het is geschikt voor mensen die van plan zijn OneCLI aan te passen. Voor Kubernetes heeft release v2.11.0 (8 oktober 2026) een Helm-chart toegevoegd; de huidige chart voert agent-sandboxes uit als Jobs met persistente volumes, zonder een Docker-daemon, en documenteert de vereiste geheimen, database- en routeringsconfiguratie.
Het dashboard bereiken vanaf uw laptop
Elke gepubliceerde poort in het meegeleverde compose-bestand bindt aan ${ONECLI_BIND_HOST:-127.0.0.1}. Op een VPS betekent dit dat het dashboard draait, maar dat niets buiten de server het kan bereiken. Die standaardinstelling is correct. Behoud deze en gebruik een tunnel:
ssh -N -L 10254:127.0.0.1:10254 you@your-serverOpen nu http://localhost:10254 op uw laptop. Het verkeer verloopt via de SSH-verbinding, waardoor er geen ongecodeerd dashboard op het publieke internet staat en er geen extra poort in de firewall hoeft te worden geopend.
Instelling ONECLI_BIND_HOST=0.0.0.0 publiceert het dashboard via onbeveiligde HTTP en publiceert daarnaast PostgreSQL, met het standaardwachtwoord uit het compose-bestand van onecli, tenzij u POSTGRES_PASSWORD instelt. Het publiceert ook de SSH-toegangspoort op poort 10257, een service die de Docker-socket mount. Als meerdere mensen toegang nodig hebben tot het dashboard, plaats dan een reverse proxy met TLS (transport layer security) ervoor en laat de bind-host ongewijzigd. Stel ONECLI_EXTERNAL_URL in op de HTTPS-URL en gebruik de reverse proxy-configuratie van de upstream, die de dashboard-, API- en gateway-paden doorstuurt naar hun respectievelijke services. Een proxy op zichzelf houdt onbevoegden niet buiten. De documentatie voor self-hosting stelt dat registratie standaard openstaat en dat er geen schakelaar is om dit uit te schakelen: iedereen die het dashboard bereikt, kan een account aanmaken, dat een eigen organisatie krijgt; alleen voor het toetreden tot uw organisatie is een uitnodiging nodig. Het advies is om het dashboard achter uw netwerkgrens te houden. Als die proxy al voor uw andere self-hosted applicaties staat, zorgt forward auth via een self-hosted single sign-on laag ervoor dat het dashboard achter de inlogprocedure komt die uw team al gebruikt, waardoor het verwijderen van een gebruiker op één plek ook deze toegang direct afsluit.
Maak het eerste account aan en verleen vervolgens een modelsleutel
Open het dashboard en maak direct uw account aan. Elk nieuw account krijgt een eigen organisatie en teamleden treden toe via een uitnodiging. Registratie blijft daarna openstaan; dit is een extra reden waarom het dashboard achter een tunnel of een geauthenticeerde proxy moet staan. Als u een upgrade uitvoert vanaf een release van vóór de inlogfunctionaliteit, registreer dan onmiddellijk: de documentatie voor self-hosting vermeldt dat de bestaande data wordt toegewezen aan het eerste account dat zich registreert. Op een bereikbare host wilt u dat dit uw account is.
Sla vervolgens een modelsleutel op voordat u een agent aanmaakt. Een gehoste agent heeft een verleende modelsleutel nodig en de volgorde is van belang: sla de sleutel op in het dashboard, verleen deze aan de agent en start pas daarna een gesprek. Slaat u het verlenen over, dan start de sandbox nooit; de agent antwoordt in de thread met de uitleg dat er een modelsleutel vereist is.
Verleen rechten beperkt. Elke agent krijgt alleen wat u heeft toegewezen en de gateway dwingt dit af bij elk verzoek. Een agent die één repository leest, heeft dus geen toegang tot de sleutel van uw betalingsprovider. Dezelfde lijst met verleende rechten is uw middel om de kosten te beheersen. Een agent per persoon die elk model kan aanroepen dat u bezit, betekent een factuur per persoon. Het is daarom de moeite waard om te lezen hoe u limieten stelt aan wat een agent kan uitgeven aan modelaanroepen voordat u er tien uitdeelt.
Hoe de gateway sleutels buiten de agents houdt
De gateway is een in Rust geschreven HTTPS-proxy die luistert op poort 10255. De HTTP-client van een agent is hierop gericht en de agent gebruikt een tijdelijke aanduiding (placeholder) in plaats van een echte inloggegevens. De gateway vergelijkt het uitgaande verzoek met de rechten van die agent, ontsleutelt het echte geheim, voegt dit in het verzoek in en stuurt het door. Geheimen worden opgeslagen in PostgreSQL, versleuteld met AES-256-GCM (Advanced Encryption Standard, 256-bit, Galois/Counter Mode), en worden pas ontsleuteld op het moment van het verzoek. Elke aanroep wordt gelogd met de identiteit van de agent en het doel; dit vormt een audit-trail die niet mogelijk is wanneer sleutels in de shell-profielen van tien verschillende personen staan.
Twee mechanismen bepalen hoe u dit implementeert.
- HTTPS-interceptie is een man-in-the-middle-proces. De gateway genereert een lokale certificate authority, de agent vertrouwt deze, en de gateway beëindigt de TLS-verbinding van de agent om vervolgens een nieuwe verbinding te openen naar de upstream-service. Daarom faalt een agent waarvan de HTTP-client de certificate authority van de gateway niet vertrouwt met een certificaatverificatiefout in plaats van een authenticatiefout.
- De agent identificeert zichzelf met een
Proxy-Authorization-header. Op een enkele machine, waar agents en de gateway een intern Docker-netwerk delen, verlaat die header nooit een netwerk dat niet van u is. Richt een agent die zich buiten de machine bevindt op de gateway en beveilig de verbinding met een VPN of TLS-transport, omdat die header een bearer token is; upstream adviseert een VPN voor de onbewerkte CONNECT-proxy-poort.
De eerlijke afweging: de gateway leest elk verzoek dat uw agents doen, in leesbare tekst, volgens het ontwerp. Het is het meest gevoelige proces op de machine. Behandel de host ervan dienovereenkomstig en houd het aantal mensen dat kan inloggen beperkt met least-privilege Linux-gebruikers.
Waarom de runner geen inkomende poort nodig heeft
De runner werkt uitsluitend via uitgaand verkeer. Volgens de documentatie: "hij opent geen poorten die van buitenaf bereikbaar zijn, waardoor een laptop, een homelab of een VPC achter NAT allemaal werken zonder inkomend verkeer, tunnels of TLS-termination." NAT staat voor network address translation, de functie die een thuisrouter uitvoert. De runner maakt verbinding met het control plane en haalt daar taken op, dus er hoeft niets te worden geforward of geopend.
Dit ontwerp werpt zijn vruchten af in het sandbox-netwerk. Het compose-bestand definieert een tweede netwerk gemarkeerd met internal: true, wat in Docker betekent dat er geen externe netwerkverbinding mogelijk is. Sandboxes maken hier deel van uit. De gateway is dual-homed over beide netwerken en is daarmee de enige uitgang. De documentatie van de runner verwoordt dit punt duidelijk: "een internal-netwerk met de gateway dual-homed hierop maakt van gateway-only egress een harde grens in plaats van een suggestie." Een agent kan de gateway niet omzeilen door een directe verbinding met een extern adres te openen; het beleid van de gateway bepaalt nog steeds welke verzoeken worden toegestaan.
Controleer dit op uw eigen systeem in plaats van enkel op de bovenstaande alinea te vertrouwen.
docker network ls
docker network inspect onecli-sandboxes | grep -i internalU zou "Internal": true moeten zien. Als er false staat, is de egress-controle uitgeschakeld en is de gateway weer slechts een suggestie. Gebruik de naam van het sandbox-netwerk die docker network ls weergeeft, aangezien onecli-sandboxes slechts de standaardwaarde is.
Hoe sterk is de OneCLI-sandbox?
Lees dit gedeelte aandachtig door, aangezien de term "sandboxed" veel gewicht in de schaal legt in de beschrijving van het project zelf, terwijl het mechanisme in de documentatie van de runner en de backend-code wordt toegelicht.
De README stelt dat elke agent "zijn eigen geïsoleerde sandbox krijgt, met een bestandssysteem en een shell", en noemt de Sandbox Supervisor als de component die "binnen elke sandbox draait en een leverancier-neutrale harness-interface gebruikt, zodat de agent-runtime vervangbaar is". Geen van beide zinnen specificeert waaruit de isolatie bestaat. De documentatie van de runner doet dit wel: de standaard backend is Docker (RUNNER_BACKEND=docker), en een sandbox is een Docker-container met een geheugenlimiet, een CPU-limiet en een proceslimiet, gekoppeld aan het interne netwerk. De code bevat een interface voor andere backends. De huidige runner-code implementeert ook een Kubernetes-backend, die de Helm-chart gebruikt voor sandbox-Jobs en persistente volumes. Bij de Compose-installatie in deze handleiding is een sandbox een Docker-container.
De documentatie van de runner beschrijft nu de Docker-grens: de agent draait als node, met no-new-privileges, waarbij alle Linux-capabilities zijn verwijderd en het standaard seccomp-profiel van Docker wordt gebruikt. De backend koppelt alleen de duurzame home-directory van de agent in de sandbox. Hanteer daarom een strikte interpretatie. De limieten zijn resourcelimieten. Het interne netwerk biedt daadwerkelijke controle over uitgaand verkeer. De isolatie tussen een agent en uw host maakt gebruik van deze container-controles, en een container deelt de kernel van de host.
Er is een tweede feit om rekening mee te houden. De runner-service koppelt /var/run/docker.sock, omdat dit de manier is waarop sandboxen worden aangemaakt. Toegang tot de socket van een Docker-daemon met root-rechten staat gelijk aan root-toegang op de host, aangezien iedereen die die API kan aanroepen, een container kan starten met het bestandssysteem van de host daarin gekoppeld. De meegeleverde Docker-gebaseerde runner gebruikt die socket. Het gevolg is dat het runner-proces even gevoelig is als de gateway. De SSH-terminator koppelt dezelfde socket zodat deze commando's kan uitvoeren in sandbox-containers, en de opmerkingen in het compose-bestand zelf noemen die koppeling root-equivalent op de host. Houd poort 10257 daarom op loopback, tenzij u een reden heeft om deze open te stellen.
Behandel de grens van de gedeelde kernel conservatief. In de praktijk betekent dit drie gewoontes:
- Draai OneCLI op een machine die niets anders doet. Geen ongerelateerde productieservices, geen gedeelde database, geen data van andere teams.
- Ga ervan uit dat een agent die willekeurige code-uitvoering binnen zijn sandbox krijgt, de host kan bereiken, en zorg dat dit scenario overleefbaar is door back-ups buiten de machine te bewaren.
- Lees
apps/runner/srcof vraag het aan de upstream-ontwikkelaars voordat u een collega vertelt dat de agent volledig is ingesloten.
Voor een beeld van hoe een gedocumenteerde grens eruitziet, en de vragen die het waard zijn om aan de upstream-ontwikkelaars te stellen, vergelijkt u dit met hoe een echte agent-sandbox-grens eruitziet. De vraag is of het gedocumenteerde mechanisme de dreigingen afdekt die u moet stoppen.
De licentiesplitsing en waarom u dit moet controleren voor de bouw
De kern van OneCLI valt onder Apache-2.0 en het zelf hosten hiervan in een productieomgeving is toegestaan. Mappen met de naam ee/ vallen onder een afzonderlijke OneCLI Enterprise License: gratis voor ontwikkeling, testen en evaluatie, waarbij een abonnement vereist is voor productiegebruik. De release notes van v2.0.1 van 18 augustus 2026 vermelden het herstellen van een door GitHub detecteerbaar Apache-2.0 licentiebestand, waardoor de badge op de repository-pagina onlangs is verplaatst. Controleer de tag die u daadwerkelijk implementeert in plaats van een samenvatting die op een andere datum is geschreven.
cd onecli && find . -type d -name ee -not -path '*/node_modules/*'Alles onder die paden vormt het commerciële gedeelte. Als een functie waar u op wilt vertrouwen zich daar bevindt, bepaal dan de kosten voordat u er een proces omheen bouwt.
Upgrades, migraties en het ene bestand dat u niet mag verliezen
Bij upgrades moeten de service-images en het afzonderlijke agent-image worden vernieuwd, waarna de actieve sandboxes opnieuw worden opgestart. Een eenmalige migratieservice wordt vóór de API uitgevoerd op elke up. Als een migratie mislukt, weigert de stack te starten in plaats van te werken met een gedeeltelijk gemigreerd schema. Dat is het gewenste gedrag, omdat een mislukte upgrade dan zichtbaar is als een storing in plaats van als stille corruptie, en docker compose logs migrations legt uit waarom.
Eén stap wordt gemakkelijk over het hoofd gezien. De documentatie voor self-hosting waarschuwt tegen het upgraden met een kale docker compose pull && docker compose up -d, omdat het agent-sandbox-image geen Compose-service is. Het is de RUNNER_AGENT_IMAGE-waarde op de runner, waardoor docker compose pull deze nooit ziet en gehoste agents op een oud sandbox-image kunnen blijven draaien zonder waarschuwing. Update de checkout, verplaats de pin en voer de gedocumenteerde upgrade-tool uit, die het sandbox-image ophaalt en actieve sandboxes opnieuw opstart.
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 migrationsVervang 2.17.0 door de release waarnaar u overstapt. Het herstarten van sandboxes onderbreekt lopende taken; de duurzame werkruimte van elke agent blijft behouden.
Als u in plaats daarvan het installatiescript hebt gebruikt, voer dat script dan opnieuw uit in plaats van handmatig te pullen, zodat het Compose-bestand in lijn blijft met de images waarnaar het verwijst. Exporteer eerst ONECLI_VERSION als u een specifieke release wilt, aangezien het script een pin overschrijft die alleen in het .env-bestand wordt bewaard.
Maak back-ups van de database, de configuratie en de volumes van de agent-werkruimtes. PostgreSQL bevat de agents, conversaties, het geheugen en de versleutelde geheimen. Het docker/.env-bestand bevat SECRET_ENCRYPTION_KEY, en zonder die sleutel zijn de versleutelde geheimen onleesbaar, zelfs als de rest van de database wordt hersteld. De /workspace van elke agent bevindt zich op een afzonderlijk duurzaam volume en vereist een eigen back-up.
cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backupBewaar die kopieën en de back-ups van de werkruimtes buiten de server. De routine is dezelfde als die elke stateful Compose-stack nodig heeft. Als u dus al een back-up maakt en een Docker Compose-stack upgradet volgens een schema, voeg dan de database, configuratie en werkruimtevolumes daaraan toe en u hoeft er niet meer naar om te kijken.
Wanneer het niet werkt
- De stack wordt nooit gezond en
docker compose up -d --waitsluit af met een non-zero exitcode. Lees eerstdocker compose logs migrations, omdat de API bewust wacht op die service. - Een agent blijft inactief en er verschijnt geen sandbox. Controleer of
COMPOSE_PROFILES=runnerindocker/.envstaat en ofdocker compose pseen runner vermeldt. Controleer vervolgens of de agent beschikt over een toegewezen modelsleutel, aangezien sandboxes niet starten zonder deze sleutel. - Geen slots beschikbaar.
RUNNER_MAX_SANDBOXESstaat standaard op 4, en een sandbox met een draaiend achtergrondproces houdt zijn slot bezet totdat de 'held-awake' limiet deze verwijdert.docker pstoont wat er daadwerkelijk actief is. - De stack start niet en Docker meldt dat een poort al in gebruik is. Met het
runner-profiel ingeschakeld, vereist de SSH-toegangspoort10257naast de andere vier poorten. - Containers verdwijnen of de host wordt extreem traag. Controleer op geheugenuitputting met
dmesg -T | grep -i oom; de standaard geheugenlimiet staat toe dat een enkele sandbox tot 2048 MB gebruikt. - HTTPS-aanroepen van een agent falen met certificaatverificatiefouten in plaats van authenticatiefouten. De HTTP-client vertrouwt de certificaatautoriteit van de gateway niet.
- Oude containers of volumes blijven achter nadat u een agent verwijdert. De runner voert elke 60 seconden een reconciliatie uit en verwijdert weesbestanden die ouder zijn dan
RUNNER_ORPHAN_GRACE_SECONDS, wat standaard op 3600 staat. Wacht dus een uur voordat u dit als een lek beschouwt.
Is dit de juiste oplossing voor u?
De fit-test is kort. OneCLI is nuttig wanneer meerdere personen elk een agent nodig hebben en u de inloggegevens op één centrale plek wilt beheren: één opslaglocatie voor rotatie, één auditlogboek om te lezen en één dashboard waar het intrekken van iemands toegang ook daadwerkelijk effectief is. Dit is een reëel operationeel probleem, en het kopiëren van een API key naar zes laptops is daarvoor een inferieure oplossing.
Voor één persoon is dit veel infrastructuur zonder praktisch voordeel. U zou PostgreSQL, een control plane, een gateway en een runner uitvoeren om één agent voor uzelf beschikbaar te maken. Het credentialprobleem dat de gateway oplost, speelt nauwelijks wanneer u de enige persoon bent die de key beheert. Gebruik in plaats daarvan één harness op een kleinere machine: een enkele agent-harness op een VPS doet hetzelfde werk met een fractie van het geheugen. Als u nog geen richting hebt gekozen, is de vergelijking in self-hosted AI-agents vergeleken een goedkopere eerste stap. Als agents zelf nog onbekend zijn en niet de servers waarop ze draaien, doorloop dan eerst een stapsgewijs leerpad voor de werking van agents. Inzicht in wat een tool call en een memory store daadwerkelijk doen, bepaalt namelijk welke rechten de agent van elke gebruiker moet krijgen.
FAQ
Wat zijn de minimale serververeisten om OneCLI zelf te hosten?
Docker met de Compose-plugin versie 2.24.0 of nieuwer, Node.js en pnpm voor de hier gebruikte installatiewizard, en voldoende geheugen. PostgreSQL wordt meegeleverd in het compose-bestand, dus u hoeft dit niet afzonderlijk te installeren. Het geheugen bepaalt de schaling van het plan: de runner beperkt elke agent-sandbox standaard tot 2048 MB, en de documentatie adviseert ongeveer 10 GiB vrije ruimte bovenop de basisstack om de standaardlimiet van vier sandboxes te ondersteunen. Uitgaande van het budget van 2 GB voor de basisstack in het schema, biedt een 4 GB-server ruimte voor één sandbox op de volledige limiet, en een 16 GB-server dekt de standaard gelijktijdigheidslimiet. Dit zijn richtgetallen voor de planning, geen gemeten minimale vereisten of vaste geheugentoewijzingen.
Heeft OneCLI PostgreSQL nodig, of kan het SQLite gebruiken?
Het vereist PostgreSQL. DATABASE_URL is gedocumenteerd als een PostgreSQL-verbindingsreeks, het meegeleverde compose-bestand draait postgres:18-alpine met een pgdata-volume, en een afzonderlijke migratieservice past het schema toe voordat de API start. Er is geen SQLite-optie gedocumenteerd. Voor een externe PostgreSQL-server configureert u zowel de API als de migratieservice om deze te gebruiken; het meegeleverde compose-bestand stelt hun verbindingsreeksen in op de gebundelde PostgreSQL-service.
Is de OneCLI agent-sandbox een echte beveiligingsgrens?
Het gedocumenteerde Compose-mechanisme is een Docker-container met limieten voor geheugen, CPU en processen, gekoppeld aan een netwerk gemarkeerd als internal: true zodat extern verkeer via de gateway verloopt. De uitgaande controle is reëel en u kunt deze verifiëren met docker network inspect. De agent draait als node, met no-new-privileges, waarbij alle Linux-capabilities zijn verwijderd en het standaard seccomp-profiel van Docker wordt gebruikt, terwijl de host-kernel wordt gedeeld. De runner en de SSH-terminator mounten beide /var/run/docker.sock, wat gelijkstaat aan root op een host die een rootful Docker-daemon gebruikt. Draai OneCLI op een toegewezen server en bewaar back-ups buiten die server.
Moet ik inkomende poorten openen voor OneCLI?
Nee. De runner is alleen uitgaand en houdt geen poorten open die van buitenaf bereikbaar zijn, dus het werkt achter NAT zonder tunnel. Het compose-bestand bindt het dashboard, de gateway, de API, PostgreSQL en, onder het runner-profiel, de SSH-toegangspoort op 10257 standaard aan 127.0.0.1. Benader het dashboard via een SSH-tunnel, of gebruik de reverse proxy-configuratie van de upstream met TLS en de vereiste routes voor het dashboard, de API en de gateway als meerdere personen er toegang toe nodig hebben. Houd er rekening mee dat registratie open blijft voor iedereen die erbij kan. De gateway op 10255 is bedoeld voor agents, en op een enkele server bereiken die agents deze via het interne Docker-netwerk.
Is OneCLI gratis te gebruiken binnen een bedrijf?
De kern is Apache-2.0 en zelf-gehost productiegebruik is toegestaan zonder commerciële licentie. Mappen genaamd ee/ vallen onder de OneCLI Enterprise License, die gratis is voor ontwikkeling, testen en evaluatie, maar een abonnement vereist in productie. De verdeling verschuift tussen releases, en de v2.0.1-notities van 18 augustus 2026 vermelden het herstellen van een via GitHub detecteerbaar Apache-2.0 licentiebestand. Controleer daarom LICENSE en de ee/-mappen in de exacte tag die u implementeert voordat u een workflow bouwt op basis van een specifieke functie.