Auto-Browser

Marco de automatización de navegador con perfiles de autenticación guardables y opciones de cumplimiento viables para desarrollos empresariales.

GitHub

897

Prueba este MCPPatrocinado

Documentación

Auto Browser

Auto Browser demo

Dale a tu agente de IA un navegador real, con un humano en el circuito.

Auto Browser es un plano de control de navegador nativo de MCP para flujos de trabajo autorizados. Proporciona a los clientes MCP, agentes LLM y operadores un navegador Playwright compartido con toma de control humana, perfiles de autenticación reutilizables, aprobaciones, registros de auditoría e implementación local-first.

Funciona con:

Claude Code, Cursor y VS Code, conectados directamente a través de HTTP
Claude Desktop, mediante el puente stdio incluido
cualquier cliente MCP que pueda hablar HTTP o stdio
llamadas REST directas cuando quieras control estilo curl primero

Por qué Auto Browser

Nativo de MCP desde el primer día. La superficie del navegador ya está empaquetada como un servidor MCP en lugar de añadirse después.
Toma de control humana cuando la web se vuelve frágil. noVNC mantiene la misma sesión en vivo disponible cuando una persona necesita intervenir.
Inicia sesión una vez, reutiliza después. Guarda perfiles de autenticación con nombre y reabre sesiones nuevas que ya están conectadas.
Local-first por defecto. Ejecuta toda la pila en tu propia máquina con Docker Compose, o usa Codespaces para una demo alojada rápida.
Barandillas de seguridad integradas. Aprobaciones, identidad del operador, eliminación de PII, recibos Witness y ajustes preestablecidos de políticas son parte de la superficie del producto.
Evidencia que puedes entregar a otra persona. Las cadenas de recibos Witness están firmadas con Ed25519, y un paquete exportado se verifica con scripts/verify_witness_bundle.py — que no importa nada de este proyecto, por lo que un destinatario no necesita ejecutar ni confiar en este controlador para verificarlo.
Nos auditamos a nosotros mismos en público. docs/audits/2026-08-execution-audit.md documenta una auditoría adversarial de este repositorio que encontró controles de seguridad que reportaban éxito sin hacer nada, con reproducciones, las correcciones y las compuertas que cierran la clase.
Inducción de habilidades gobernada. Los rastros de navegador verificados pueden convertirse en candidatos de habilidades escalonados con procedencia que se firma cuando se configura una identidad de malla — y se verifica al leer, no solo al producir — además de adaptadores de verificación y graduación solo de revisión — agentes que demuestran que pueden repetirse correctamente, no solo actuar una vez.

Buenos Casos de Uso

paneles internos y herramientas de administración
QA asistida por operador y depuración de navegador
flujos de cuenta de iniciar sesión una vez, reutilizar después
sitios frágiles donde un humano puede necesitar recuperar el flujo
flujos de trabajo de agentes impulsados por MCP que necesitan un navegador real, no solo extracciones de HTML

No es el Objetivo

resolución de CAPTCHA
scraping no autorizado o automatización de cuentas
modelado de identidad engañoso o herramientas de evasión

Lo Que Obtienes

Control del Navegador	Seguridad del Operador	Implementación e Integración
Sesiones respaldadas por Playwright con capturas de pantalla, resúmenes DOM, extractos OCR, controles de pestañas, descargas e inspección de red	compuertas de aprobación, encabezados de identidad del operador, eventos de auditoría, eliminación de PII, recibos Witness y perfiles de protección	MCP sobre HTTP, puente stdio incluido, API REST, Docker Compose, Codespaces, perfiles de autenticación y aislamiento opcional por sesión

Inicio Rápido

git clone https://github.com/LvcidPsyche/auto-browser.git
cd auto-browser
docker compose up --build

Eso es suficiente para el desarrollo local con la configuración predeterminada.

Opcional:

cp .env.example .env
make doctor

Ejecuta make doctor desde una terminal normal con acceso local a Docker y permiso para abrir sockets de localhost.

Abre:

Documentación de API: http://127.0.0.1:8000/docs
Panel del operador: http://127.0.0.1:8000/dashboard, que incluye la cola de acciones que esperan tu aprobación
Toma de control visual: http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale

Todos los puertos publicados se vinculan a 127.0.0.1 por defecto.

Pruébalo en Codespaces

Codespaces aprovisiona la pila automáticamente. Las pestañas del panel y noVNC suelen estar listas en unos 90 segundos.

