SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-10-22

Como alojar o Dormice para sandboxes de agentes

Instale o Dormice num VPS Linux, execute codigo nao confiavel com uma API compativel com E2B, verifique o isolamento e calcule o dimensionamento do host.

O que é o Dormice e o que não é

O Dormice é um sandbox de agentes autoalojado: um daemon num VPS Linux que lhe pertence, ao qual o código do seu agente faz chamadas HTTP para executar código não confiável dentro de um contentor isolado. O seu programa pede um sandbox pelo nome, recebe o mesmo sandbox independentemente do estado em que estava, executa um comando dentro dele e lê o resultado. O sandbox é um recurso programático, não uma máquina na qual inicia sessão.

Isto é diferente de dar ao agente um computador inteiro. Uma VM descartável para um agente de programação é uma máquina à qual se liga por SSH, deixa o agente danificar e depois elimina. O Dormice fica um nível abaixo: é a API de execução que o seu programa chama quando já tem código e precisa de um local seguro para o executar. Use a VM descartável quando uma máquina inteira for a unidade de trabalho. Use o Dormice quando uma única chamada exec for a unidade de trabalho e quiser fazer cem por dia sem cem VMs.

O projeto declara compatibilidade com E2B. O E2B é um serviço de sandbox alojado cuja biblioteca cliente muitos frameworks de agentes já importam. O Dormice disponibiliza o mesmo protocolo nos seus próprios prefixos de URL, por isso uma aplicação escrita para o pacote e2b oficial continua a funcionar quando aponta para a sua própria máquina. O código da aplicação não muda. Apenas mudam 2 URLs e 1 prefixo de chave de API.

O que significa, na prática, "o SQLite dos sandboxes de agentes"

O SQLite é uma base de dados que integra, em vez de um serviço que tem de operar, e o Dormice usa diretamente essa comparação. Existe um daemon por máquina, um ficheiro SQLite para o seu ledger, uma porta TCP e um pequeno gateway instalado ao lado, que disponibiliza a consola Web. Não há Kubernetes nem um servidor de base de dados externo. O daemon obtém um bloqueio exclusivo junto do seu ledger, pelo que um segundo daemon na mesma máquina recusa arrancar em vez de dividir o estado silenciosamente. Cada sandbox permanece na máquina onde foi criado. O README descreve agora uma fleet como um gateway mais as máquinas na sua rede privada, mas continua a indicar que, se precisar de sandboxes que se movam entre máquinas ou de uma fleet entre regiões, deve escolher outra solução e deve avaliá-la com atenção.

A segunda parte da ideia está relacionada com o custo. Um sandbox alojado é faturado por cada segundo em que existe, pelo que os sandboxes alojados são descartáveis por conceção. O Dormice é executado em hardware que já paga, pelo que os seus sandboxes são permanentes e ficam mais baratos quanto mais tempo permanecem parados. Um sandbox arrefece um nível de cada vez: ativo, depois congelado, depois parado e, por fim, arquivado. Qualquer operação acquire recupera-o a partir do nível em que ficou.

O congelamento é a parte que vale a pena compreender, porque é o que torna acessível manter permanentemente o sandbox de cada agente. Estes são os valores publicados pelo próprio projeto, medidos no respetivo hardware e não no seu.

GráficoOne idle sandbox before and after freezing, figures published by the project
Os dados por trás deste gráfico
[
  {
    "label": "Active, holding 1 GiB",
    "resident_memory_mib": 1024,
    "wake_ms": 0
  },
  {
    "label": "Frozen",
    "resident_memory_mib": 5,
    "wake_ms": 50
  }
]

Um sandbox inativo que utiliza 1024 MiB de memória passa a utilizar 5 MiB de memória residente depois de ser congelado e volta a ficar disponível em cerca de 50 ms. Os processos são suspensos e retomados no mesmo local, pelo que um agente de longa duração mantém o estado da shell e o trabalho incompleto durante o congelamento. Reproduza este comportamento no seu próprio host antes de planear a capacidade com base nele.

O que o host precisa antes da instalação

O host deve executar Ubuntu ou Debian em x86_64, e o instalador precisa de root. O daemon mantém o root durante a execução porque cria loop mounts e escreve em cgroups.

As sandboxes são executadas no Docker com gVisor (um runtime de contentores que coloca um kernel em userspace entre o contentor e o kernel do host), que fornece o runtime runsc usado por cada sandbox. O daemon é executado no Node 22 ou posterior. Se o Node do sistema já for 22 ou posterior, o instalador reutiliza-o. Só quando está ausente ou é mais antigo é que o instalador descarrega a sua própria cópia fixada, verifica o checksum e descompacta-a em /opt.

