Como hospedar o Moli headless para agentes
Instale o Moli em um VPS pequeno, exponha o CDP apenas em loopback e conecte um agente. Veja as limitações que fazem páginas falharem fora do Chrome.
Um browser headless que cabe num VPS pequeno
Moli é um browser headless para agentes de IA e é suficientemente pequeno para ser alojado num VPS onde o headless Chrome não cabe. É um motor de browser escrito em Rust, não um wrapper sobre Chromium, e responde ao Chrome DevTools Protocol (CDP), o protocolo que a sua biblioteca de automação já utiliza. Instale um único binário, execute moli serve e indique http://127.0.0.1:9222 ao Playwright ou ao código do seu próprio agente.
Leia as limitações antes de instalar qualquer coisa. O projeto define claramente o seu âmbito: não tem browser com GUI, compositor GPU, paridade ao nível de píxeis com o Chrome nem suporte de alta fidelidade para Canvas/WebGL/reprodução de multimédia. As páginas que dependem destes recursos vão falhar. O Chrome real com Playwright continua a ser a alternativa, e a última secção mostra como decidir que páginas precisam dele.
Todos os comandos abaixo vêm do README do projeto e dos seus ficheiros de skill publicados, verificados novamente em 16 November 2026 contra a versão fixada. Todos os números dos gráficos são valores publicados pelo projeto sobre o seu próprio motor, não medições deste site, e cada legenda dos gráficos indica isso. Se ainda estiver a escolher um motor, o levantamento mais abrangente de browsers headless para agentes num VPS apresenta as alternativas.
Por que o Chrome headless usa tanta memória?
O Chrome é um navegador multiprocesso. Agrupa os documentos por site e, no Linux desktop, o Site Isolation completo mantém cada site, incluindo iframes de outros sites, nos seus próprios processos de renderização. O Chrome pode permitir que páginas do mesmo site partilhem um processo de renderização, mas uma sessão que aceda a vários sites continua a executar vários processos. Cada processo de renderização tem o seu próprio heap V8 e os seus próprios buffers gráficos. Este desenho é adequado para um desktop, onde uma página bloqueada não deve fazer cair toda a janela. Num VPS com 2 GB, uma única etapa de navegação pode consumir mais memória do que a aplicação que está efetivamente a executar.
O projeto rastreou 192 URLs públicas variadas com quatro engines e publicou o resultado.
Os dados por trás deste gráfico
[
{
"engine": "Moli",
"useful_pages": 103,
"median_rss_mib": 73
},
{
"engine": "Chrome Headless",
"useful_pages": 101,
"median_rss_mib": 773
},
{
"engine": "Lightpanda",
"useful_pages": 85,
"median_rss_mib": 40
},
{
"engine": "Obscura",
"useful_pages": 57,
"median_rss_mib": 39
}
]O Chrome Headless devolveu 101 páginas úteis e o Moli devolveu 103, pelo que, neste conjunto, as duas engines leram aproximadamente a mesma proporção da web. A diferença está na memória: um RSS mediano (resident set size, a memória que um processo mantém efetivamente na RAM) de 773 MiB para o Chrome, contra 73 MiB para o Moli. Esta diferença é plausível porque resulta da arquitetura dos processos. Não deve assumir que a proporção exata será igual nas suas páginas.
A mediana não é o valor que causa problemas. O pico é. Quando uma máquina com 2 GB fica sem memória, o kernel escolhe um processo e termina-o. O registo aparece em dmesg -T ou journalctl -k:
Out of memory: Killed process 4211 (chrome) total-vm:2318936kB, anon-rss:1418324kB, file-rss:0kB, shmem-rss:0kB, UID:1000 pgtables:3540kB oom_score_adj:0O seu agente nunca vê essa linha. Vê um navegador que deixou de responder, normalmente como um erro do Playwright, como page.goto: Page crashed, ou um destino fechado. Esse erro não menciona memória. Por isso, o OOM (out of memory) killer é a primeira coisa a verificar quando um agente falha aleatoriamente numa máquina pequena. Dimensionar para o pico é o mesmo processo que escolher RAM e CPU para um VPS de agente.
Instalar o binário Moli, fixado numa versão
O projeto publica um instalador de shell e arquivos tar pré-compilados nas releases do GitHub. Em 16 November 2026, a release mais recente é a 1.1.25, publicada em 15 November 2026; os comandos abaixo continuam fixados na 1.1.18. O projeto mediu a sua pontuação Lexbench, citada mais à frente neste guia, na versão 0.1.1, e o README não identifica a versão usada nos outros valores. Considere todos esses valores como uma indicação aproximada do comportamento do motor, não como uma garantia sobre a build que vai instalar.
Fixe a versão. Um instalador que resolve sempre latest move o seu agente para outro motor de browser na próxima rebuild. Uma alteração no comportamento do browser deve ser agendada, não descoberta por acaso.
O instalador de shell é a forma mais rápida de começar, mas deve lê-lo antes de o executar.
curl --proto '=https' --tlsv1.2 -fsSL \
-o /tmp/moli-installer.sh \
https://github.com/lexmount/moli/releases/download/v1.1.18/moli-installer.sh
less /tmp/moli-installer.sh
sh /tmp/moli-installer.shLeia o script antes de o executar. É curto. Escolhe um arquivo a partir de uname -m e depois extrai um único binário para ~/.local/bin. Em x86_64, usa o arquivo moli-x86_64-unknown-linux-gnu.tar.gz. Num servidor Arm, usa o arquivo aarch64. Assim, tanto os planos VPS Arm como os x86 são suportados. Defina MOLI_INSTALL_DIR para instalar noutra localização. Verifique o que o script resolve para a versão: a release mais recente, não a tag a partir da qual obteve o script. Isso é aceitável para uma primeira avaliação, mas está errado para uma rebuild que queira repetir de forma consistente.
Por isso, para qualquer instalação permanente, faça manualmente o que o instalador faz e indique o arquivo exato. Esta também é a forma de colocar o binário num local que um serviço do sistema consiga alcançar. Além disso, evita encaminhar um script transferido diretamente para uma shell.
cd /tmp
curl --proto '=https' --tlsv1.2 -fsSLO \
https://github.com/lexmount/moli/releases/download/v1.1.18/moli-x86_64-unknown-linux-gnu.tar.gz
mkdir -p moli-pkg
tar -xzf moli-x86_64-unknown-linux-gnu.tar.gz -C moli-pkg --strip-components=1
sudo install -m 0755 moli-pkg/moli /usr/local/bin/moli
moli --versionmoli --version imprimir a versão que fixou é toda a verificação necessária. moli: command not found imediatamente depois do instalador significa que o diretório de instalação não está no seu PATH, e o instalador imprime uma linha com o diretório que precisa de adicionar.
Extração única com moli fetch
Muitos dos trabalhos que um agente entrega a um navegador são “carregar este URL e dizer-me o que ele apresenta”. Isso não requer nenhum servidor. moli fetch inicia o motor, carrega uma página, escreve um artefacto na saída padrão e termina. Assim, não mantém memória entre chamadas.
moli fetch --dump markdown --wait-until networkidle https://example.com
moli fetch --dump semantic_tree_text --wait-selector "main" https://example.com
moli fetch --dump json --wait-until networkidle https://example.com > page.jsonO primeiro comando apresenta a página como Markdown, começando por # Example Domain. O Markdown é o formato mais económico para fornecer a um modelo, porque remove a marcação e mantém o texto. semantic_tree_text mantém as funções e a estrutura. É o que deve usar numa página com muita navegação, onde as ligações são tão importantes como o texto. --dump json inclui o estado HTTP e o rastreio do pedido. Use-o quando uma obtenção não devolve conteúdo e precisa de saber porquê.
A estratégia de espera determina se obtém conteúdo ou uma estrutura vazia. --wait-until networkidle devolve o resultado quando a rede deixa de apresentar atividade. --wait-until domstable devolve o resultado quando o DOM deixa de sofrer alterações. É a melhor opção para uma página que faz consultas em segundo plano e, por isso, nunca fica realmente sem atividade. --wait-selector espera por um seletor que indique. É a única estratégia que conhece algum dado sobre a página que está a obter. Por isso, é a mais fiável quando conhece o elemento de destino.
As capturas de ecrã e os PDF precisam de um layout real, e o layout está desativado por predefinição:
moli fetch --layout --dump screenshot https://example.com > page.png
moli fetch --layout --dump screenshot_full https://example.com > full-page.png
moli fetch --layout --dump pdf https://example.com > page.pdfO README identifica a política de layout predefinida como LayoutPolicy::Mock: a geometria é simulada e nada é desenhado, porque o layout e o desenho são a parte mais dispendiosa de um navegador. Essa predefinição explica os valores de memória apresentados acima. Também significa que um PNG vazio normalmente resulta da ausência da flag --layout, e não de um problema na página.
Para URLs encontrados pelo agente, em vez de URLs escolhidos por si, adicione --block-private-networks. Um agente que segue ligações lidas numa página pode ser induzido a obter http://169.254.169.254/ para credenciais de instâncias na cloud ou uma porta de base de dados em localhost que nunca deveria estar exposta à Internet. Essa flag bloqueia endereços privados em pedidos diretamente ligados, e --block-cidrs adiciona intervalos bloqueados específicos. Os destinos resolvidos pelo proxy têm de ser filtrados pelo proxy. Quando o trabalho consiste em rastrear páginas, e não em ler uma única página, a estrutura desse pipeline é apresentada em alternativas self-hosted ao Firecrawl. O passo anterior, que consiste em encontrar URLs, é apresentado em uma skill de pesquisa com SearXNG para agentes.
Apontar um agente para o Moli via CDP
Para um agente que navega e clica em muitas etapas, execute o servidor separadamente.
moli serve --host 127.0.0.1 --port 9222127.0.0.1 e a porta 9222 são os valores predefinidos, por isso um moli serve simples já fica associado apenas ao loopback. Mesmo assim, especifique ambos em qualquer configuração permanente. Assim, a próxima pessoa que ler o ficheiro de serviço não precisa de se lembrar do valor predefinido.
Verifique o servidor antes de ligar um cliente a ele:
curl -s http://127.0.0.1:9222/json/versionUm servidor funcional responde com um objeto JSON que contém um campo webSocketDebuggerUrl. Esse URL é o ponto ao qual um cliente CDP se liga. curl: (7) Failed to connect to 127.0.0.1 port 9222: Connection refused significa que não há nada a escutar. Nesse caso, consulte o terminal onde iniciou o servidor ou use journalctl -u moli -n 50 quando ele estiver configurado como serviço. /json/list apresenta os destinos abertos e /json/protocol apresenta os domínios implementados nesta compilação. Assim, pode confirmar se existe aqui um método CDP de que dependa.
O Playwright liga-se a esse endpoint em vez de iniciar o seu próprio navegador:
import { chromium } from "playwright";
const browser = await chromium.connectOverCDP("http://127.0.0.1:9222");
const context = browser.contexts()[0];
const page = context.pages()[0] ?? await context.newPage();
await page.goto("https://example.com");
console.log(await page.locator("body").innerText());
await browser.close();A linha relevante é connectOverCDP, não chromium.launch(). Não existe aqui um processo Chromium filho. Por isso, executablePath e as opções habituais de contentores, como --no-sandbox, não têm qualquer efeito. As definições de proxy, cookies e user-agent devem ser passadas ao servidor Moli como opções próprias, pelo mesmo motivo. Espere suporte apenas para um subconjunto do CDP, não para todo o protocolo do Chrome. Um erro explícito de método não suportado indica um limite do motor, não um erro no seu código.
Duas opções do servidor determinam o que o agente pode fazer. --layout ativa a geometria real, necessária para cliques por coordenadas e capturas de ecrã. --resource obtém as imagens, os tipos de letra e os conteúdos multimédia opcionais. Isto consome largura de banda e memória em cada carregamento de página, por isso mantenha a opção desativada até uma página demonstrar que precisa dela. --profile-dir mantém os cookies e o armazenamento entre execuções. Sem essa opção, cada execução é descartável.
Os dados por trás deste gráfico
[
{
"engine": "Moli",
"cdp_ready_ms": 34.85,
"peak_pss_mib": 102.46,
"processes": 1
},
{
"engine": "Chromium",
"cdp_ready_ms": 169.37,
"peak_pss_mib": 348.82,
"processes": 11
}
]Na carga de trabalho de agente de exemplo do projeto, o Moli aceitou uma ligação CDP após 34.85 ms, contra 169.37 ms no Chromium, com um PSS máximo (proportional set size, memória contabilizada com as páginas partilhadas divididas entre os processos que as partilham) de 102.46 MiB, contra 348.82 MiB. A diferença estrutural está na última coluna: 1 processo, contra 11. Um processo é uma única unidade para o systemd supervisionar e um único cgroup ao qual aplicar limites. É isso que torna curta a próxima secção.
Executar moli serve como um serviço systemd no loopback
Execute o servidor como um serviço quando um agente precisar de um browser à sua espera. Continue a utilizar moli fetch por URL quando não precisar disso, porque um servidor inativo continua a ocupar memória.
Não coloque a porta 9222 numa interface pública. O CDP não tem qualquer etapa de autenticação. Qualquer pessoa que consiga alcançar essa porta pode controlar o browser e ler tudo o que o browser consiga alcançar, incluindo quaisquer cookies no diretório do seu perfil. Mantenha-o em 127.0.0.1. Aceda-lhe a partir de outra máquina através de um túnel SSH (ssh -L 9222:127.0.0.1:9222 user@your-vps) ou de uma interface VPN privada, e faça com que o agente se ligue a http://127.0.0.1:9222 do seu próprio lado desse túnel.
Crie um utilizador de serviço e, em seguida, o ficheiro da unidade:
sudo useradd --system --home-dir /var/lib/moli --shell /usr/sbin/nologin moliEscreva /etc/systemd/system/moli.service:
[Unit]
Description=Moli headless browser CDP server
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=moli
Group=moli
ExecStart=/usr/local/bin/moli serve --host 127.0.0.1 --port 9222 --profile-dir /var/lib/moli/profile --block-private-networks
Restart=on-failure
RestartSec=2
StateDirectory=moli
MemoryAccounting=yes
MemoryMax=768M
NoNewPrivileges=yes
PrivateTmp=yes
ProtectHome=yes
ProtectSystem=strict
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now moli.service
systemctl status moli.service
curl -s http://127.0.0.1:9222/json/versionsystemctl status deve mostrar active (running), e curl deve devolver o JSON de descoberta. ProtectSystem=strict torna o sistema de ficheiros só de leitura, exceto os sistemas de ficheiros de API e as exceções configuradas; StateDirectory=moli cria /var/lib/moli, propriedade do utilizador de serviço, e mantém-no com permissões de escrita. Com PrivateTmp=yes, o /tmp e o /var/tmp privados da unidade também permitem escrita. Uma unidade que inicia e depois termina com um erro de permissões em journalctl -u moli está quase sempre a tentar escrever num local que ProtectSystem acabou de tornar só de leitura. Mova esse caminho para o diretório de estado.
MemoryMax=768M limita a utilização de memória da unidade. A unidade obtém o seu próprio cgroup e, quando a utilização atinge o limite, o kernel tenta recuperar memória. Se não for possível reduzir a utilização, o OOM killer é invocado dentro desse cgroup e não termina processos fora dele. O journal regista uma terminação:
moli.service: A process of this unit has been killed by the OOM killer.Interprete essa linha como um sinal para dimensionamento. As páginas podem ser mais pesadas do que previsto ou o limite pode ser demasiado baixo. Defina o valor com base numa medição das suas próprias páginas. Essa medição é explicada na secção seguinte. A contabilização mede a utilização; controlos separados, como MemoryMax e CPUQuota, impõem limites a outros serviços, e limitar a memória e a CPU com systemd funciona através dos restantes controlos.
Meça o pico de memória
Os valores publicados foram obtidos no hardware e nas páginas de outras pessoas. O pico de memória determina se o seu servidor continua a funcionar, e o pico depende totalmente do que você carrega. Faça a medição antes de dimensionar os recursos.
Para obter páginas uma única vez, use o binário time, que informa muito mais dados do que o builtin do shell com o mesmo nome:
sudo apt update && sudo apt install -y time
/usr/bin/time -v moli fetch --dump markdown --wait-until networkidle https://example.com > /dev/nullA saída termina com um bloco de estatísticas de recursos que inclui Maximum resident set size (kbytes). Divida esse valor por 1024 para obter MiB. Execute o comando em dez páginas que o seu agente realmente visita, e não em example.com. Mantenha o pior resultado em vez da média, porque o OOM killer reage aos picos.
Para o serviço, leia o contador que o kernel já mantém para o respetivo cgroup:
cat /sys/fs/cgroup/system.slice/moli.service/memory.peak
systemd-cgtop -mmemory.peak é uma contagem em bytes e representa o maior valor atingido desde a criação do cgroup. Um reinício do serviço só o repõe se o cgroup for recriado. Esse valor deve ficar abaixo de MemoryMax, com margem adicional para a página mais pesada que você ainda não visitou. systemd-cgtop -m mostra o uso atual por unidade. É a forma mais rápida de identificar qual serviço do servidor está a consumir mais recursos no momento.
Onde o Moli falha e quando ainda é necessário usar o Chrome?
O projeto também executa um benchmark com 1,308 tarefas comparáveis de automação de navegador e publica a pontuação de vários engines.
Os dados por trás deste gráfico
[
{
"engine": "Chrome",
"success_rate_pct": 99.85
},
{
"engine": "Moli 0.1.1",
"success_rate_pct": 81.88
},
{
"engine": "Kitesurf",
"success_rate_pct": 62.08
},
{
"engine": "Lightpanda",
"success_rate_pct": 53.29
},
{
"engine": "Obscura",
"success_rate_pct": 44.88
}
]Entre esses 5 engines, o Moli 0.1.1 concluiu 81.88 por cento das tarefas, e o Chrome, o engine de referência, concluiu 99.85 por cento. O próprio projeto atribui essas pontuações usando a sua própria suite, portanto interprete-as como uma afirmação, não como um resultado independente.
A interpretação prática é simples. O Moli 0.1.1 falhou em 237 das 1,308 tarefas selecionadas, aproximadamente uma em cada cinco. Se o seu agente visita um conjunto fixo de páginas que você controla, essa proporção informa muito pouco, porque as suas páginas funcionam ou não funcionam, e você pode verificar isso ainda hoje. O relatório descreve observações, não limites máximos de capacidade. Portanto, essas falhas não comprovam a ausência de suporte a funcionalidades específicas nem uma taxa de falha na web aberta.
O âmbito declarado do projeto identifica as cargas de trabalho que devem ser verificadas com o Chrome.
- Aplicações que exigem renderização Canvas de alta fidelidade; o Moli implementa operações de desenho Canvas, portanto o Canvas, por si só, não comprova a necessidade do Chrome
- Qualquer aplicação que exija WebGL ou composição por GPU de alta fidelidade, porque não existe um compositor de GPU
- Reprodução de multimédia exigente
- Testes visuais que validam capturas de ecrã com correspondência exata de píxeis em relação ao Chrome, porque a paridade com o Chrome não é um objetivo
O outro número citado pelo projeto, uma execução completa com 1.612 milhões de testes da plataforma web aprovados, é uma afirmação sobre a cobertura de padrões. Não é uma garantia sobre os sites que o seu agente visitará. Uma página pode usar apenas padrões bem suportados e ainda assim falhar numa verificação para bots, e nenhuma pontuação de engine cobre esse caso.
Por isso, mantenha o fallback no desenho da solução. Envie primeiro todos os URLs para o Moli. Quando uma página voltar vazia ou um seletor nunca aparecer, repita a tentativa para esse URL usando o Playwright para controlar um Chrome real, numa máquina maior ou segundo um agendamento em que um processo de 773 MiB seja aceitável. A maioria dos agentes passa a maior parte do tempo em páginas comuns. Assim, o engine pequeno processa o volume e o engine mais caro trata dos casos extremos.
FAQ
O Moli pode substituir o Chrome headless do meu agente?
Para ler páginas, extrair texto e executar cliques comuns, normalmente sim. No benchmark do próprio projeto, com 1,308 tarefas, concluiu 81.88 por cento, contra 99.85 por cento do Chrome, deixando 237 tarefas sem concluir no Moli 0.1.1; estas observações não demonstram que todas as falhas exigem uma capacidade não suportada. O Canvas/WebGL e a reprodução de multimédia com elevada fidelidade estão fora do âmbito declarado do projeto, mas o uso exclusivo de Canvas não torna uma aplicação incompatível. Encaminhe para o Chrome real as URLs que falharem nas suas verificações, em vez de voltar a usar o Chrome para tudo.
Quanta RAM o Moli precisa num VPS?
O projeto indica um RSS mediano de 73 MiB num crawl de 192 URLs e um PSS máximo de 102.46 MiB num episódio de agente de amostra, contra 773 MiB de mediana no Chrome headless. Esses são os valores medidos pelo projeto nas respetivas páginas. Meça o seu ambiente com /usr/bin/time -v em torno de uma chamada moli fetch para uma execução única, ou leia /sys/fs/cgroup/system.slice/moli.service/memory.peak para o serviço. Depois, defina MemoryMax acima do pior valor observado.
É seguro expor a porta 9222 à Internet?
Não. O CDP não tem autenticação. Qualquer pessoa que consiga alcançar essa porta pode controlar o seu browser e ler tudo aquilo a que o browser tiver acesso. Mantenha --host 127.0.0.1 e aceda ao endpoint a partir de outra máquina através de um túnel SSH ou de uma interface VPN privada. Se tiver de associar o serviço a outro endereço, use uma interface privada e controle o acesso com a firewall.
Por que motivo o meu screenshot está vazio ou o meu clique não acerta em nada?
O layout está desativado por predefinição. O README indica LayoutPolicy::Mock como política predefinida. Por isso, a geometria dos elementos não é real e tudo o que dependa de uma caixa na página não funciona. Inicie o servidor com moli serve --layout ou adicione --layout a moli fetch. O screenshot e os caminhos baseados em coordenadas começam então a funcionar. As imagens em falta dependem de outro flag: --resource.
Que versão do Moli devo instalar?
Fixe uma versão e registe qual foi usada. Em 16 de novembro de 2026, a versão mais recente é a 1.1.25; os comandos deste guia continuam fixados na 1.1.18. A pontuação do projeto no Lexbench foi medida na 0.1.1. Compare as versões antes de comparar resultados com outra pessoa. Transfira o moli-x86_64-unknown-linux-gnu.tar.gz dessa tag e instale o binário manualmente, em vez de depender do instalador da shell. O instalador resolve a versão mais recente, não a tag a partir da qual o ficheiro foi obtido. Depois, confirme com moli --version.