Dormice self-hosted agent sandbox installeren

Wat Dormice is, en wat het niet is

Dormice is een self-hosted agent sandbox: één daemon op een Linux VPS in uw beheer, die door uw agent-code via HTTP wordt aangeroepen om niet-vertrouwde code uit te voeren in een geïsoleerde container. Uw programma vraagt om een sandbox op naam, krijgt dezelfde sandbox terug ongeacht de status, voert daarin een commando uit en leest de output. De sandbox is een programmatische resource, geen machine waarop u inlogt.

Dit verschilt van het toewijzen van een volledige computer aan een agent. Een wegwerp-VM voor een coding agent is een omgeving waar u via SSH op inlogt, de agent laat experimenteren en die u vervolgens verwijdert. Dormice bevindt zich een niveau lager: het is de execution API die uw programma aanroept wanneer het al over code beschikt en een veilige plek nodig heeft om deze uit te voeren. Gebruik de wegwerp-VM wanneer een volledige machine de werkeenheid is. Gebruik Dormice wanneer een enkele exec-aanroep de werkeenheid is en u er honderd per dag wilt uitvoeren zonder honderd VM's te beheren.

Het project noemt zichzelf E2B-compatibel. E2B is een gehoste sandbox-dienst waarvan de client library door veel agent-frameworks al wordt geïmporteerd. Dormice bedient hetzelfde protocol onder zijn eigen URL-prefixen, waardoor een applicatie die is geschreven voor het officiële e2b-pakket blijft werken wanneer u deze naar uw eigen server wijst. De applicatiecode verandert niet. Slechts twee URL's en een API-key-prefix worden aangepast.

Wat "de SQLite van agent-sandboxes" in de praktijk betekent

SQLite is een database die u insluit in plaats van een service die u beheert, en Dormice leent die vergelijking direct. Eén daemon, één SQLite-bestand voor het grootboek, één TCP-poort. Geen Kubernetes, geen aparte database, geen scheduler. De daemon plaatst een lock naast zijn grootboek en weigert te starten wanneer het grootboek en de machine waarop hij zich bevindt niet bij elkaar horen; een split-brain-scenario kan dus niet onopgemerkt plaatsvinden. Eén machine is het uitgangspunt van het ontwerp. Als u een vloot over meerdere hosts nodig heeft, geeft de README duidelijk aan dat u voor iets anders moet kiezen, en dat advies kunt u beter opvolgen.

De tweede helft van het idee gaat over kosten. Een gehoste sandbox brengt elke seconde dat deze bestaat in rekening, dus gehoste sandboxes zijn ontworpen om wegwerpbaar te zijn. Dormice draait op hardware waar u al voor betaalt, dus de sandboxes zijn permanent en worden goedkoper naarmate ze langer stilstaan. Een sandbox koelt stapsgewijs af: actief, dan bevroren, dan gestopt, dan gearchiveerd. Elke acquire-actie haalt de sandbox terug vanuit de status waarin deze zich bevond.

Het bevriezen (freezing) is het onderdeel dat het begrijpen waard is, omdat dit ervoor zorgt dat het betaalbaar is om de sandbox van elke agent voor altijd te bewaren. Dit zijn de eigen gepubliceerde cijfers van het project, gemeten op hun hardware en niet op die van u.

[
  {
    "label": "Active, holding 1 GiB",
    "resident_memory_mib": 1024,
    "wake_ms": 0
  },
  {
    "label": "Frozen",
    "resident_memory_mib": 5,
    "wake_ms": 50
  }
]

Een inactieve sandbox die 1024 MiB aan geheugen verbruikt, daalt naar 5 MiB resident geheugen zodra deze bevroren is, en komt in ongeveer 50 ms weer terug. Processen worden op hun plek gepauzeerd en hervat, waardoor een langlopende agent zijn shell-status en zijn halfvoltooide werk behoudt tijdens het bevriezen. Reproduceer dit op uw eigen host voordat u uw capaciteitsplanning hierop baseert.

Wat de host nodig heeft voor de installatie

