SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-10-15

How to Self-Host Dormice Agent Sandboxes on VPS

Learn how Dormice runs E2B-compatible agent sandboxes on your Linux VPS, plus install steps, code execution, isolation checks, and host sizing.

Wetin Dormice be, and wetin e no be

Dormice na self-hosted agent sandbox: na one daemon for Linux VPS wey you own, and your agent code dey call am over HTTP to run untrusted code inside isolated container. Your program go ask for sandbox by name, get the same sandbox back no matter the state wey e dey, run command inside am, then read the output. The sandbox na programmatic resource, no be machine wey you go log into.

This one different from giving agent whole computer. A throwaway VM for coding agent na box wey you go SSH into, allow agent spoil am, then delete am. Dormice dey one level down: na execution API wey your program dey call when e already get code and need safe place to run am. Use throwaway VM when whole machine na the unit of work. Use Dormice when one exec call na the unit of work, and you want run hundred of dem every day without hundred VMs.

The project call itself E2B compatible. E2B na hosted sandbox service wey client library for plenty agent frameworks already dey import. Dormice dey serve the same protocol under its own URL prefixes, so application wey dem write against official e2b package go continue run when you point am to your own box. Application code no change. Na two URLs and one API key prefix go change.

Wetin “the SQLite of agent sandboxes” mean for real

SQLite na database wey you embed instead of service wey you operate, and Dormice use that comparison directly. One daemon per machine, one SQLite file for the ledger, one TCP port, plus one small gateway wey you install beside am to serve the web console. No Kubernetes, no external database server. The daemon take exclusive lock beside its ledger, so second daemon for the same machine go refuse to start instead of quietly splitting the state. Each sandbox dey live for the machine wey create am. The README now describe fleet as one gateway plus the machines for its private network, but e still talk say if you need sandboxes wey dey move between machines, or fleet across regions, make you choose something else, and make you listen.

The second part of the idea concern cost. Hosted sandbox dey charge for every second wey e exist, so hosted sandboxes dey disposable by design. Dormice dey run for hardware wey you already dey pay for, so its sandboxes dey permanent and become cheaper the longer dem remain idle. Sandbox dey cool down one level at a time: active, then frozen, then stopped, then archived. Any acquire go bring am back from whichever level e reach.

Freezing na the part wey worth understanding, because na wetin make e affordable to keep every agent sandbox forever. These figures na the project own published figures, measured for its hardware and not your own.

ChartOne idle sandbox before and after freezing, figures published by the project
Di data wey dey behind dis chart
[
  {
    "label": "Active, holding 1 GiB",
    "resident_memory_mib": 1024,
    "wake_ms": 0
  },
  {
    "label": "Frozen",
    "resident_memory_mib": 5,
    "wake_ms": 50
  }
]

Idle sandbox wey dey hold 1024 MiB memory go drop to 5 MiB resident memory once dem freeze am, and e go wake again for about 50 ms. Processes go suspend and resume for the same place, so long-lived agent go keep its shell state and unfinished work across the freeze. Reproduce am for your own host before you plan capacity based on am.

Wetín the host need before you install

The host na Ubuntu or Debian for x86_64, and installer need root. The daemon dey keep root when e dey run because e dey do loop mounts and write cgroups.

Sandboxes dey run under Docker with gVisor (a container runtime wey put userspace kernel between the container and host kernel), and e provide the runsc runtime wey each sandbox dey use. Node 22 or newer dey run the daemon. If your system Node don already reach 22 or newer, installer go reuse am; na only when e no dey or e old pass that the installer go download its own pinned copy, verify the checksum, and unpack am under /opt.

Swap must dey available, and vm.swappiness must be 100. This no be tuning advice; na functional requirement. Freezing dey work by pushing idle sandbox memory go swap, gVisor dey hold sandbox memory as shared memory, and kernel no go swap shared memory when swappiness dey the default value. The project measure 0 bytes reclaimed for the default value and 99.5 percent reclaimed at 100. Check the value wey kernel really dey use, because some cloud images get vm.swappiness = 0 for a file wey you no go ever think to read.

sysctl vm.swappiness
swapon --show

sysctl vm.swappiness suppose print vm.swappiness = 100, and swapon --show suppose list one swapfile. If swappiness print 0, every freeze na no-op wey leave you to pay full memory cost for every idle sandbox.

Ubuntu wey Dormice dey Install

The documented install na one pipe go bash:

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