Tem de existir swap, e vm.swappiness tem de ser 100. Isto não é uma recomendação de afinação. É um requisito funcional. O congelamento funciona transferindo a memória de uma sandbox inativa para a swap. O gVisor mantém a memória da sandbox como memória partilhada, e o kernel não troca memória partilhada para a swap com o valor predefinido de swappiness. O projeto mediu 0 bytes recuperados com o valor predefinido e 99.5 por cento recuperados com 100. Verifique o valor que o kernel está realmente a usar, porque algumas imagens cloud definem vm.swappiness = 0 num ficheiro que normalmente não consultaria.

sysctl vm.swappiness
swapon --show

sysctl vm.swappiness deve mostrar vm.swappiness = 100, e swapon --show deve listar um swapfile. Se swappiness mostrar 0, todos os congelamentos serão uma operação sem efeito e continuará a pagar o custo total de memória por cada sandbox inativa.

Instalar o Dormice no Ubuntu

A instalação documentada consiste em executar um pipe para bash:

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

Transfira o script e leia-o antes de o executar. Este script é executado como root e altera o sistema anfitrião: instala o Docker se este não estiver presente, transfere o gVisor e o Caddy com verificação de checksum, cria um ficheiro de swap se o anfitrião não tiver swap, escreve unidades systemd para o daemon, o gateway e um registo de imagens, e adiciona regras 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 define o tamanho do ficheiro de swap e, por predefinição, usa 16, o que representa muito espaço em disco num VPS pequeno. --mirror cn muda as transferências para mirrors acessíveis a partir da China continental. Executar novamente o instalador atualiza o código e corrige divergências, mas nunca roda o seu token da API.

O código fica em /opt/dormice, a configuração em /etc/dormice/env (e em /etc/dormice/gateway.env para o gateway), os dados da sandbox em /var/lib/dormice, e os comandos dormice e dor em /usr/local/bin. O instalador gera o token da API durante a instalação e escreve-o em /etc/dormice/env com o modo 600. O mesmo valor é escrito no ficheiro do gateway.

Não existe uma release identificada por tag para instalar. Em 12 October 2026, o repositório não tinha tags git nem releases no GitHub. Por isso, o instalador clona main e obtém o código que tiver sido publicado nessa manhã. Fixar uma versão significa, portanto, registar o commit que foi realmente instalado.

git -C /opt/dormice rev-parse HEAD

Guarde esse hash juntamente com as notas da implementação. Ele indica exatamente que código está a executar. Por si só, não permite regressar à versão anterior: os novos processos aplicam migrações à base de dados durante o arranque, e a documentação de atualização indica que uma migração não é revertida ao executar novamente um instalador mais antigo. Antes de reiniciar qualquer componente, o instalador guarda snapshots das duas bases de dados em /var/lib/dormice/backups/ e mantém os três mais recentes. Esses snapshots são o método documentado para recuperar de uma atualização problemática. Por isso, copie o mais recente para fora do servidor antes de voltar a atualizar.

O instalador termina executando dor doctor, uma verificação do anfitrião apenas de leitura que inicia contentores gVisor reais para confirmar que o runtime funciona, em vez de confiar numa lista de pacotes. Execute-a novamente sempre que o daemon apresentar problemas.

sudo dor doctor
systemctl is-active dormice

systemctl is-active dormice deve apresentar active. Se apresentar failed, journalctl -u dormice -n 50 contém o motivo. Uma falha no arranque é normalmente causada pelo swap ou por um pré-requisito do gVisor, e não pelo daemon.

O instalador também instala o Caddy no servidor. Por isso, verifique o que está a escutar antes de considerar concluída a configuração da firewall.

sudo ss -lntp

O daemon faz sempre bind a 127.0.0.1. Por conceção, não existe uma definição para alterar esse endereço. Apenas a porta pode mudar: DORMICE_PORT usa 3676 por predefinição. O gateway ao lado segue a mesma regra em 127.0.0.1:3677, com DORMICE_GATEWAY_PORT para a porta e sem uma definição de host. Aceder a qualquer um deles a partir do seu portátil é uma ação deliberada. A opção mais simples é um túnel SSH que encaminhe ambas as portas.

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

Com o túnel aberto, http://127.0.0.1:3677/console no seu portátil é a consola Web, servida pelo gateway. Na primeira visita, confirme que é o operador colando o token da API uma vez. Depois, defina um nome de utilizador e uma palavra-passe para a consola. O início de sessão define um cookie de sessão httpOnly, válido durante 7 days, que o JavaScript da página não consegue ler. A consola nunca volta a apresentar o token. A página Connect apresenta snippets de cliente prontos a copiar e colar, já apontados para o seu próprio endpoint.