De host draait op Ubuntu of Debian op x86_64 en de installer vereist root-rechten. De daemon behoudt root-rechten tijdens runtime omdat deze loop-mounts uitvoert en naar cgroups schrijft.

Sandboxes draaien onder Docker met gVisor (een container-runtime die een userspace-kernel tussen de container en de host-kernel plaatst), wat de runsc runtime levert die elke sandbox gebruikt. Node 22 of nieuwer voert de daemon uit; de installer levert een eigen kopie mee, waardoor uw systeem-Node ongewijzigd blijft.

Swap moet aanwezig zijn en vm.swappiness moet op 100 staan. Dit is geen optimalisatieadvies, maar een functionele vereiste. Het bevriezen van een sandbox werkt door het geheugen van een inactieve sandbox naar swap te verplaatsen. gVisor houdt sandbox-geheugen vast als gedeeld geheugen en de kernel zal gedeeld geheugen niet swappen bij de standaard swappiness-waarde. Het project mat 0 bytes vrijgekomen geheugen bij de standaardwaarde en 99,5 procent bij 100. Controleer de waarde die de kernel daadwerkelijk gebruikt, aangezien sommige cloud-images vm.swappiness = 0 bevatten in een bestand dat u waarschijnlijk niet zult controleren.

sysctl vm.swappiness
swapon --show

sysctl vm.swappiness hoort vm.swappiness = 100 weer te geven en swapon --show hoort een swapfile te tonen. Als swappiness 0 weergeeft, is elke freeze-actie zinloos en betaalt u het volledige geheugengebruik voor elke inactieve sandbox.

Dormice installeren op Ubuntu

De gedocumenteerde installatie verloopt via één pipe naar bash:

curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash

Haal het script op en lees het door voordat u het uitvoert. Dit script draait als root en wijzigt uw host: het installeert Docker indien dit ontbreekt, downloadt gVisor en Caddy met checksum-verificatie, maakt een swapfile aan, schrijft systemd-units en voegt firewallregels toe.

curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh -o dormice-install.sh
less dormice-install.sh
sudo bash dormice-install.sh --swap-gb 8

--swap-gb stelt de grootte van de swapfile in en staat standaard op 16, wat op een kleine VPS veel schijfruimte in beslag neemt. --mirror cn schakelt de downloads om naar mirrors die bereikbaar zijn vanuit het vasteland van China. Het opnieuw uitvoeren van het installatieprogramma upgradet de code en herstelt configuratieafwijkingen; uw API-token wordt hierbij nooit geroteerd.

De code wordt geplaatst in /opt/dormice, de configuratie in /etc/dormice/env, sandbox-data in /var/lib/dormice, en de commando's dormice en dor in /usr/local/bin. Het installatieprogramma genereert het API-token tijdens de installatie en schrijft dit naar /etc/dormice/env met modus 600.

Er is geen getagde release om tegen te installeren. Sinds 4 augustus 2026 bevat de repository geen git-tags en geen GitHub-releases, dus het installatieprogramma kloont main en u ontvangt de code die op dat moment actueel is. Het vastzetten van een versie betekent daarom dat u de commit noteert die u daadwerkelijk heeft geïnstalleerd.

git -C /opt/dormice rev-parse HEAD

Sla die hash op bij uw implementatienotities. Wanneer een upgrade problemen veroorzaakt, is die commit uw enige weg terug, omdat er geen versienummer is om op terug te vallen.

Het installatieprogramma eindigt met het uitvoeren van dor doctor, een read-only host-check die echte gVisor-containers opstart om te bewijzen dat de runtime werkt, in plaats van te vertrouwen op een pakketlijst. Voer dit opnieuw uit wanneer de daemon niet naar behoren functioneert.

sudo dor doctor
systemctl is-active dormice

systemctl is-active dormice hoort active te tonen. Als het failed toont, bevat journalctl -u dormice -n 50 de reden; een mislukte start wordt meestal veroorzaakt door de swap- of gVisor-vereisten en niet door de daemon zelf.

Het installatieprogramma plaatst ook Caddy op de server, dus controleer wat er luistert voordat u concludeert dat het firewallwerk is voltooid.

sudo ss -lntp