Fetch am and read am before you run am. This script dey run as root and dey rearrange your host: e go install Docker if e no dey, download gVisor and Caddy with checksum verification, create swapfile if host no get swap, write systemd units for daemon, gateway and image registry, and add firewall rules.

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 dey set swapfile size, and default na 16. For small VPS, na plenty disk to give up. --mirror cn go switch the downloads to mirrors wey mainland China fit reach. If you run installer again, e go upgrade the code and repair drift, but e no dey rotate your API token.

Code dey for /opt/dormice, configuration dey for /etc/dormice/env, plus /etc/dormice/gateway.env for gateway, sandbox data dey for /var/lib/dormice, and dormice plus dor commands dey for /usr/local/bin. Installer dey generate API token during install and write am to /etc/dormice/env with mode 600. The same value dey enter gateway file.

No tagged release dey available to install against. As of 12 October 2026, repository no get git tags and no GitHub releases, so installer clones main and you go get anything wey land that morning. So, to pin version, write down the commit wey you actually install.

git -C /opt/dormice rev-parse HEAD

Save that hash with your deploy notes, because e tells you exactly which code you dey run. Hash alone no be way back: new processes dey apply database migrations as dem boot, and upgrade docs talk say re-running older installer no go reverse migration. Before e restart anything, installer saves snapshots of both databases to /var/lib/dormice/backups/ and keeps the three most recent ones. Those snapshots na the documented way back after bad upgrade, so copy the newest one comot from the box before you upgrade again.

Installer dey end by running dor doctor. Na read-only host check wey boots real gVisor containers to prove say runtime dey work, instead of trusting package list. Run am again anytime daemon dey misbehave.

sudo dor doctor
systemctl is-active dormice

systemctl is-active dormice suppose print active. If e print failed, journalctl -u dormice -n 50 get the reason. Failed start usually na swap or gVisor prerequisite wahala, no be daemon itself.

Installer still puts Caddy for the box, so check wetin dey listen before you decide say firewall work don finish.

sudo ss -lntp

Daemon always dey bind 127.0.0.1, and by design no setting dey to change that address. Na only port fit change: DORMICE_PORT default na 3676. Gateway beside am follow the same rule for 127.0.0.1:3677, with DORMICE_GATEWAY_PORT for the port and deliberately no host setting. To reach either one from your laptop na deliberate action, and the cheap option na SSH tunnel wey forwards both ports.

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

When tunnel dey open, http://127.0.0.1:3677/console for your laptop na the web console, and gateway dey serve am. The first time you visit, paste the API token once to prove say you be the operator, then set console username and password. Signing in sets an httpOnly session cookie wey dey valid for 7 days and page JavaScript no fit read. Console no dey display the token again. The Connect page prints copy-and-paste client snippets wey don already point to your own endpoint.

Create sandbox and run code inside am

One operation dey create sandbox: acquire. E idempotent, so the same key go always return the same sandbox. E go create am, wake am, start am, or restore am as needed. Every other verb dey answer 404 for key wey e never see before. The dor CLI no get acquire verb, so your first sandbox go come from the console or client library.

Console route na the fastest one. Open /console through the tunnel and create sandbox wey dem name my-agent. The CLI go then work on am.

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 dey list every sandbox with im lifecycle state. Na so you fit monitor one as e move from active to frozen. dor sandbox exec dey print Python 3.12 version, because the stock image na Ubuntu 24.04 with Python 3.12, Node 24, git and ripgrep already installed. If authentication error show instead, e mean say the token line wey you copy include the variable name.

Files dey move with dor sandbox push my-agent ./script.py, and e dey land for /home/user/script.py. dor sandbox pull my-agent notes.txt go bring one back. The native file verbs get 16 MiB limit for each file, but the E2B file surface dey stream files and make sandbox disk quota na the only limit.

Destroying na the only verb wey dey lose data. dor sandbox destroy my-agent dey remove the sandbox and e idempotent. The main README, the bundled agent skill and the CLI package README all document am under that one name. Run dor sandbox --help for your own build anyway, because the installer dey track main and the CLI still dey grow.

Point your existing E2B code go your own box

Na this reason to care. The official e2b package from npm, as e be, dey talk to Dormice. Run this from your laptop while the SSH tunnel dey open, so nothing new go listen on the server.

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

A healthy run dey print exit code 0 and 42. The API key na your Dormice token with an e2b_ prefix for front, because na this format the compatibility layer expect.