Primera Demo Útil

El flujo de mayor señal en este repositorio es:

crear una sesión
iniciar sesión manualmente si el sitio necesita un humano
guardar la sesión como un perfil de autenticación con nombre
abrir una nueva sesión desde ese perfil de autenticación
continuar el trabajo sin volver a autenticarse

Empieza aquí:

Creación mínima de sesión:

curl -s http://127.0.0.1:8000/sessions \
  -X POST \
  -H 'content-type: application/json' \
  -d '{"name":"demo","start_url":"https://example.com"}' | jq

Observación mínima:

curl -s http://127.0.0.1:8000/sessions/<session-id>/observe | jq

Cambios Recientes

1.8.1

Sesiones y almacenes más robustos. Las acciones que se ejecutaron ya no se reportan como fallidas cuando la página navega justo después, una acción aprobada se ejecuta como máximo una vez, MAX_SESSIONS se mantiene bajo creaciones concurrentes, y las sesiones, pestañas, trabajos cron y los almacenes JSON ya no pierden ni filtran escrituras.
El puente MCP stdio sobrevive a un reinicio del controlador y reporta errores de autenticación y límite de velocidad en lugar de colgarse. El SDK, el puente y los adaptadores LangChain pueden enviar una identificación de operador para controladores con REQUIRE_OPERATOR_ID=true.
Acciones y observaciones más rápidas, menos viajes de ida y vuelta del navegador por observación, y una imagen del controlador sin las herramientas de prueba.
Correcciones de seguridad para el socket noVNC, el autocompletado TOTP, las rutas de perfiles de autenticación, las aprobaciones y los recibos Witness. create_session con totp_secret ahora necesita totp_hosts o un start_url.

1.8.0

Resultados más pequeños para agentes. Los resultados MCP se refieren a sesiones en lugar de repetir el registro completo de la sesión, y execute_action ya no devuelve la instantánea previa a la acción (detail="full" restaura ambas). Un resultado de acción es menos de la mitad de su tamaño anterior. La lista de herramientas predeterminada incluye las 20 herramientas que un agente de navegación necesita, y el resto están a un MCP_TOOL_PROFILE=full de distancia.
Los agentes pueden ver y leer. browser.screenshot y el ajuste preestablecido fast de observe devuelven la captura de pantalla como contenido de imagen MCP. browser.read_download lee un archivo CSV, JSON o de texto descargado. browser.get_html(text_only=true) está paginado y conserva los saltos de línea y las celdas de tabla.
Aprobaciones que puedes encontrar y en las que puedes confiar. El panel tiene una cola de aprobaciones pendientes con Aprobar y Rechazar. Una llamada de herramienta gobernada como browser.eval_js se aprueba por sus argumentos exactos, que el operador ve.
Las observaciones nombran las cosas como una persona las lee. Los campos se etiquetan desde su <label>, nunca desde lo que se escribió en ellos. El esquema de accesibilidad vuelve a funcionar en Playwright actual.
Una pasada de seguridad. La lista de permitidos de navegación ahora coincide con cómo Chromium analiza las URLs. Un controlador sin token rechaza los encabezados Host de enlace de DNS, los artefactos descargados se sirven en un entorno aislado, los enlaces compartidos están limitados y el navegador se ejecuta como un usuario sin privilegios.
Una imagen más ligera. El controlador omite las CLI de los proveedores (alrededor de 750 MB) a menos que se compile con INSTALL_AGENT_CLIS=true.

1.7.0 cerró los problemas de diseño fail-open de GHSA-xmh3-cw7j-9gp5. Una API accesible ahora necesita un token (API_BIND_SCOPE), la identidad del operador puede demostrarse con una credencial con nombre, los perfiles de autenticación pertenecen al operador que los guardó, y las habilidades escalonadas se verifican por firma al leer.

Consulta CHANGELOG.md para el historial completo de versiones.

Clientes MCP

Auto Browser expone:

un endpoint MCP HTTP en http://127.0.0.1:8000/mcp
endpoints de conveniencia en http://127.0.0.1:8000/mcp/tools y http://127.0.0.1:8000/mcp/tools/call
un puente stdio: uvx auto-browser-mcp desde PyPI, o scripts/mcp_stdio_bridge.py en un checkout del repositorio

Los clientes que hablan MCP sobre HTTP se conectan directamente. Con Claude Code:

claude mcp add --transport http auto-browser http://127.0.0.1:8000/mcp

