Cómo autohospedar Dormice para sandboxes de agentes
Instale Dormice en un VPS Linux, ejecute código no confiable con una API compatible con E2B, compruebe el aislamiento y calcule los recursos del host.
Qué es Dormice y qué no es
Dormice es un sandbox de agentes autohospedado: un daemon en un VPS Linux que usted administra. El código de su agente lo invoca mediante HTTP para ejecutar código no confiable dentro de un contenedor aislado. El programa solicita un sandbox por nombre, obtiene el mismo sandbox independientemente de su estado anterior, ejecuta un comando dentro de él y lee la salida. El sandbox es un recurso programático, no una máquina a la que se accede mediante login.
Esto es distinto de proporcionar a un agente un equipo completo. Una VM desechable para un agente de programación es un sistema al que se accede mediante SSH, se deja que el agente lo modifique o dañe y después se elimina. Dormice se sitúa un nivel por debajo: es la API de ejecución que el programa invoca cuando ya dispone del código y necesita un entorno seguro donde ejecutarlo. Use la VM desechable cuando la unidad de trabajo sea una máquina completa. Use Dormice cuando la unidad de trabajo sea una sola llamada exec y quiera realizar cien al día sin crear cien VM.
El proyecto se declara compatible con E2B. E2B es un servicio de sandbox alojado cuya biblioteca cliente ya importan muchos frameworks de agentes. Dormice proporciona el mismo protocolo bajo sus propios prefijos de URL. Por tanto, una aplicación escrita para el paquete oficial e2b sigue funcionando cuando se configura para usar su propio servidor. El código de la aplicación no cambia. Sólo cambian dos URL y un prefijo de clave de API.
Qué significa en la práctica «el SQLite de los sandboxes de agentes»
SQLite es una base de datos que se integra en lugar de un servicio que se administra, y Dormice adopta directamente esa comparación. Un daemon por máquina, un archivo SQLite para su registro, un puerto TCP y una pequeña pasarela instalada junto a él que sirve la consola web. No hay Kubernetes ni un servidor de base de datos externo. El daemon adquiere un bloqueo exclusivo junto a su registro, por lo que un segundo daemon en la misma máquina se niega a iniciar en lugar de dividir el estado silenciosamente. Cada sandbox permanece en la máquina en la que se creó. El README describe ahora una flota como una pasarela más las máquinas de su red privada, pero también indica que, si necesita sandboxes que se muevan entre máquinas o una flota distribuida entre regiones, debe elegir otra opción y prestar atención.
La segunda parte de la idea se refiere al coste. Un sandbox alojado se factura por cada segundo que existe, por lo que los sandboxes alojados son desechables por diseño. Dormice se ejecuta en hardware que ya paga, por lo que sus sandboxes son permanentes y resultan más baratos cuanto más tiempo permanecen inactivos. Un sandbox se enfría un nivel cada vez: activo, después congelado, después detenido y, por último, archivado. Cualquier acquire lo recupera desde el nivel en el que se encuentre.
La congelación es la parte que conviene entender, porque permite conservar para siempre el sandbox de cada agente a un coste asequible. Estas son las cifras publicadas por el propio proyecto, medidas en su hardware y no en el suyo.
Los datos de este gráfico
[
{
"label": "Active, holding 1 GiB",
"resident_memory_mib": 1024,
"wake_ms": 0
},
{
"label": "Frozen",
"resident_memory_mib": 5,
"wake_ms": 50
}
]Un sandbox inactivo que ocupa 1024 MiB de memoria pasa a ocupar 5 MiB de memoria residente cuando se congela y vuelve en unos 50 ms. Los procesos se suspenden y reanudan en el mismo estado, por lo que un agente de larga duración conserva el estado de su shell y el trabajo a medio terminar durante la congelación. Reprodúzcalo en su propio host antes de planificar la capacidad basándose en estas cifras.
Requisitos del host antes de la instalación
El host debe ejecutar Ubuntu o Debian en x86_64, y el instalador necesita root. El daemon mantiene root durante la ejecución porque realiza montajes loop y escribe en cgroups.
Los sandboxes se ejecutan en Docker con gVisor (un runtime de contenedores que coloca un kernel de espacio de usuario entre el contenedor y el kernel del host), que proporciona el runtime runsc que usa cada sandbox. El daemon se ejecuta con Node 22 o posterior. Si el Node del sistema ya es 22 o posterior, el instalador lo reutiliza. Sólo cuando falta o es anterior, el instalador descarga su propia copia fijada, verifica su checksum y la descomprime en /opt.
Debe existir swap, y vm.swappiness debe ser 100. No es una recomendación de ajuste, sino un requisito funcional. El congelamiento funciona trasladando a swap la memoria de un sandbox inactivo. gVisor mantiene la memoria del sandbox como memoria compartida, y el kernel no intercambia memoria compartida con el valor predeterminado de swappiness. El proyecto midió 0 bytes recuperados con el valor predeterminado y un 99.5 por ciento con 100. Compruebe el valor que realmente usa el kernel, porque algunas imágenes cloud establecen vm.swappiness = 0 en un archivo que normalmente no se revisa.
sysctl vm.swappiness
swapon --showsysctl vm.swappiness debería mostrar vm.swappiness = 100, y swapon --show debería mostrar un swapfile. Si swappiness muestra 0, cada congelamiento no hará nada y tendrá que pagar el coste de memoria completo de cada sandbox inactivo.
Instalar Dormice en Ubuntu
La instalación documentada consiste en ejecutar un pipe hacia bash:
curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bashDescárguelo y léalo antes de ejecutarlo. Este script se ejecuta como root y modifica el host: instala Docker si no está instalado, descarga gVisor y Caddy con verificación de sumas de comprobación, crea un archivo de swap si el host no tiene swap, escribe unidades de systemd para el daemon, el gateway y un registro de imágenes, y añade reglas de firewall.
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 establece el tamaño del archivo de swap y su valor predeterminado es 16, una cantidad considerable de disco en un VPS pequeño. --mirror cn cambia las descargas a mirrors accesibles desde China continental. Si vuelve a ejecutar el instalador, actualiza el código y corrige las diferencias de configuración, pero nunca rota el token de API.
El código se instala en /opt/dormice, la configuración en /etc/dormice/env (y /etc/dormice/gateway.env para el gateway), los datos del sandbox en /var/lib/dormice, y los comandos dormice y dor en /usr/local/bin. El instalador genera el token de API durante la instalación y lo escribe en /etc/dormice/env con el modo 600. El mismo valor se escribe en el archivo del gateway.
No hay una release etiquetada contra la que instalar. Al 12 de octubre de 2026, el repositorio no tiene tags de git ni releases de GitHub. Por tanto, el instalador clona main y obtiene todo lo que se haya incorporado esa mañana. Fijar una versión significa anotar el commit que se instaló realmente.
git -C /opt/dormice rev-parse HEADGuarde ese hash con las notas del despliegue. Indica exactamente qué código está ejecutando. No permite volver atrás por sí solo: los procesos nuevos aplican migraciones de base de datos durante el arranque, y la documentación de actualización indica que volver a ejecutar un instalador antiguo no revierte una migración. Antes de reiniciar cualquier proceso, el instalador guarda snapshots de ambas bases de datos en /var/lib/dormice/backups/ y conserva los tres más recientes. Esos snapshots son el método documentado para recuperar el sistema después de una actualización defectuosa. Por tanto, copie el más reciente fuera del servidor antes de volver a actualizar.
El instalador termina ejecutando dor doctor, una comprobación de solo lectura del host que arranca contenedores gVisor reales para demostrar que el runtime funciona, en lugar de confiar en una lista de paquetes. Vuelva a ejecutarlo cuando el daemon presente un comportamiento anómalo.
sudo dor doctor
systemctl is-active dormicesystemctl is-active dormice debería mostrar active. Si muestra failed, journalctl -u dormice -n 50 contiene el motivo. Un arranque fallido suele deberse al requisito de swap o de gVisor, y no al daemon.
El instalador también instala Caddy en el servidor. Por tanto, compruebe qué procesos están escuchando antes de dar por terminado el trabajo del firewall.
sudo ss -lntpEl daemon siempre se enlaza a 127.0.0.1. Por diseño, no existe ninguna opción para cambiar esa dirección. Sólo cambia el puerto: DORMICE_PORT tiene 3676 como valor predeterminado. El gateway situado junto a él sigue la misma regla en 127.0.0.1:3677, con DORMICE_GATEWAY_PORT para el puerto y sin ninguna opción de host. Acceder a cualquiera de los dos desde el portátil requiere una acción deliberada. La opción sencilla es un túnel SSH que reenvíe ambos puertos.
ssh -L 3676:127.0.0.1:3676 -L 3677:127.0.0.1:3677 root@your-serverCon el túnel abierto, http://127.0.0.1:3677/console en el portátil es la consola web, servida por el gateway. En la primera visita, demuestre que es el operador pegando una vez el token de API. Después, establezca un nombre de usuario y una contraseña para la consola. El inicio de sesión establece una cookie de sesión httpOnly válida durante 7 días, que el JavaScript de la página no puede leer. La consola nunca vuelve a mostrar el token. La página Connect muestra fragmentos de cliente listos para copiar y pegar, ya configurados para apuntar a su propio endpoint.
Crear un entorno aislado y ejecutar código en él
Una operación crea un entorno aislado: acquire. Es idempotente, por lo que la misma clave siempre devuelve el mismo entorno aislado. Lo crea, lo reactiva, lo inicia o lo restaura según sea necesario. Todos los demás verbos responden con 404 para una clave que nunca han visto. El CLI de dor no tiene un verbo acquire, por lo que el primer entorno aislado se obtiene desde la consola o desde una biblioteca cliente.
La ruta de la consola es la más rápida. Abra /console mediante el túnel y cree un entorno aislado llamado my-agent. Después, el CLI puede trabajar con él.
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 muestra cada entorno aislado con su estado del ciclo de vida. Así puede supervisar cómo uno pasa de activo a congelado. dor sandbox exec muestra una versión de Python 3.12, porque la imagen estándar es Ubuntu 24.04 e incluye Python 3.12, Node 24, git y ripgrep. Un error de autenticación significa, en cambio, que la línea del token copiada incluía el nombre de la variable.
Los archivos se transfieren con dor sandbox push my-agent ./script.py, que los coloca en /home/user/script.py, y dor sandbox pull my-agent notes.txt recupera uno. Los verbos nativos para archivos limitan cada archivo a 16 MiB, mientras que la interfaz de archivos de E2B transmite los datos y permite que la cuota de disco del entorno aislado sea el único límite.
La destrucción es el único verbo que provoca pérdida de datos. dor sandbox destroy my-agent elimina el entorno aislado y es idempotente. El README principal, la capacidad del agente incluida y el README del paquete CLI lo documentan con ese mismo nombre. Ejecute de todos modos dor sandbox --help en su propia compilación, porque el instalador sigue main y el CLI continúa incorporando funciones.
Dirija su código E2B existente a su propio servidor
Este es el motivo para usarlo. El paquete oficial e2b de npm, sin modificar, se comunica con Dormice. Ejecútelo desde su portátil con el túnel SSH abierto, para que no se abra ningún puerto nuevo en el servidor.
npm init -y
npm i e2b tsximport { 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.tsUna ejecución correcta muestra el código de salida 0 y 42. La clave de API es su token de Dormice con el prefijo e2b_ delante, que es el formato que espera la capa de compatibilidad.
La compatibilidad no es un simple stub. La salida estándar y de error en streaming, los comandos en segundo plano, una PTY interactiva, las URL firmadas de carga y descarga, la supervisión de directorios y un proxy de puertos se prueban mediante el paquete oficial contra daemons reales de Docker y gVisor en la suite de extremo a extremo del proyecto. Antes de migrar algo real, tenga en cuenta varias diferencias:
- Las compilaciones de plantillas no están implementadas. Una plantilla es una imagen de Docker que debe compilar usted mismo y registrar con
dor template add, ySandbox.create('name')la resuelve. Un nombre no registrado devuelve 404 en lugar de simular que existe. - Los sandboxes creados mediante la interfaz de E2B tienen plazos reales, porque la semántica de E2B los requiere. Los sandboxes creados mediante la API nativa nunca tienen plazos impuestos.
- Un sandbox congelado conserva sus procesos y los reanuda en el punto en que estaban. Por tanto, la pausa y reanudación no equivalen aquí a detenerlo y arrancarlo desde cero, como puede ocurrir en otros entornos.
Qué detiene el sandbox y qué no
gVisor intercepta las llamadas al sistema del contenedor en el espacio de usuario y las gestiona por su cuenta. Por tanto, el código dentro del sandbox no se comunica directamente con el kernel del host. Dentro del sandbox, los comandos se ejecutan como user (uid 1000), pero esa cuenta tiene sudo sin contraseña. Por tanto, cualquier código que lo solicite puede obtener root dentro del sandbox. No interprete el uid como una protección: el proyecto indica claramente que el límite de seguridad es gVisor, no el uid, y que un sandbox que eleva sus privilegios sigue sin poder acceder al kernel del host. Esto cubre el caso normal: un script generado que ejecuta rm -rf /, llena el disco o crea procesos hasta provocar un fallo daña su propio sandbox y no sale de él.
Esto es lo que no detiene. Usted debe encargarse de cada uno de estos puntos.
- El sandbox tiene acceso de salida a la red. El código generado puede descargar lo que quiera y enviar cualquier información que encuentre. El refuerzo de red del instalador cubre dos aspectos concretos: bloquea el tráfico de los contenedores hacia el servicio de metadatos de la nube en 169.254.0.0/16 y en 100.100.100.200, la dirección que usa Alibaba Cloud, desde donde la nube entrega las credenciales de la instancia a cualquier proceso que pueda acceder a ella; además, desactiva el tráfico entre contenedores mediante
"icc": falseendaemon.jsonde Docker. No se bloquea nada más. Leasudo iptables -S DOCKER-USERy añada sus propias reglas DROP para los rangos privados a los que un sandbox no debería poder acceder. - Docker inserta sus propias reglas antes que las de su firewall. Por eso, un puerto publicado por un contenedor puede responder desde Internet aunque ufw indique que está cerrado. Lea cómo Docker publica puertos ignorando ufw y los conceptos básicos del firewall ufw para un VPS antes de exponer cualquier servicio en este host.
- gVisor es un kernel en el espacio de usuario, no un hipervisor. Es una decisión deliberada: el aislamiento requiere que los sandboxes sean procesos, y exigir KVM impediría instalarlo en muchos entornos. Si su modelo de amenazas exige virtualización por hardware, use un aislamiento de la clase de Firecracker y asuma el coste operativo correspondiente.
- El token de API es todo el límite de seguridad en el lado del cliente. Cualquiera que tenga
DORMICE_API_TOKENpuede crear, leer y destruir todos los sandboxes de la máquina. Asigne al proceso del agente su propio usuario con privilegios mínimos en el VPS y trate el token como trataría una clave SSH. Las prácticas de ejecutar Claude Code de forma segura en un VPS se aplican directamente.
El daemon se ejecuta como root en el host. gVisor protege el host frente al código que se ejecuta dentro de un sandbox, pero nada protege el host frente al daemon ni frente a quien tenga su token. Por tanto, la máquina que ejecuta Dormice debe dedicarse exclusivamente a esa tarea. Si su agente también accede a herramientas mediante MCP (model context protocol), mantenga esos servidores MCP en un VPS independiente por el mismo motivo.
¿Cuántos sandboxes caben en 4 GB y 8 GB?
Dos elementos consumen memoria: la base del propio host y el conjunto de trabajo de cada sandbox que está activo. Reserve aproximadamente 1 GB para Ubuntu, Docker y el daemon. Después, divida la memoria restante por el consumo real de uno de sus sandboxes. Un sandbox que ejecuta un script de Python y lee algunos archivos suele consumir entre 200 y 300 MiB. Uno que ejecuta un compilador o una suite de pruebas completa puede superar 1 GiB.
Los datos de este gráfico
[
{
"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
}
]Un VPS de 4 GB admite aproximadamente 6 sandboxes activos a la vez si cada uno usa 512 MiB, o 3 si cada uno usa 1 GiB completo. En un VPS de 8 GB, esas cifras aumentan a 14 y 7. Son límites para el trabajo simultáneo, no resultados de una prueba de rendimiento. Por tanto, supervise free -m mientras se ejecuta su propia carga.
Los sandboxes congelados están limitados por el espacio de swap y no por la RAM. Ese es el objetivo del diseño. Un sandbox congelado que ocupaba 1 GiB conserva aproximadamente esa cantidad en swap y casi nada en memoria residente. Por eso, el archivo de swap predeterminado de 16 GB del instalador puede mantener aproximadamente 16 sandboxes congelados. Después, deben pasar al estado detenido, en el que sólo consumen espacio en disco. El disco es el límite real a largo plazo: cada sandbox conserva su sistema de archivos y unas pocas docenas de agentes, cada uno con un directorio node_modules, pueden llenar un volumen pequeño mucho antes de que la memoria sea un problema.
Congelar, detener, archivar: controles del ciclo de vida
Los valores predeterminados son congelar después de 10 minutos de inactividad, detener después de 3 días y archivar después de 7 días cuando el archivado está configurado. Establecer stopAfterSeconds en null proporciona un agente residente: puede congelarse cuando está inactivo y nunca inicia en frío.
El archivado es opcional y el daemon lo indica claramente. Configure un almacenamiento compatible con S3 en la página de configuración de la consola (las cuatro variables DORMICE_S3_* siguen existiendo, pero sólo se utilizan como valores iniciales para el primer arranque del gateway). El disco de un sandbox detenido se empaqueta con tar y zstd, se envía al bucket y se libera localmente. Ese bucket puede ser un bucket de MinIO que aloje usted mismo en otra máquina suya. Si deja el almacenamiento sin configurar, los sandboxes permanecen detenidos indefinidamente, y una política que solicite archivarlos se rechaza en lugar de ignorarse silenciosamente. Las restauraciones son visibles: la siguiente adquisición responde inmediatamente con un estado de restauración y un valor de progreso, y después cambia a ready cuando el disco vuelve a estar disponible.
¿Deberías depender ya de ello?
Respuesta directa: no para nada que no puedas reconstruir. El repositorio se creó el 8 de julio de 2026. A fecha del 12 de octubre de 2026, muestra 1,509 estrellas, 109 bifurcaciones, una licencia Apache-2.0 y ninguna versión etiquetada. La propia línea de estado del README indica que nada está listo para producción.
Esa combinación presenta un riesgo concreto. El código cambia, porque el instalador sigue main. La interfaz aún se está definiendo: la documentación ahora describe una puerta de enlace delante del daemon, con su propio puerto, su propio archivo de configuración y su propia base de datos. Además, un proyecto de unos tres meses puede detenerse sin más, ya que ninguna cláusula de la licencia obliga a nadie a continuar.
Lo que hace que el riesgo sea asumible es la compatibilidad con E2B. Tu aplicación se comunica con un protocolo que tiene una implementación alojada detrás, así que, si Dormice se detiene, cambias 2 URL y sigues trabajando. Escribe tu agente contra la interfaz E2B en lugar de la API nativa y conservarás esa salida. El paquete nativo @dormice/sdk tampoco está todavía en npm, por lo que usarlo implica compilarlo desde el repositorio. Esta es otra razón para empezar con la ruta compatible.
Ejecútalo donde puedas permitirte perderlo. Reconstruye el host a partir de un script, mantén el token fuera de todas las solicitudes y de todos los commits, y extrae de los sandboxes cualquier dato que quieras conservar según tu propio calendario de copias de seguridad.
FAQ
¿Está Dormice listo para producción?
No, y el propio proyecto lo indica. La línea de estado del README indica que nada de lo que contiene está listo para producción todavía. Además, al 12 de octubre de 2026, el repositorio tiene aproximadamente tres meses, no contiene etiquetas de Git ni releases y, por tanto, no hay un número de versión que fijar. El instalador clona la rama main, por lo que cada ejecución obtiene el commit más reciente. Registre git -C /opt/dormice rev-parse HEAD después de cada instalación, conserve una copia de las instantáneas de la base de datos que el instalador escribe en /var/lib/dormice/backups/ y mantenga cualquier dato importante fuera de los sandboxes.
¿En qué se diferencia Dormice de proporcionar a mi agente una VM desechable?
Una VM desechable es una máquina con SSH que crea para una sesión y elimina después. Dormice es una API de ejecución: el programa llama a acquire y después a exec, y recibe stdout y un código de salida, sin una sesión de shell intermedia. La VM es adecuada para una persona o un agente que necesita un equipo completo durante un tiempo. Dormice es adecuado para una aplicación que ejecuta código generado muchas veces al día y no quiere asumir la configuración y la eliminación de una máquina en cada ejecución.
¿El SDK oficial de E2B funciona realmente sin cambios en el código?
Sí, con cambios de configuración. Configure apiUrl y sandboxUrl para que apunten a /e2b/api y /e2b/envd en su daemon, y pase el token de Dormice con un prefijo e2b_ como clave de API. La ejecución de comandos, las sesiones PTY, la transferencia de archivos, las URL firmadas y el proxy de puertos están cubiertos por la suite de extremo a extremo del proyecto mediante el paquete oficial. La creación de plantillas es la principal limitación: e2b template build no está implementado, por lo que una plantilla es una imagen de Docker que se crea y registra con dor template add.
¿Cuántos sandboxes caben en una VPS de 4 GB?
Aproximadamente 6 activos al mismo tiempo si cada sandbox usa 512 MiB, o 3 si cada uno usa un gibibyte completo, después de reservar aproximadamente 1 GB para el sistema operativo, Docker y el daemon. Los sandboxes congelados están limitados por el espacio de swap. Por tanto, el archivo de swap predeterminado de 16 GB del instalador permite mantener aproximadamente 16 sandboxes que hayan usado un gibibyte cada uno. Mida su propio entorno con free -m bajo carga real, porque un sandbox que ejecuta una suite de pruebas usa varias veces más recursos que uno que ejecuta un script pequeño.
¿Por qué Dormice necesita establecer vm.swappiness en 100?
Congelar un sandbox significa mover su memoria inactiva al espacio de swap. gVisor mantiene la memoria del sandbox como memoria compartida, y el kernel de Linux no intercambia la memoria compartida con el valor predeterminado de swappiness. Por tanto, con el valor predeterminado, una congelación no recupera memoria y el sandbox sigue consumiendo toda la memoria. El proyecto midió 0 bytes recuperados con el valor predeterminado y un 99.5 por ciento con el valor 100. Compruebe el valor efectivo con sysctl vm.swappiness en lugar de leer los archivos de configuración, porque algunas imágenes de proveedores cloud incluyen un valor de 0.