The compatibility no be stub. The project end-to-end suite dey test streaming stdout and stderr, background commands, interactive PTY, signed upload and download URLs, directory watching, and port proxy through the official package against real Docker and gVisor daemon. Before you migrate any real workload, note these few differences:

  • Template builds no dey implemented. Template na docker image wey you build by yourself and register with dor template add, then Sandbox.create('name') go resolve am. If you use name wey no dey registered, e go return 404 instead of pretending.
  • Sandboxes wey you create through the E2B surface get real deadlines, because E2B semantics require am. Sandboxes wey you create through the native API no dey get deadline.
  • Frozen sandbox keep its processes and resume dem from where dem stop, so pause and resume for here no be the stop and cold start wey you fit don dey used to.

Wetin the sandbox dey stop, and wetin e no stop

gVisor dey intercept system calls wey container dey make for userspace and handle dem by itself, so code inside sandbox no dey talk directly to your host kernel. Inside the sandbox, commands dey run as user (uid 1000), but that account get passwordless sudo, so root inside the sandbox dey available to any code wey ask for am. No treat the uid as protection: the project talk clearly say gVisor na the security boundary, no be the uid, and sandbox wey elevate itself still no fit reach the host kernel. This handles the normal case: generated script wey runs rm -rf /, fills the disk, or forks until something dies go damage only its own sandbox and stop there.

But na wetin e no stop be this. Na your responsibility to handle each one.

  • Sandbox get working outbound network. Generated code fit download anything e like and post anything e find. The installer's network hardening handles two specific things: e drops container traffic to the cloud metadata service for 169.254.0.0/16 and 100.100.100.200, wey na the address Alibaba Cloud dey use, where cloud dey give instance credentials to anything wey fit reach am, and e turns off container-to-container traffic with "icc": false for Docker's daemon.json. Nothing else dey blocked. Read sudo iptables -S DOCKER-USER and add your own DROP rules for the private ranges wey sandbox no get business reaching.
  • Docker dey insert its own rules before your firewall rules, so published container port fit answer from internet while ufw dey insist say e dey closed. Read how Docker dey publish ports past ufw and the ufw firewall basics for a VPS before you expose anything for this host.
  • gVisor na userspace kernel, no be hypervisor. Na deliberate trade-off be this, because freezing requires sandboxes to be processes, and requiring KVM go stop the thing from installing anywhere. If your threat model require hardware virtualisation, use Firecracker-class isolation and accept the operational cost wey come with am.
  • API token na the complete security boundary for the client side. Anything wey hold DORMICE_API_TOKEN fit create, read, and destroy every sandbox for the machine. Give the agent process its own least privilege user on the VPS and treat the token the same way you dey treat an SSH key. The habits from running Claude Code safely on a VPS apply directly.

The daemon itself dey run as root for your host. gVisor dey protect the host from code inside sandbox, and nothing dey protect the host from the daemon or from anybody wey hold its token. So the machine wey dey run Dormice suppose be machine wey dey do only that work. If your agent also dey reach tools through MCP (model context protocol), keep those MCP servers for a separate VPS for the same reason.

Sandbox wey 4 GB and 8 GB fit hold?

Two things dey use memory: host baseline by itself, and working set of every sandbox wey dey awake. Keep about 1 GB for Ubuntu, Docker and daemon, then divide wetin remain by wetin one of your sandboxes really dey use. Sandbox wey dey run Python script wey dey read small number of files fit dey around 200 to 300 MiB. One wey dey run compiler or complete test suite fit pass one gibibyte.

ChartConcurrent sandboxes by host RAM, arithmetic after a 1 GB host reserve
Di data wey dey behind dis chart
[
  {
    "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
  }
]

4 GB VPS fit keep about 6 sandboxes awake at once if each one dey use 512 MiB, or 3 if each one dey use complete gibibyte. 8 GB VPS increase am to 14 and 7. These na limits for concurrent work, and na calculation dem be, no be benchmark, so monitor free -m while your own load dey run.

Swap dey limit frozen sandboxes instead of RAM, and na the main reason for this design. Frozen sandbox wey dey hold one gibibyte go keep roughly that amount for swap and almost nothing for resident memory, so installer's default 16 GB swapfile fit park about 16 of dem. After that, dem need reach stopped rung, where na disk only dem dey cost. Disk na the real long-term limit here: every sandbox dey keep its filesystem, and few dozen agents wey each carry node_modules directory go fill small volume long before memory become important.