Cursor, VS Code, tokens de portador y el emparejamiento de Auto Browser con un servidor MCP de búsqueda web se cubren en docs/mcp-clients.md.

El perfil de herramientas MCP predeterminado es curated: las 20 herramientas que un agente de navegación necesita (sesiones, observe y captura de pantalla, execute_action, lectura de páginas y descargas, pestañas, perfiles de autenticación, toma de control humana). Cada herramienta listada cuesta contexto del modelo en cada solicitud, por lo que las herramientas de diagnóstico, auditoría, arnés y administración están en el perfil completo. Para exponerlas, establece:

MCP_TOOL_PROFILE=full

Ejemplo de llamada de herramienta cruda:

curl -s http://127.0.0.1:8000/mcp/tools/call \
  -X POST \
  -H 'content-type: application/json' \
  -d '{
    "name":"browser.create_session",
    "arguments":{
      "name":"demo",
      "start_url":"https://example.com"
    }
  }' | jq

Guías de configuración de clientes:

Para ejemplos de listado de recursos, lecturas de recursos y actualizaciones de estilo suscripción, consulta docs/mcp-clients.md#resources-and-subscriptions.

Arnés de Convergencia

Auto Browser incluye un arnés de convergencia de Etapa 0 para la Inducción de Habilidades de Agente. Ejecuta un contrato de tarea estructurado, registra rastros verificados contra manipulación, verifica la finalización y escribe un candidato de habilidad escalonado con procedencia. Con una identidad de malla configurada, esa procedencia se firma, y el registro verifica la firma antes de servir un candidato — un candidato que falla la verificación, o que se dejó en el directorio de escalonamiento sin firmar, se rechaza. Los candidatos inducidos de una ejecución simulada se marcan como simulated para que no puedan pasar como convergidos. Las habilidades generadas solo se escalonan — la promoción permanece explícita y revisada.

Las herramientas del arnés — ejecuciones de convergencia, estado de ejecución y rastros, verificaciones de deriva, gestión de candidatos y graduación — están en el perfil de herramientas MCP full (MCP_TOOL_PROFILE=full), o se pueden invocar directamente sobre REST.

Empieza con docs/convergence-harness.md. Una prueba de humo local determinista es:

python -m controller.harness.run --contract evals/contracts/example_read.json --mock-final-url https://example.com --mock-final-text "Example Domain"

Para clientes MCP, establece MCP_TOOL_PROFILE=full para exponer las herramientas harness.*.

Seguridad y Cumplimiento

Para una implementación privada real, establece al menos:

APP_ENV=production
API_BIND_SCOPE=exposed
API_BEARER_TOKEN=<strong-random-secret>
REQUIRE_OPERATOR_ID=true
AUTH_STATE_ENCRYPTION_KEY=<44-char-fernet-key>
REQUIRE_AUTH_STATE_ENCRYPTION=true
SHARE_TOKEN_SECRET=<strong-random-secret>
CONTROLLER_ALLOWED_HOSTS=<controller hostname>
ALLOWED_HOSTS=<sites the browser may visit>
REQUEST_RATE_LIMIT_ENABLED=true
METRICS_ENABLED=true
STEALTH_ENABLED=false

Con APP_ENV=production el controlador se niega a iniciar mientras falte cualquiera de estos, y el registro de inicio nombra los que faltan.

Por defecto, cada sesión comparte un proceso de Chromium y un escritorio noVNC (SESSION_ISOLATION_MODE=shared_browser_node). Las cookies y el almacenamiento permanecen separados por sesión, pero un humano que toma el control de una sesión puede ver las ventanas de las demás. Cuando las sesiones pertenecen a diferentes personas, cuentas o dominios de confianza, comienza con make up-isolation para dar a cada sesión su propio contenedor de navegador y superficie de toma de control (docker_ephemeral). docs/session-isolation-audit.md tiene los detalles.

COMPLIANCE_TEMPLATE puede aplicar una postura preconfigurada al inicio:

Ajuste Preestablecido	Cifrado de Autenticación	ID del Operador	Eliminación de PII	Aislamiento	Edad Máxima de Sesión
`strict`	requerido	requerido	todas las capas	`docker_ephemeral`	4h
`balanced`	-	requerido	red + texto	compartido	24h

Ambos ajustes preestablecidos requieren aprobaciones de carga y habilitan los recibos Witness. El inicio escribe la política aplicada en /data/compliance-manifest.json. Los nombres heredados (HIPAA, SOC2, GDPR, PCI-DSS) todavía funcionan como alias obsoletos y emiten una advertencia al inicio.

