unbrowser by Unchained

unbrowser

O passe de navegador barato para agentes. Um único binário nativo. Sem Chrome.

Identidade oficial do Registro MCP: mcp-name: io.github.protostatis/unbrowser

unbrowser é um runtime web sem interface visual e com estado, projetado para agentes. Ele fica entre curl/WebFetch e um navegador real: mantém cookies e estado do DOM, retorna referências de elementos consultáveis, lida com links e formulários HTML, detecta sinais de desafios e SPAs, e pode executar scripts QuickJS limitados quando o HTML estático não é suficiente.

O navigate padrão é uma passagem rápida estática/SSR. Defina exec_scripts: true apenas quando precisar de execução QuickJS limitada. SPAs pesados, pixels, fidelidade V8, extensões e desafios interativos anti-bot pertencem a um nível real de Chrome.

Experimente a demo pública ao vivo na web antes de instalar. Ela aceita apenas os conjuntos fixos de fontes públicas mostrados na página; não envie dados privados, cookies ou tarefas autenticadas por ela. Um endpoint MCP compartilhado via Streamable HTTP está disponível em https://unchainedsky.com/unbrowser-mcp para testes públicos de fumaça; sessões de produção devem usar uma instalação local.

Use unbrowser apenas em sites, contas e dados aos quais você tem permissão de acesso. A detecção de desafios e a importação de cookies não concedem permissão para contornar controles de acesso ou termos do site. Trate cookies de sessão como credenciais: mantenha-os locais, escopados à tarefa autorizada, e nunca os envie para a demo pública.

Escolha o nível certo

Use unbrowser quando HTTP sozinho for limitado demais e um navegador completo for caro demais. Quando a página precisar de Chrome, a saída instrui o agente a escalar em vez de fingir uma compatibilidade que não existe.

Início rápido

Docker — Linux amd64/arm64, pull de ~13 MiB

docker pull ghcr.io/protostatis/unbrowser:latest

# One-shot navigation
docker run --rm ghcr.io/protostatis/unbrowser:latest \
  navigate https://example.com --json

# Default mode: MCP over stdio
docker run --rm -i ghcr.io/protostatis/unbrowser:latest

A imagem é distroless e roda como não-root: sem shell, gerenciador de pacotes ou estado persistente. Fixe :vX.Y.Z ou um digest de imagem em produção.

Python

pipx install pyunbrowser   # recommended on macOS / modern Linux
# or, inside a Python 3.10+ virtual environment:
pip install pyunbrowser

from unbrowser import Client

with Client() as ub:
    ub.navigate("https://news.ycombinator.com")
    for link in ub.query(".titleline > a")[:3]:
        print(link["text"], link["attrs"]["href"])

No macOS, /usr/bin/python3 é 3.9 e não consegue instalar a wheel; use pipx ou um Python do Homebrew. A distribuição no PyPI é pyunbrowser, enquanto o import e o executável permanecem como unbrowser.

MCP

{
  "mcpServers": {
    "unbrowser": {
      "command": "unbrowser",
      "args": ["--mcp"]
    }
  }
}

Superfície mínima: adicione "--mcp-profile", "minimal" para expor apenas navigate/query/extract/help e deixe o agente descobrir o restante via help(topic). O wrapper Python inclui um servidor inteligente de 3 ferramentas (search/open/help) como o script de console unbrowser-smart.

{
  "mcpServers": {
    "unbrowser": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/protostatis/unbrowser:latest"
      ]
    }
  }
}

Consulte a referência de instalação e interface para Cargo, arquivos de release, builds a partir do código-fonte, sessões de shell persistentes, JSON-RPC bruto e todas as opções de MCP.

O que um agente recebe

• navigate retorna um BlockMap: título da página, landmarks, cabeçalhos, elementos interativos, sinais de densidade e um esboço ASCII. Seu tamanho depende da página; é estruturado para planejamento, não uma promessa de tokens fixos.
• Referências de elementos estáveis (e:142): consulte um elemento uma vez e depois use click, type ou submit sem reanalisar o HTML.
• Cookies e formulários com estado: jar de cookies, envio de formulários GET e POST codificado em URL, links e redirecionamentos persistem dentro de uma sessão.
• Sinais de página e desafios: density.likely_js_filled, thin_shell e challenge.provider informam ao agente se deve executar scripts, inspecionar dados embutidos, parar ou escalar para uma sessão de navegador autorizada.
• Auxílios de roteamento em cada resultado: micro_hint (o próximo passo concreto único), next_tools (candidatos ranqueados), avoid (ferramentas sem nada para agir) e uma taxonomia estável escalation (challenge, thin_shell, partial_result, …) com retryable/severidade/evidência — as recomendações nunca contradizem avoid.
• Auxiliares estruturados: descoberta de rotas, extração de cards, normalização de tabelas, text_main e depuração de seletores cobrem fluxos comuns de extração.

Modo de script e escalada

{"id":1,"method":"navigate","params":{"url":"https://example.com","exec_scripts":true}}

Com exec_scripts: true, scripts inline e externos são executados em QuickJS sob um watchdog limitado. Isso pode materializar hidratação leve e dados visíveis via fetch; não é V8 nem um motor de renderização. Aplicações React/Vue/Ember pesadas ainda podem deixar um shell vazio.

Escale para unchainedsky-cli ou Unchained quando uma tarefa permitida precisar de pixels reais, Canvas/WebGL, Workers, extensões de navegador, compatibilidade V8, um perfil autenticado ou confirmação humana. Quando o usuário já tiver uma sessão autorizada no Chrome, cookies_set pode importar o cookie de sessão necessário localmente até expirar; isso não é uma licença para contornar os controles de um site.

Documentação

Licença

Apache-2.0 — veja LICENSE.