Crie um sandbox e execute código nele

Uma operação cria um sandbox: acquire. Ela é idempotente, portanto a mesma chave devolve sempre o mesmo sandbox, criando-o, reativando-o, iniciando-o ou restaurando-o conforme necessário. Todos os outros verbos devolvem 404 para uma chave que nunca foi utilizada. A CLI dor não tem o verbo acquire, por isso o primeiro sandbox é criado pela consola ou por uma biblioteca cliente.

A rota da consola é a mais rápida. Abra /console através do túnel e crie um sandbox chamado my-agent. A CLI passa então a trabalhar nele.

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 apresenta cada sandbox com o seu estado no ciclo de vida. É assim que pode monitorizar a transição de ativo para congelado. dor sandbox exec apresenta uma versão do Python 3.12, porque a imagem padrão é Ubuntu 24.04 e já inclui Python 3.12, Node 24, git e ripgrep. Um erro de autenticação significa, em vez disso, que a linha do token copiada incluía o nome da variável.

Os ficheiros são transferidos com dor sandbox push my-agent ./script.py, que os coloca em /home/user/script.py, e dor sandbox pull my-agent notes.txt transfere um ficheiro de volta. Os verbos nativos para ficheiros estão limitados a 16 MiB por ficheiro. A interface de ficheiros do E2B transmite os dados e permite que a quota de disco do sandbox seja o único limite.

A destruição é o único verbo que elimina dados. dor sandbox destroy my-agent remove o sandbox e é idempotente. O README principal, a competência de agente incluída e o README do pacote da CLI documentam-no com esse único nome. Execute dor sandbox --help na sua própria compilação, porque o instalador acompanha main e a CLI continua a receber novas funcionalidades.

Aponte o seu código E2B existente para o seu próprio servidor

Este é o motivo para utilizar esta solução. O pacote oficial e2b do npm, sem alterações, comunica com o Dormice. Execute isto no seu portátil com o túnel SSH aberto, para que nada novo fique a escutar no servidor.

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

Uma execução normal apresenta o código de saída 0 e 42. A chave da API é o seu token do Dormice com o prefixo e2b_, que é o formato esperado pela camada de compatibilidade.

A compatibilidade não é apenas um stub. O suite de testes end-to-end do projeto testa o stdout e o stderr em fluxo, os comandos em segundo plano, um PTY interativo, os URLs assinados para upload e download, a monitorização de diretórios e um proxy de portas através do pacote oficial, contra daemons reais do Docker e do gVisor. Antes de migrar qualquer carga real, tenha em conta algumas diferenças:

  • As compilações de templates não estão implementadas. Um template é uma imagem Docker que cria e regista com dor template add, e Sandbox.create('name') resolve essa imagem. Um nome não registado devolve 404, em vez de ser aceite incorretamente.
  • Os sandboxes criados através da interface E2B têm deadlines reais, porque a semântica do E2B os exige. Não são impostos deadlines aos sandboxes criados através da API nativa.
  • Um sandbox congelado mantém os seus processos e retoma a execução no ponto em que estavam. Por isso, a pausa e a retoma aqui não correspondem à paragem e ao arranque a frio a que pode estar habituado.

O que o sandbox impede e o que não impede

O gVisor intercepta as chamadas de sistema do contentor no espaço do utilizador e trata-as internamente. Assim, o código no sandbox não comunica diretamente com o kernel do host. Dentro do sandbox, os comandos são executados como user (uid 1000), mas essa conta tem sudo sem palavra-passe. Por isso, o root dentro do sandbox está disponível para qualquer código que o solicite. Não considere o uid uma proteção. O projeto afirma claramente que o limite de segurança é o gVisor, não o uid. Mesmo que um sandbox eleve os próprios privilégios, continua sem conseguir aceder ao kernel do host. Isto cobre o caso normal: um script gerado que execute rm -rf /, encha o disco ou crie processos até causar uma falha danifica o próprio sandbox e fica limitado a ele.