De daemon bindt aan 127.0.0.1:3676 en heeft hiervoor bewust geen instelling om dit te wijzigen. Het benaderen hiervan vanaf uw laptop is een bewuste handeling; de goedkope methode is een SSH-tunnel.

ssh -L 3676:127.0.0.1:3676 root@your-server

Met de tunnel geopend is http://127.0.0.1:3676/console op uw laptop de webconsole. Meld u eenmalig aan met het token; dit wordt een httpOnly-sessiecookie, zodat het token zelf nooit wordt opgeslagen op een plek waar de pagina het kan uitlezen. De Connect-pagina daar toont copy-paste client-snippets die al naar uw eigen endpoint wijzen.

Een sandbox aanmaken en code uitvoeren

Eén bewerking creëert een sandbox: acquire. Deze is idempotent, wat betekent dat dezelfde sleutel altijd dezelfde sandbox retourneert; deze wordt indien nodig aangemaakt, geactiveerd, gestart of hersteld. Elk ander werkwoord geeft een 404-foutmelding voor een sleutel die nog niet eerder is gezien. De dor CLI heeft geen acquire-commando, dus uw eerste sandbox komt tot stand via de console of een client library.

De console-route is het snelst. Open /console via de tunnel en maak een sandbox aan met de naam my-agent. De CLI werkt daarna op deze sandbox.

sudo grep DORMICE_API_TOKEN /etc/dormice/env
export DORMICE_ENDPOINT=http://127.0.0.1:3676
export DORMICE_API_TOKEN=paste-the-value-here
dor sandbox ls
dor sandbox exec my-agent 'python3 --version'

dor sandbox ls toont een lijst van elke sandbox met de bijbehorende levenscyclusstatus; hiermee kunt u zien hoe een sandbox verandert van actief naar bevroren. dor sandbox exec voert een Python 3.12-versie uit, omdat de standaard image Ubuntu 24.04 is met Python 3.12, Node 24, git en ripgrep reeds geïnstalleerd. Een authenticatiefout betekent in plaats daarvan dat de token-regel die u heeft gekopieerd de variabelenaam bevatte.

Bestanden verplaatsen gebeurt met dor sandbox push my-agent ./script.py, wat terechtkomt op /home/user/script.py, en dor sandbox pull my-agent notes.txt haalt er een terug. De standaard bestandswerkwoorden hebben een limiet van 16 MiB per bestand, terwijl het E2B-bestandsoppervlak streamt en de schijfquota van de sandbox de enige beperking vormt.

Vernietigen is het enige werkwoord waarbij gegevens verloren gaan, en het is tevens een goed voorbeeld van de leeftijd van het project: de hoofd-README en de meegeleverde agent-skill documenteren beide dor sandbox destroy <key>, terwijl de README van het CLI-pakket dor sandbox release <key> documenteert. Voer dor sandbox --help uit op uw eigen build en vertrouw op die informatie.

Richt uw bestaande E2B-code op uw eigen server

Dit is de reden waarom dit relevant is. Het officiële e2b-pakket van npm communiceert in ongewijzigde vorm met Dormice. Voer dit uit vanaf uw laptop terwijl de SSH-tunnel openstaat, zodat er geen nieuwe services op de server luisteren.

npm init -y
npm i e2b tsx

import { Sandbox } from 'e2b';

const sbx = await Sandbox.create({
  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
  apiUrl: 'http://127.0.0.1:3676/e2b/api',
  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
});

const result = await sbx.commands.run('python3 -c "print(6 * 7)"');
console.log(result.exitCode, result.stdout);

await sbx.kill();

DORMICE_API_TOKEN=paste-the-value-here npx tsx index.ts

Een geslaagde uitvoering geeft exitcode 0 en 42 terug. De API-sleutel is uw Dormice-token met een e2b_-prefix ervoor; dit is de indeling die de compatibiliteitslaag verwacht.

De compatibiliteit is geen beperkte implementatie. Het streamen van stdout en stderr, achtergrondcommando's, een interactieve PTY, ondertekende upload- en download-URL's, directory-monitoring en een poort-proxy worden allemaal via het officiële pakket getest tegen een echte Docker- en gVisor-daemon door de end-to-end testsuite van het project. Enkele verschillen zijn van belang voordat u productieomgevingen migreert:

• Template-builds zijn niet geïmplementeerd. Een template is een Docker-image die u zelf bouwt en registreert met dor template add, waarna Sandbox.create('name') deze omzet. Een niet-geregistreerde naam geeft een 404-foutmelding in plaats van een gesimuleerd resultaat.
• Sandboxes die via het E2B-oppervlak worden aangemaakt, krijgen echte deadlines, omdat de E2B-semantiek dit vereist. Er worden nooit deadlines opgelegd aan sandboxes die via de native API worden aangemaakt.
• Een bevroren sandbox behoudt zijn processen en hervat deze op het punt waar ze waren gebleven; pauzeren en hervatten is hier dus niet de stop- en koudestart-procedure die u wellicht gewend bent.

Wat de sandbox tegenhoudt, en wat niet

gVisor onderschept de systeemaanroepen van de container in de userspace en handelt deze zelf af, waardoor de gesandboxte code niet rechtstreeks communiceert met uw host-kernel. Binnen de sandbox draait alles als een ongeprivilegieerde gebruiker, uid 1000. Deze combinatie dekt de standaardgevallen af: een gegenereerd script dat rm -rf / uitvoert, de schijf volschrijft of blijft forken totdat het systeem bezwijkt, beschadigt alleen de eigen sandbox en stopt daar.

Dit is wat het niet tegenhoudt. Elk van deze punten is uw eigen verantwoordelijkheid.

• Een sandbox heeft werkend uitgaand netwerkverkeer. Gegenereerde code kan alles downloaden wat het wil en alles wat het vindt versturen. De netwerkbeveiliging van de installer dekt twee specifieke zaken: het blokkeert containerverkeer naar de cloud-metadataservice op 169.254.0.0/16, de plek waar een cloudomgeving instantie-credentials verstrekt aan alles wat deze kan bereiken, en het schakelt container-naar-containerverkeer uit met "icc": false in de daemon.json van Docker. Niets anders wordt geblokkeerd. Lees sudo iptables -S DOCKER-USER en voeg uw eigen DROP-regels toe voor de privé-netwerkbereiken die een sandbox niet hoeft te bereiken.
• Docker plaatst zijn eigen regels vóór uw firewall, waardoor een gepubliceerde containerpoort bereikbaar kan zijn vanaf het internet, terwijl ufw aangeeft dat deze gesloten is. Lees hoe Docker poorten publiceert buiten ufw om en de basisprincipes van de ufw-firewall voor een VPS voordat u iets op deze host openstelt.
• gVisor is een userspace-kernel, geen hypervisor. Dit is een bewuste keuze, omdat bevriezen vereist dat sandboxes processen zijn, en het vereisen van KVM zou installatie op veel locaties onmogelijk maken. Als uw dreigingsmodel hardware-virtualisatie vereist, gebruik dan isolatie van het type Firecracker en accepteer de operationele kosten die daarbij horen.
• Het API-token vormt de volledige beveiligingsgrens aan de clientzijde. Iedereen die beschikt over DORMICE_API_TOKEN kan elke sandbox op de machine aanmaken, inzien en vernietigen. Geef het agent-proces zijn eigen gebruiker met minimale rechten op de VPS en behandel het token zoals u een SSH-key behandelt. De gewoontes uit veilig draaien van Claude Code op een VPS zijn hier direct van toepassing.

De daemon zelf draait als root op uw host. gVisor beschermt de host tegen de code binnen een sandbox, maar niets beschermt de host tegen de daemon of tegen degene die het token bezit. De machine waarop Dormice draait, moet daarom een machine zijn die uitsluitend die taak uitvoert. Als uw agent ook tools bereikt via MCP (model context protocol), houd die MCP-servers dan op een aparte VPS om dezelfde reden.

Hoeveel sandboxes passen er in 4 GB en 8 GB?