Freeze, stop, archive: settings for lifecycle

Default na freeze after 10 minutes wey e idle, stop after 3 days, and archive after 7 days when archive dey configured. If you set stopAfterSeconds to null, you get resident agent: e fit freeze when idle, but e no go ever do cold start.

Archiving na optional, and daemon dey clear about am. Configure S3-compatible store for the console settings page. The four DORMICE_S3_* variables still dey, but dem only serve as seeds for the gateway first boot. After that, stopped sandbox disk dey pack with tar and zstd, send go the bucket, then free the local copy. That bucket fit be MinIO bucket wey you host yourself for another machine wey belong to you. If you no configure the store, sandboxes go remain stopped forever. Policy wey ask to archive go fail instead of dem quietly ignoring am. Restore no dey happen silently. The next acquire go answer immediately with restoring status and progress value. E go change to ready after the disk don return.

You suppose depend on am now?

Straight answer: no be for anything wey you no fit rebuild. Dem create the repository for 8 July 2026. As of 12 October 2026, e get 1,509 stars, 109 forks, Apache-2.0 licence, and e no get any tagged release at all. The status line for the README sef talk say nothing wey dey inside dey ready for production.

That combination get im own kind of risk. The code dey change under you, because the installer dey track main. The interface still dey settle: the docs now describe one gateway wey dey front of the daemon, e get im own port, im own configuration file, and im own database. And project wey just reach three months fit just stop, because no licence clause force anybody to continue the work.

Wetin make the risk manageable na the E2B compatibility. Your application dey talk to one protocol wey get hosted implementation behind am, so if Dormice stall, you go just change two URLs and continue your work. Write your agent against the E2B surface instead of the native API so you go fit keep that exit. The native @dormice/sdk package no dey npm yet, so if you wan use am, you must build am from the repository, and that one na second reason why you suppose start with the compatible path.

Run am for where you no go mind if you lose am. Rebuild the host from script, keep the token comot from every prompt and every commit, and pull anything wey worth keeping out of the sandboxes based on your own backup schedule.

FAQ

Dormice don ready for production?

No, and the project talk am so itself. The status line for the README say say nothing there don ready for production yet. As of 12 October 2026, the repository dey about three months old, with no git tags and no releases. So, no version number dey wey you fit pin. The installer clones the main branch, meaning say every run go give you the newest commit. Record git -C /opt/dormice rev-parse HEAD after every install. Keep copy of the database snapshots wey the installer writes to /var/lib/dormice/backups/. Keep anything valuable outside the sandboxes.

How Dormice different from giving my agent disposable VM?

Disposable VM na machine with SSH wey you create for one session, then delete afterwards. Dormice na execution API: your program go call acquire, then exec, and receive stdout plus exit code, without shell session for the middle. VM fit human or agent wey need whole computer for some time. Dormice fit application wey dey run generated code many times every day and no want machine-level setup and teardown for every run.

Official E2B SDK really dey work without code changes?

Yes, but you need change configuration. Point apiUrl and sandboxUrl to /e2b/api and /e2b/envd for your daemon. Pass your Dormice token with e2b_ prefix as the API key. Command execution, PTY sessions, file transfer, signed URLs, and the port proxy all dey covered by the project's end-to-end suite through the official package. Template building na the main gap: e2b template build never implement, so template na docker image wey you build and register with dor template add.

How many sandboxes fit run for 4 GB VPS?

About 6 fit dey awake at the same time if each sandbox use 512 MiB. Or 3 if each one use full gibibyte. This na after you reserve roughly 1 GB for the operating system, Docker, and the daemon. Frozen sandboxes depend on swap instead. So, the installer's default 16 GB swapfile fit park around 16 sandboxes wey each hold one gibibyte. Measure your own with free -m under real load, because sandbox wey dey run test suite fit use several times the memory wey sandbox wey dey run small script use.

Why Dormice need vm.swappiness set to 100?

To freeze sandbox mean say system go push its idle memory go swap. gVisor dey hold sandbox memory as shared memory. Linux kernel no go swap shared memory when swappiness dey the default value. So, freeze for the default value no reclaim anything, and the sandbox go still use full memory. The project measure 0 bytes reclaimed for the default value and 99.5 percent reclaimed at 100. Check the effective value with sysctl vm.swappiness instead of reading config files, because some cloud images ship with value of 0.

Dis article help you?