Isto é o que o sandbox não impede. Essa proteção é da sua responsabilidade.

  • Um sandbox tem acesso de saída à rede. O código gerado pode descarregar o que quiser e enviar tudo o que encontrar. O reforço de segurança do instalador cobre duas situações específicas: bloqueia o tráfego dos contentores para o serviço de metadados da cloud em 169.254.0.0/16 e em 100.100.100.200, o endereço usado pela Alibaba Cloud, onde uma cloud fornece as credenciais da instância a qualquer processo que consiga aceder-lhe; e desativa o tráfego entre contentores com "icc": false no daemon.json do Docker. Nada mais é bloqueado. Consulte sudo iptables -S DOCKER-USER e adicione as suas próprias regras DROP para os intervalos privados que um sandbox não deve conseguir alcançar.
  • O Docker insere as próprias regras antes da firewall. Por isso, uma porta publicada de um contentor pode responder a partir da Internet enquanto o ufw indica que está fechada. Consulte como o Docker publica portas além do ufw e os fundamentos da firewall ufw para um VPS antes de expor qualquer serviço neste host.
  • O gVisor é um kernel no espaço do utilizador, não um hypervisor. Esta é uma escolha deliberada. O freezing exige que os sandboxes sejam processos, e exigir KVM impediria a instalação em muitos ambientes. Se o seu modelo de ameaças exigir virtualização por hardware, use isolamento da classe do Firecracker e aceite o custo operacional correspondente.
  • O token da API é todo o limite de segurança do lado do cliente. Qualquer processo que tenha DORMICE_API_TOKEN pode criar, ler e destruir todos os sandboxes da máquina. Dê ao processo do agente o seu próprio utilizador com privilégios mínimos no VPS e trate o token como trata uma chave SSH. As práticas de execução segura do Claude Code num VPS aplicam-se diretamente.

O daemon é executado como root no host. O gVisor protege o host contra o código dentro de um sandbox, mas nada protege o host contra o daemon ou contra quem tiver o respetivo token. Por isso, a máquina que executa o Dormice deve ser dedicada a essa função. Se o seu agente também aceder a ferramentas através de MCP (model context protocol), mantenha esses servidores MCP num VPS separado pelo mesmo motivo.

Quantos sandboxes cabem em 4 GB e 8 GB?

Duas coisas consomem memória: a utilização base do host e o conjunto de trabalho de cada sandbox que está atualmente ativo. Reserve cerca de 1 GB para o Ubuntu, o Docker e o daemon. Depois, divida o que restar pelo consumo real de um dos seus sandboxes. Um sandbox que executa um script Python que lê alguns ficheiros utiliza cerca de 200 a 300 MiB. Um sandbox que executa um compilador ou uma suite de testes completa pode ultrapassar 1 gibibyte.

GráficoConcurrent sandboxes by host RAM, arithmetic after a 1 GB host reserve
Os dados por trás deste 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
  }
]

Um VPS com 4 GB suporta cerca de 6 sandboxes ativos em simultâneo se cada um utilizar 512 MiB, ou 3 se cada um utilizar 1 gibibyte completo. Num VPS com 8 GB, esses valores passam para 14 e 7. Estes são limites para trabalho concorrente, calculados por aritmética e não por um benchmark. Por isso, monitorize free -m enquanto executa a sua própria carga.

Os sandboxes congelados ficam limitados pelo swap e não pela RAM. Esse é o objetivo deste desenho. Um sandbox congelado que estava a utilizar 1 gibibyte mantém aproximadamente essa quantidade no swap e quase nada na memória residente. Assim, o swapfile predefinido de 16 GB do instalador mantém cerca de 16 desses sandboxes. Depois disso, eles precisam de passar para o estado parado, no qual consomem apenas espaço em disco. O disco é o limite real a longo prazo: cada sandbox mantém o seu sistema de ficheiros, e algumas dezenas de agentes, cada um com um diretório node_modules, vão preencher um volume pequeno muito antes de a memória se tornar um problema.

Congelar, parar, arquivar: parâmetros do ciclo de vida

Os valores predefinidos são congelar após 10 minutos de inatividade, parar após 3 dias e arquivar após 7 dias quando o arquivamento está configurado. Definir stopAfterSeconds como null cria um agente residente: pode congelar quando fica inativo, mas nunca faz um arranque a frio.

O arquivamento é opcional, e o daemon indica claramente o estado. Configure um armazenamento compatível com S3 na página de definições da consola (as quatro variáveis DORMICE_S3_* continuam a existir, mas servem apenas como valores iniciais para o primeiro arranque do gateway). O disco de um sandbox parado é então empacotado com tar e zstd, enviado para o bucket e libertado localmente. Esse bucket pode ser um bucket MinIO alojado por si noutra máquina sua. Se o armazenamento não estiver configurado, os sandboxes permanecem parados indefinidamente, e uma política que peça o arquivamento é recusada em vez de ser ignorada silenciosamente. As reposições são visíveis, não silenciosas: a aquisição seguinte responde imediatamente com um estado de reposição e um valor de progresso. Depois, muda para pronto quando o disco estiver novamente disponível.