Twee factoren verbruiken geheugen: de basisbezetting van de host zelf en de actieve werkset van elke sandbox die op dat moment is ingeschakeld. Reserveer ongeveer 1 GB voor Ubuntu, Docker en de daemon, en deel de resterende ruimte door het werkelijke verbruik van één sandbox. Een sandbox die een Python-script uitvoert dat enkele bestanden leest, verbruikt ongeveer 200 tot 300 MiB. Een sandbox die een compiler of een volledige testsuite draait, kan meer dan een gibibyte in beslag nemen.

[
  {
    "host": "4 GB VPS",
    "active_at_512_mib": 6,
    "active_at_1_gib": 3,
    "frozen_on_16gb_swap": 16
  },
  {
    "host": "8 GB VPS",
    "active_at_512_mib": 14,
    "active_at_1_gib": 7,
    "frozen_on_16gb_swap": 16
  }
]

Een VPS met 4 GB RAM kan ongeveer 6 sandboxes tegelijkertijd actief houden als elke sandbox 512 MiB verbruikt, of 3 als elke sandbox een volledige gibibyte verbruikt. Een VPS met 8 GB RAM verhoogt dit aantal naar 14 en 7. Dit zijn bovengrenzen voor gelijktijdig werk en het betreft een rekenkundige benadering in plaats van een benchmark; houd daarom free -m in de gaten terwijl uw eigen belasting draait.

Bevroren sandboxes worden beperkt door swap in plaats van RAM, wat het kernpunt van dit ontwerp is. Een bevroren sandbox die een gibibyte in gebruik had, houdt ongeveer die hoeveelheid in de swap vast en verbruikt vrijwel geen residentieel geheugen. Het standaard swapbestand van 16 GB van het installatieprogramma biedt daarom ruimte aan ongeveer 16 van deze sandboxes. Zodra dit limiet is bereikt, moeten ze naar de gestopte status worden verplaatst, waar ze enkel nog schijfruimte in beslag nemen. Schijfruimte is op de lange termijn de werkelijke beperkende factor: elke sandbox behoudt zijn eigen bestandssysteem, en enkele tientallen agents die elk een node_modules-directory bevatten, zullen een klein volume vullen lang voordat het geheugengebruik relevant wordt.

Bevriezen, stoppen, archiveren: de knoppen voor de levenscyclus

De standaardinstellingen zijn bevriezen na 10 minuten inactiviteit, stoppen na 3 dagen en archiveren na 7 dagen wanneer archivering is geconfigureerd. Het instellen van stopAfterSeconds op null resulteert in een resident agent: deze kan bevriezen bij inactiviteit, maar voert nooit een cold start uit.

Archivering is optioneel en de daemon is hier transparant over. Stel de vier DORMICE_S3_*-variabelen in en de schijf van een gestopte sandbox wordt ingepakt met tar en zstd, verzonden naar een S3-compatibele bucket en lokaal vrijgegeven. Die bucket kan een MinIO-bucket die u zelf host op een andere machine van u zijn. Laat de variabelen oningesteld en sandboxes blijven voor altijd in de status gestopt; een beleid dat vraagt om archivering wordt geweigerd in plaats van stilletjes genegeerd. Herstelacties zijn zichtbaar in plaats van onopgemerkt: de volgende acquire-opdracht antwoordt onmiddellijk met een restoring-status en een voortgangswaarde, en schakelt over naar ready zodra de schijf terug is.

Moet u er nu al op vertrouwen?

Het korte antwoord: niet voor zaken die u niet opnieuw kunt opbouwen. De eerste commit in de repository dateert van 8 juli 2026. Op 4 augustus 2026 heeft het project 446 sterren, 37 forks, een Apache-2.0 licentie en nog geen enkele getagde release. De statusregel in de README geeft zelf aan dat er nog niets gereed is voor productie.

Deze combinatie brengt een specifiek risicoprofiel met zich mee. De code verandert onder uw handen, omdat de installer main volgt. De interface is nog in ontwikkeling; dit is precies de reden waarom het delete-werkwoord in twee verschillende bestanden in dezelfde repository twee verschillende namen heeft. Een project van vier weken oud kan bovendien zomaar stoppen, aangezien geen enkele licentieclausule iemand verplicht om door te gaan.

