Auto-Browser

Auto Browser

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 Desktop
• Cursor
• cualquier cliente MCP que pueda hablar HTTP o stdio
• llamadas REST directas cuando quieras control curl-first

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 acoplarse a posteriori.
• 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 frescas 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.
• Rieles de seguridad integrados. Aprobaciones, identidad del operador, limpieza de PII, recibos Witness y presets 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 habilidad 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 verificador y graduación solo de revisión — agentes que demuestran que pueden repetirse correctamente, no solo actuar una vez.

Destacados de la versión (v1.5.0)

• Lee una página sin pagar por píxeles. El nuevo preset de observación text devuelve el esquema de accesibilidad, texto extraído e interactivos sin captura de pantalla ni OCR — la forma más económica para que un agente lea una página. Establece PERCEPTION_PRESET_DEFAULT=text para convertirlo en un valor predeterminado en toda la implementación.
• Encuentra una cadena en la página en una sola llamada. browser.find_elements ahora acepta un query (texto plano o regex, sin distinción de mayúsculas) en lugar de un selector CSS y devuelve cada coincidencia con contexto circundante — no se necesita una observación completa para verificar un valor.
• Errores sobre los que los agentes pueden actuar. Los argumentos de herramienta no válidos reportan detalles a nivel de campo, los mensajes del manejador pasan en lugar de un fallo genérico, y el error de arranque en frío del puente MCP ahora dice exactamente cómo iniciar el controlador.
• Cualquier modelo compatible con OpenAI puede manejar el navegador. Un único adaptador genérico sirve a cada modelo accesible a través de un endpoint OpenAI /chat/completions. Nuevos proveedores: openrouter (una clave → ~cada modelo fronterizo), xai (Grok), deepseek, minimax y openai_compatible (URL base personalizada para Ollama / vLLM / LM Studio autoalojados, Azure, Together, Groq, Fireworks, …). Visión + llamada de funciones con un respaldo de análisis de contenido para endpoints que ignoran tool_choice.
• Recurso MCP browser://audit/events. Lista y lee eventos de auditoría recientes entre sesiones directamente a través de MCP.
• Paridad de Playwright aplicada en CI. Las versiones de Playwright del controlador (pip) y del nodo del navegador (npm) deben coincidir exactamente — un aumento de un solo lado ya no puede fusionarse y causar bucles de fallo en las implementaciones de compose.
• En PyPI. pip install auto-browser-client para el SDK, pip install auto-browser-langchain para los adaptadores LangChain/LangGraph/CrewAI y uvx auto-browser-mcp para ejecutar el puente MCP stdio con cero configuración. Las versiones se publican a través de publicación confiable de PyPI (OIDC) al empujar etiquetas.

Desde v1.3.0

• browser_manager.py ahora es una fachada pura + raíz de composición (1,284 → 769 líneas), con lógica de dominio extraída en app/browser/services/.
• Las exportaciones de estado de fork están cifradas en reposo y el estado de navegación en sombra nunca toca el disco.
• Las tareas de captura de descargas ya no pueden ser recolectadas como basura a mitad de vuelo, los fallos de navegación en sombra se revierten limpiamente y los oyentes de página sobreviven a la reutilización de ID de objeto.
• Compuertas de versión en CI aplican auditorías de dependencias, evaluaciones de fixtures, pruebas de cliente, compilaciones de ruedas de Python y la compuerta de cobertura del controlador al 80% en Python 3.11 y 3.14.

Consulta CHANGELOG.md para el historial completo de versiones.

Buenos casos de uso

• paneles internos y herramientas de administración
• QA asistido por operador y depuración de navegador
• flujos de trabajo 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 búsquedas 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, limpieza 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
• 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:

1. crea una sesión
2. inicia sesión manualmente si el sitio necesita un humano
3. guarda la sesión como un perfil de autenticación con nombre
4. abre una nueva sesión desde ese perfil de autenticación
5. continúa el trabajo sin volver a autenticarte

Empieza aquí:

• examples/login-and-save-profile.md
• examples/README.md

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

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

El perfil de herramientas MCP predeterminado es curated, que mantiene la superficie del navegador compacta para una mejor selección de herramientas. Si quieres la superficie completa de herramientas internas, 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:

• docs/mcp-clients.md
• examples/claude-desktop-setup.md
• examples/cursor-mcp-setup.md
• examples/claude_desktop_config.json

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ó caer en el directorio de escalonamiento sin firmar, es rechazado. Los candidatos inducidos de una ejecución simulada se marcan como simulated para que no puedan pasar como convergidos. Las habilidades generadas se escalonan solo — la promoción permanece explícita y revisada.

Las herramientas de inspección de solo lectura (harness.list_runs, harness.get_status, harness.get_trace) se exponen en el perfil de herramientas MCP predeterminado curated para que los agentes puedan inspeccionar el estado del arnés sin acceso elevado. Las ejecuciones de convergencia, verificaciones de deriva, gestión de candidatos y graduación requieren MCP_TOOL_PROFILE=full, o se pueden invocar directamente a través de REST.

Empieza con docs/convergence-harness.md. Una prueba 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
REQUEST_RATE_LIMIT_ENABLED=true
METRICS_ENABLED=true
STEALTH_ENABLED=false

COMPLIANCE_TEMPLATE puede aplicar una postura preconfigurada al inicio:

Preset	Cifrado de autenticación	ID del operador	Limpieza 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 presets requieren aprobaciones de carga y habilitan recibos Witness. El inicio escribe la política aplicada en /data/compliance-manifest.json. Los nombres heredados (HIPAA, SOC2, GDPR, PCI-DSS) aún 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 guía de SSH inverso, consulta:

• docs/deployment.md
• docs/production-hardening.md

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 maneja cualquier modelo accesible a través de un endpoint OpenAI /chat/completions — establece una clave de API para habilitarlo:

Proveedor	Alcanza
openrouter	una clave → ~cada modelo fronterizo (Claude, GPT, Gemini, Grok, DeepSeek, Llama, Mistral, Qwen, …)
xai	Grok
deepseek	DeepSeek (solo texto; manejado 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 cada proveedor excepto los de solo texto. Consulta .env.example para la configuración de *_API_KEY / *_BASE_URL / *_MODEL.

Componentes principales:

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

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 Playwright
examples/	flujos de copiar y pegar y configuración de clientes MCP
integrations/langchain/	adaptadores LangChain, LangGraph y CrewAI
docs/	arquitectura, implementación, endurecimiento y documentos de lanzamiento
scripts/	doctor, arneses de humo, puente stdio y ayudantes de autenticación
ops/	plantillas de servicios de soporte y activos operativos

Comandos comunes

Comando	Propósito
make help	lista los comandos disponibles del repositorio
make lint	ejecuta comprobaciones de Ruff en la app, las pruebas y los scripts auxiliares
make test	ejecuta las pruebas del controlador en Docker
make test-local	ejecuta las pruebas del controlador en Python 3.10+ del host
make eval	ejecuta la evaluación determinista de proveedores/perfiles
make doctor	ejecuta la prueba de humo de preparación local
make release-audit	ejecuta el pase completo de validación de lanzamiento
make smoke-isolation	verifica el aislamiento de Docker por sesión
make smoke-reverse-ssh	verifica 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 con curl primero	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 versiones	CHANGELOG.md
ver hacia dónde se dirige el proyecto	ROADMAP.md

Contribuciones

Si quieres ayudar, empieza con:

• CONTRIBUTING.md
• docs/good-first-issues.md
• CODE_OF_CONDUCT.md

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