Ainda deve depender dele?

Resposta direta: não para nada que não consiga reconstruir. O repositório foi criado em 8 July 2026. Em 12 October 2026, apresenta 1,509 stars, 109 forks, uma licença Apache-2.0 e nenhuma release tagged. A própria linha de estado do README indica que nada está pronto para produção.

Essa combinação cria um risco específico. O código pode mudar sem aviso, porque o instalador acompanha main. A interface ainda está a ser definida: a documentação descreve agora um gateway à frente do daemon, com a sua própria porta, o seu próprio ficheiro de configuração e a sua própria base de dados. Além disso, um projeto com cerca de três meses pode simplesmente parar, porque nenhuma cláusula da licença obriga alguém a continuar o desenvolvimento.

A compatibilidade com E2B torna este risco controlável. A aplicação comunica com um protocolo que tem uma implementação alojada, por isso, se o Dormice parar, basta alterar 2 URLs para continuar a trabalhar. Desenvolva o agente contra a interface E2B, em vez de usar a API nativa, para manter essa alternativa. O pacote nativo @dormice/sdk também ainda não está no npm. Para o usar, é necessário compilá-lo a partir do repositório, o que constitui uma segunda razão para começar pelo caminho compatível.

Execute-o onde possa aceitar perder o ambiente. Reconstrua o host a partir de um script, mantenha o token fora de todas as prompts e commits e retire das sandboxes tudo o que precisar de conservar, seguindo o seu próprio calendário de backups.

FAQ

O Dormice está pronto para produção?

Não, e o próprio projeto afirma isso. A linha de estado do README indica que nada ali está pronto para produção. Em 12 October 2026, o repositório tinha cerca de três meses, sem tags git nem releases. Portanto, não existe um número de versão para fixar. O instalador clona o branch main, o que significa que cada execução obtém o commit mais recente. Registe git -C /opt/dormice rev-parse HEAD depois de cada instalação. Mantenha uma cópia dos snapshots da base de dados que o instalador grava em /var/lib/dormice/backups/. Guarde todos os dados importantes fora das sandboxes.

Em que difere o Dormice de fornecer ao meu agente uma VM descartável?

Uma VM descartável é uma máquina com SSH que cria para uma sessão e elimina depois. O Dormice é uma API de execução: o seu programa chama acquire, depois exec, e recebe o stdout e um código de saída, sem uma sessão de shell intermédia. A VM é adequada para uma pessoa ou para um agente que precisa de um computador completo durante algum tempo. O Dormice é adequado para uma aplicação que executa código gerado várias vezes por dia e não quer repetir a configuração e a remoção de uma máquina em cada execução.

O SDK oficial da E2B funciona realmente sem alterações no código?

Sim, com alterações de configuração. Aponte apiUrl e sandboxUrl para /e2b/api e /e2b/envd no daemon e passe o token do Dormice com o prefixo e2b_ como chave da API. A execução de comandos, as sessões PTY, a transferência de ficheiros, os URLs assinados e o proxy de portas estão todos cobertos pela suite end-to-end do projeto, executada através do pacote oficial. A criação de templates é a principal limitação: e2b template build não está implementado. Assim, um template é uma imagem Docker que cria e regista com dor template add.

Quantas sandboxes cabem numa VPS com 4 GB?

Cerca de 6 podem permanecer ativas ao mesmo tempo se cada sandbox usar 512 MiB. Se cada uma usar um gibibyte completo, o valor é 3, depois de reservar aproximadamente 1 GB para o sistema operativo, o Docker e o daemon. As sandboxes congeladas são limitadas pelo swap. Com o ficheiro de swap predefinido de 16 GB do instalador, é possível manter cerca de 16 sandboxes que tenham usado um gibibyte cada. Meça o seu ambiente com free -m sob carga real, porque uma sandbox que executa uma suite de testes usa várias vezes mais memória do que uma que executa um script pequeno.

Por que motivo o Dormice precisa de vm.swappiness definido como 100?

Congelar uma sandbox significa transferir a memória inativa para o swap. O gVisor mantém a memória da sandbox como memória partilhada. O kernel Linux não troca memória partilhada para o swap com o valor predefinido de swappiness. Por isso, com o valor predefinido, o congelamento não recupera memória e a sandbox continua a consumir a memória total. O projeto mediu 0 bytes recuperados com o valor predefinido e 99.5 percent recuperados com o valor 100. Confirme o valor efetivo com sysctl vm.swappiness em vez de ler ficheiros de configuração, porque algumas imagens cloud são fornecidas com o valor 0.

Este artigo foi útil?