Wat het risico acceptabel maakt, is de E2B-compatibiliteit. Uw applicatie communiceert met een protocol waarachter een gehoste implementatie schuilgaat. Als Dormice stagneert, wijzigt u twee URL's en kunt u doorwerken. Schrijf uw agent tegen het E2B-oppervlak in plaats van tegen de native API, zodat u die uitwijkmogelijkheid behoudt. Het native @dormice/sdk-pakket staat bovendien nog niet op npm, wat betekent dat u het vanuit de repository moet bouwen. Dat is een tweede reden om voor het compatibele pad te kiezen.

Draai het op plekken waar u het verlies kunt opvangen. Bouw de host opnieuw op vanuit een script, houd het token uit elke prompt en elke commit, en haal alles wat het bewaren waard is volgens uw eigen back-upschema uit de sandboxes.

FAQ

Is Dormice klaar voor productie?

Nee, en het project geeft dit zelf ook aan. De statusregel in de README vermeldt dat er nog niets gereed is voor productie. Sinds 4 augustus 2026 is de repository ongeveer vier weken oud, zonder git-tags of releases, waardoor er geen versienummer is om vast te pinnen. Het installatieprogramma kloont de main-branch, wat betekent dat elke uitvoering u de nieuwste commit geeft. Noteer git -C /opt/dormice rev-parse HEAD na elke installatie en bewaar waardevolle gegevens buiten de sandboxes.

Hoe verschilt Dormice van het geven van een tijdelijke VM aan mijn agent?

Een tijdelijke VM is een machine met SSH die u aanmaakt voor een sessie en daarna verwijdert. Dormice is een execution API: uw programma roept acquire aan, gevolgd door exec, en ontvangt stdout en een exitcode terug, zonder dat er een shell-sessie tussen zit. De VM is geschikt voor een mens of een agent die voor langere tijd een volledige computer nodig heeft. Dormice is geschikt voor een applicatie die vele malen per dag gegenereerde code uitvoert en niet bij elke run de overhead van het opzetten en afbreken van een machine wil.

Werkt de officiële E2B SDK echt zonder codewijzigingen?

Ja, met configuratiewijzigingen. Wijs apiUrl en sandboxUrl naar /e2b/api en /e2b/envd op uw daemon en geef uw Dormice-token door met een e2b_-prefix als API-sleutel. Commando-uitvoering, PTY-sessies, bestandsoverdracht, ondertekende URL's en de poort-proxy worden allemaal gedekt door de end-to-end testsuite van het project die via het officiële pakket draait. Het bouwen van templates is het opvallende hiaat: e2b template build is niet geïmplementeerd, dus een template is een docker-image die u zelf bouwt en registreert met dor template add.

Hoeveel sandboxes passen er op een 4 GB VPS?

Ongeveer 6 tegelijkertijd actief als elke sandbox 512 MiB gebruikt, of 3 als elke sandbox een volledige gibibyte gebruikt, na reservering van ongeveer 1 GB voor het besturingssysteem, Docker en de daemon. Bevroren sandboxes worden beperkt door swap; het standaard swapbestand van 16 GB van het installatieprogramma biedt ruimte aan ongeveer 16 sandboxes die elk een gibibyte in beslag namen. Meet uw eigen gebruik met free -m onder werkelijke belasting, omdat een sandbox die een testsuite uitvoert vele malen meer verbruikt dan een sandbox die een klein script uitvoert.

Waarom moet Dormice vm.swappiness op 100 hebben staan?

Het bevriezen van een sandbox betekent dat het inactieve geheugen naar swap wordt verplaatst. gVisor houdt sandbox-geheugen vast als gedeeld geheugen, en de Linux-kernel zal gedeeld geheugen niet swappen bij de standaard swappiness-waarde. Bij de standaardinstelling wordt er dus niets vrijgemaakt en blijft de sandbox het volledige geheugen verbruiken. Het project mat 0 bytes vrijgemaakt bij de standaardinstelling en 99,5 procent vrijgemaakt bij 100. Controleer de effectieve waarde met sysctl vm.swappiness in plaats van configuratiebestanden te lezen, aangezien sommige cloud-images een waarde van 0 hanteren.