Ejemplo:

COMPLIANCE_TEMPLATE=strict docker compose up

Para detalles de implementación, notas de Witness alojado, modos de autenticación CLI y orientación de SSH inverso, consulta:

Arquitectura de un Vistazo

flowchart LR
    User[Human operator] -->|watch / takeover| noVNC[noVNC]
    LLM[Any model: OpenAI / Claude / Gemini / OpenRouter / Grok / DeepSeek / MiniMax / local] -->|shared tools| Controller[Controller API]
    Controller -->|Playwright protocol| Browser[Browser node]
    noVNC --> Browser
    Browser --> Artifacts[(screenshots / traces / auth state)]
    Controller --> Artifacts
    Controller --> Policy[Allowlist + approval gates]

Proveedores de modelos

Adaptadores de primera clase para OpenAI, Claude y Gemini (API o CLI). Más allá de esos, un único adaptador genérico compatible con OpenAI impulsa cualquier modelo accesible a través de un endpoint /chat/completions de OpenAI — establece una clave de API para habilitarlo:

Proveedor	Alcanza
`openrouter`	una clave → ~casi todos los modelos de frontera (Claude, GPT, Gemini, Grok, DeepSeek, Llama, Mistral, Qwen, …)
`xai`	Grok
`deepseek`	DeepSeek (solo texto; impulsado desde el esquema DOM/accesibilidad)
`minimax`	MiniMax
`openai_compatible`	cualquier URL base personalizada — Ollama / vLLM / LM Studio autoalojados, Azure OpenAI, Together, Groq, Fireworks, …

La visión (capturas de pantalla) se usa para todos los proveedores excepto los de solo texto. Consulta .env.example para los ajustes *_API_KEY / *_BASE_URL / *_MODEL.

Componentes principales:

browser-node/ ejecuta Chromium, Xvfb, x11vnc y noVNC
controller/ expone el controlador FastAPI, el transporte MCP, las barreras de políticas y los endpoints de orquestación
data/ contiene artefactos de ejecución, estado de autenticación, aprobaciones, registros de auditoría y cachés opcionales de CLI
scripts/ contiene helpers locales para doctor, pruebas de humo, puentes y verificaciones de lanzamiento

Guía del Repositorio

Ruta	Qué Contiene
`controller/`	API del controlador, transporte MCP, pruebas y empaquetado
`browser-node/`	tiempo de ejecución del navegador y capa de conexión de Playwright
`examples/`	flujos de copiar y pegar y configuración del cliente MCP
`integrations/langchain/`	adaptadores de LangChain, LangGraph y CrewAI
`docs/`	documentación de arquitectura, despliegue, endurecimiento y lanzamiento
`scripts/`	doctor, arneses de humo, puente stdio y helpers de autenticación
`ops/`	plantillas de servicios de soporte y activos operativos

Comandos Comunes

Comando	Propósito
`make help`	listar comandos disponibles del repositorio
`make lint`	ejecutar verificaciones de Ruff en todo el repositorio
`make test`	ejecutar pruebas del controlador en Docker
`make test-local`	ejecutar pruebas del controlador en Python 3.11+ del host
`make eval`	ejecutar la puntuación determinista de evaluación de proveedor/perfil
`make doctor`	ejecutar la prueba de humo de preparación local
`make release-audit`	ejecutar la pasada completa de validación de lanzamiento
`make smoke-isolation`	verificar el aislamiento de Docker por sesión
`make smoke-reverse-ssh`	verificar el acceso remoto por SSH inverso

Mapa de Documentación

Si Quieres...	Empieza Aquí
entender la forma del sistema	`docs/architecture.md`
conectar Claude Desktop o Cursor	`docs/mcp-clients.md`
ejecutar los ejemplos primero con curl	`examples/README.md`
desplegar en un host de confianza	`docs/deployment.md`
revisar las restricciones de producción	`docs/production-hardening.md`
ejecutar el arnés de convergencia	`docs/convergence-harness.md`
inspeccionar el historial de lanzamientos	`CHANGELOG.md`
ver hacia dónde se dirige el proyecto	`ROADMAP.md`

Contribuciones

Si quieres ayudar, empieza con:

Si Auto Browser es útil, una estrella ayuda a que otras personas lo encuentren. Las opciones de patrocinio y propinas están en TIPS.md.