Invictum Browser Bridge

Control de navegador de código abierto para agentes de IA, creado para desarrolladores.

Invictum Browser Bridge (IBB, también llamado Invictum Browser Gate o IBG) permite que un agente de IA autorizado trabaje en el perfil existente de Google Chrome del usuario. El agente puede usar aplicaciones web en las que ya se haya iniciado sesión sin exportar cookies, contraseñas, perfiles de navegador ni estado de autenticación sin procesar.

El proyecto está licenciado bajo la Licencia MIT. Está diseñado para el desarrollo local y flujos de trabajo avanzados de navegador a través de MCP, una CLI, un SDK de TypeScript o la API de control de loopback.

Demostración en vídeo

Ver la demostración completa de Invictum Browser Bridge en YouTube para ver a un agente de IA trabajar dentro de un perfil real de Chrome, comprender semánticamente un sitio web público, navegar por su contenido, probar una vista móvil y crear capturas de pantalla de página completa y anotadas mientras mantiene la pestaña controlada visible y explícitamente reservada.

Related MCP server: browser-control

¿Por qué usarlo?

La mayoría de la automatización de navegadores inicia un perfil de navegador limpio o se basa en coordenadas de pantalla frágiles. IBB, en cambio, proporciona acciones tipadas y verificadas por políticas dentro del perfil real de Chrome del usuario:

• lectura semántica de páginas y referencias deterministas a elementos;

• control de pestañas en segundo plano que evita interrumpir al usuario;

• adaptadores específicos para WordPress, terminales WHM/cPanel y Figma;

• formularios fiables, editores de texto enriquecido/código, subidas, diálogos, capturas de pantalla y herramientas de depuración;

• autorización explícita, reserva por pestaña, User Stop, datos de auditoría redactados y limpieza garantizada.

La extensión instalada informa de sus capacidades exactas en tiempo de ejecución. Los agentes deben llamar siempre a system.capabilities en lugar de asumir que la documentación y la compilación de Chrome cargada son idénticas.

Características principales

Control del navegador y de la página

• Enumerar, abrir, cerrar, navegar, activar y moverse por el historial de pestañas.

• Trabajar en una ventana de agente dedicada y en pestañas en segundo plano por defecto.

• Esperar a que se cumplan URLs, títulos, texto, selectores, estabilidad del DOM o preparación de la aplicación; enfocar una pestaña de renderizado diferido solo una vez cuando una espera en segundo plano acotada demuestra que el enfoque es necesario.

• Leer instantáneas semánticas compactas, esquemáticas, completas, interactivas o acotadas.

• Extraer texto limpio o Markdown ligero y encontrar elementos con clasificación determinista en lenguaje natural.

• Hacer clic, doble clic, clic con el botón derecho, pasar el cursor, enfocar, escribir, pulsar teclas, seleccionar, marcar, desplazarse hasta un elemento o posición del documento, y arrastrar y soltar.

• Usar clics por coordenadas solo como recurso de reserva vinculado a una revisión.

Formularios, editores, archivos y autenticación

• Establecer valores en entradas nativas, áreas de texto, selectores, casillas de verificación, botones de opción, regiones contenteditable y editores WYSIWYG.

• Sincronizar CodeMirror, Ace, Monaco, Quill, TinyMCE, Gutenberg y modelos de editor autoritativos similares para que los valores sobrevivan al envío.

• Adjuntar uno o más archivos locales a través de la API nativa de entrada de archivos de Chrome sin exponer rutas en los resultados ni en los registros de auditoría.

• Enviar formularios solo con la autorización requerida, incluida una ruta sin avisos explícitamente autorizada para una instrucción de agente ya aprobada.

• Usar formularios de inicio de sesión precumplimentados, autenticación HTTP Basic efímera y diálogos nativos de JavaScript alert, confirm, prompt y beforeunload mediante acciones dedicadas.

Soporte para WordPress

IBB incluye flujos de trabajo tipados para WordPress en lugar de pedir a los agentes que improvisen con cambios cosméticos en el DOM o arrastres por coordenadas:

• identificar pantallas de wp-admin, avisos, tablas de listas, filas y acciones disponibles;

• realizar acciones de fila y acciones masivas con claves de acción exactas de WordPress;

• leer y actualizar el contenido de Gutenberg o el Editor Clásico, título, extracto, slug, estado, categorías, etiquetas, metadatos de imagen destacada y otros campos admitidos;

• revisar los cambios por separado del guardado y verificar el modelo de editor autoritativo después de guardar;

• inspeccionar y editar árboles clásicos de Apariencia > Menús, incluidos enlaces personalizados, actualizaciones, eliminaciones, movimientos de subárbol completo, anidamiento, ordenación y guardado;

• recuperarse de forma segura cuando el aviso de cambios sin guardar de WordPress bloquea la navegación;

• recurrir a herramientas generales de formularios, subidas, editor, DOM, consola y API de mismo origen para ajustes de plugins, medios, controles similares a ACF y páginas de administración personalizadas.

Consulta WordPress wp-admin y edición clásica de menús.

WHM, cPanel y terminales en el navegador

El adaptador tipado xterm admite terminales alojados en el navegador, como WHM/cPanel Terminal:

• detectar el terminal real en lugar del campo Search Tools de WHM;

• leer un búfer xterm acotado y redactado o un WebSocket de terminal local a la acción;

• enfocar solo la entrada auxiliar del terminal y enviar texto confiable o teclas especiales en una pestaña en segundo plano;

• preparar y verificar el comando exacto antes de enviar un solo Enter;

• fallar en modo cerrado, retener el Enter e intentar borrar un borrador no verificado;

• esperar un prompt, texto, cambio de salida o estado de reposo;

• devolver verificación explícita del borrador y de la entrega sin registrar comandos ni salida sin procesar.

La salida del terminal es R2 y cada acción de texto/tecla es R3. Una solicitud de solo lectura nunca autoriza un comando. Consulta automatización de terminales.

Figma en Chrome

Las acciones tipadas de Figma pueden inspeccionar la interfaz del navegador alrededor de un archivo de diseño:

• comprobar el estado de los anclajes esperados de la interfaz de Figma;

• leer el nombre del archivo, las páginas, el modo actual y la selección actual;

• leer las filas renderizadas del árbol de capas y las propiedades del inspector;

• seleccionar una página, un modo o una capa visible con protección contra filas obsoletas;

• usar capturas de pantalla para el lienzo WebGL.

Figma virtualiza su árbol de capas y pinta el lienzo de diseño con WebGL, por lo que este adaptador no pretende, deliberadamente, ofrecer mutación completa del documento. Consulta soporte de Figma.

Diagnósticos de desarrollador y salida visual

• Captura de consola acotada y redactada y diagnósticos de red solo con metadatos.

• Solicitudes de API de página del mismo origen con manejo opcional de nonces de WordPress.

• Emulación reversible de viewport móvil, orientación, DPR y táctil.

• Capturas de pantalla de viewport, elemento, región y página completa.

• Capturas de pantalla de tutorial con rectángulos, elipses, flechas, etiquetas y superposiciones automáticas numeradas de conjunto de marcas.

• Inspección de elementos/oyentes/fuentes, observación acotada de eventos, mutación tipada del DOM y de estilos en línea, inyección reversible de CSS y exportación acotada de PDF.

• JavaScript de página sin procesar explícitamente autorizado como último recurso R3; las superficies sensibles, de navegación, envío y red sin restricciones permanecen denegadas.

• Lotes secuenciales que preservan las políticas, ejecuciones de prueba, claves de idempotencia, instantáneas posteriores, deltas semánticos del DOM, verificación y reubicación de referencias obsoletas.

Integraciones con agentes

IBB expone cuatro superficies locales para desarrolladores:

El transporte Native Host en 127.0.0.1:47821 pertenece exclusivamente a Desktop Authority. Los agentes no deben conectarse directamente a la extensión ni a ese puerto.

El servidor expone actualmente 54 acciones de navegador en tiempo de ejecución y 61 herramientas MCP. Ese número es una instantánea de la versión, no un contrato para el agente: llama a invictum_capabilities en tiempo de ejecución.

Modelo de seguridad

• Desktop Authority es el único límite de políticas y auditoría.

• Cada acción se clasifica como R0-R3; las acciones sensibles requieren una aserción de autorización explícita y coincidente.

• Una pestaña se reserva antes de trabajar, se marca visiblemente con la identidad del agente y se libera en finally. El usuario puede detener el control inmediatamente.

• Las referencias a elementos están vinculadas a revisiones del documento y del DOM.

• Las instantáneas redactan valores sensibles; las subidas, los comandos de terminal, las credenciales, el texto de los avisos y los cuerpos de respuesta no se escriben en los registros de auditoría.

• Las páginas internas del navegador, las extensiones, DevTools, Chrome Web Store, los archivos locales y otras superficies restringidas permanecen no disponibles.

• El trabajo en segundo plano es el predeterminado. Los agentes no deben solicitar la activación en primer plano a menos que la aplicación realmente lo requiera.

• El acceso al depurador está acotado a la pestaña y es limitado. Los adaptadores persistentes liberan su concesión al detenerse, restablecerse, desbloquearse, navegar o en la limpieza tras un fallo.

IBB no expone cookies, contraseñas guardadas, datos de autocompletado, almacenamiento arbitrario del navegador, descargas sin restricciones, cuerpos de solicitud/respuesta pasivos, interceptación de tráfico, entrada confiable a nivel de sistema operativo ni control remoto.

Lee SECURITY.md y POLICY_CONFIGURATION.md antes de ampliar la superficie de acciones.

Arquitectura

AI agent
  |  MCP / CLI / TypeScript SDK / local control API
  v
Desktop Authority :47820
  |  policy -> validation -> reservation -> audit -> cleanup
  v
Native Host -> private loopback WebSocket :47821
  v
Chrome MV3 extension -> typed page/CDP adapters -> authorized tab

Consulta ARCHITECTURE.md para conocer los límites de confianza y los contratos de transporte.

Requisitos

• Windows 11 x64

• Google Chrome 120+

• Node.js 22+

• pnpm 11

• Git

El repositorio incluye actualmente una instalación de desarrollo basada en el código fuente, no un paquete firmado de Chrome Web Store ni un instalador de producción.

Inicio rápido

git clone https://github.com/invictumhr/ai-invictum-browser-bridge.git
Set-Location .\ai-invictum-browser-bridge
$env:CI = 'true'
pnpm install --frozen-lockfile
pnpm build
pnpm typecheck
pnpm test
pnpm lint

Carga apps/extension/dist a través de chrome://extensions como extensión sin empaquetar, copia el ID de extensión generado y registra el Native Host:

.\scripts\register-native-host-dev.ps1 -ExtensionId "PASTE_EXTENSION_ID"
pnpm browser ping
pnpm browser capabilities

Establece el Acceso al sitio de Chrome de la extensión en En todos los sitios. Esto evita una aprobación manual en la barra de herramientas para cada nuevo origen HTTP(S); la política de Chrome y el modelo de autorización propio del Bridge siguen aplicándose.

Las instrucciones completas están en INSTALL_WINDOWS.md y EXTENSION_INSTALL.md.

Instalación con un agente de IA en Windows

Copia el siguiente prompt en un agente de codificación de IA de confianza que tenga acceso a PowerShell en el equipo Windows. El agente puede instalar y compilar el entorno de ejecución local, pero Chrome requiere algunas acciones visibles del usuario para una extensión sin empaquetar. Por lo tanto, el prompt le indica al agente exactamente cuándo debe pausar y guiar al usuario.

Desktop Authority es el proceso local que acepta comandos de los agentes en 127.0.0.1:47820; el Native Host actúa de intermediario entre este y la extensión de Chrome en 127.0.0.1:47821. La instalación admitida no crea un servicio permanente de Windows. MCP y la CLI inician Desktop Authority como un demonio local oculto cuando es necesario, mientras que Chrome inicia el Native Host registrado. No expongas ninguno de los dos puertos ni crees una regla de firewall.

Install Invictum Browser Bridge from the public repository on this Windows PC:

https://github.com/invictumhr/ai-invictum-browser-bridge.git

Your goal is to install the complete supported local chain:

AI client -> MCP/CLI -> Desktop Authority -> Native Host -> Chrome extension

Work autonomously wherever PowerShell can do the work. Guide me step by step
only for actions Chrome requires me to perform manually. Explain each manual
step in one short message, wait for my confirmation or the extension ID, and
then continue. Do not ask me to execute commands that you can safely execute.

Safety rules:

1. Use only the public repository above and the scripts checked into it.
2. Do not request, copy, print, or store Chrome passwords, cookies, tokens,
   browser-profile files, or browsing data.
3. Do not disable Chrome security, install an unrelated extension, expose a
   loopback port, create a firewall rule, or bind any service publicly.
4. Do not invent a Windows Service or Scheduled Task. This project intentionally
   auto-starts Desktop Authority through MCP/CLI and lets Chrome start the Native
   Host.
5. Do not overwrite an existing checkout. If the target directory exists,
   inspect its Git remote and working tree first. Continue only if it is this
   repository and existing changes are safe; otherwise choose a new directory.
6. Avoid administrator elevation unless a missing prerequisite genuinely
   requires it. Native Host registration itself is per-user under HKCU.
7. Never work around a failed test, Chrome permission, or Native Messaging
   error. Diagnose it and preserve the security model.

Perform these phases:

PHASE 1 — Preflight

- Use PowerShell.
- Check Windows version and availability/versions of Git, Google Chrome,
  Node.js, npm/Corepack, and pnpm.
- Require Node.js 22 or newer and pnpm 11. Use the pnpm version declared in the
  repository package.json.
- If a prerequisite is missing, explain what is missing. Install it through an
  official source or winget only when installation is within my request; report
  any UAC/manual step before continuing.
- Resolve a normal per-user installation directory. Default to
  %USERPROFILE%\invictum-browser-bridge unless I already selected another path.

PHASE 2 — Clone, inspect, install, and build

- Clone the repository with:
  git clone https://github.com/invictumhr/ai-invictum-browser-bridge.git
- Enter the repository and verify that origin points to that repository.
- Read README.md, INSTALL_WINDOWS.md, EXTENSION_INSTALL.md, SECURITY.md, and
  AGENT_USAGE.md before installation.
- Run the repository secret scan before installation.
- Set CI=true for the install and run:
  pnpm install --frozen-lockfile
  pnpm build
  pnpm typecheck
  pnpm test
  pnpm lint
- Stop and diagnose any failed gate. Do not continue with a partial build.
- Resolve and show me the exact absolute folder I will need in Chrome:
  <repository>\apps\extension\dist
- Copy that folder path to the Windows clipboard if possible.

PHASE 3 — Guide me through loading the Chrome extension

Pause and ask me to do exactly this:

1. Open Google Chrome and go to chrome://extensions.
2. Turn on Developer mode in the top-right corner.
3. Click Load unpacked.
4. Select the exact apps\extension\dist folder you resolved above.
5. Confirm that Invictum Browser Controller appears and is enabled.
6. Copy its 32-character extension ID and send only that ID back to you.

Do not guess or hardcode the extension ID. Validate that the value I provide
matches Chrome's unpacked-extension ID format before using it.

PHASE 4 — Register the local Native Host

- From the repository root, run:
  .\scripts\register-native-host-dev.ps1 -ExtensionId "THE_ID_I_PROVIDED"
- Confirm that the script created the per-user Native Messaging registration
  for com.invictum.browser_bridge and did not expose a network port.
- If the Windows C# compiler needed by the checked-in launcher is unavailable,
  report that exact blocker; do not download or execute an unverified launcher.

PHASE 5 — Finish Chrome configuration

Pause and guide me through these steps:

1. Return to chrome://extensions.
2. Click Reload on Invictum Browser Controller once.
3. Open Details for the extension.
4. Set Site access to On all sites.
5. Confirm the extension remains enabled and has no current error.
6. Optionally pin its toolbar icon so the ON/AI status and settings are easy to
   see.

Explain that On all sites prevents a new manual approval for every HTTP(S)
domain, but does not bypass Chrome policy, restricted pages, User Stop, or IBB's
own authorization rules. Wait for my confirmation before testing.

PHASE 6 — Start and verify the bridge

- Run pnpm browser health.
- Run pnpm browser ping. The CLI should automatically start Desktop Authority
  as a hidden local daemon if it is offline.
- Run pnpm browser capabilities.
- Verify that Desktop Authority is reachable only through 127.0.0.1:47820, the
  private Native Host transport uses 127.0.0.1:47821, nativeConnected is true,
  and the loaded extension returns its runtime capabilities.
- Treat runtime capabilities as authoritative. The current source expects 54
  browser actions and the built MCP server expects 61 tools, but do not hide a
  mismatch or force those numbers if the checked-out release differs.
- If the badge briefly shows ON and disconnects, diagnose Desktop Authority,
  the HKCU Native Messaging manifest, its allowed extension ID, the built Native
  Host paths, and extension errors. Rebuild/reregister/reload only the component
  that is stale.
- Do not ask for a second extension reload unless extension files or its Native
  Host registration actually changed.

PHASE 7 — Configure AI clients

- Ask whether I want global IBB/IBG discovery for installed AI clients. If yes,
  run:
  powershell -ExecutionPolicy Bypass -File
  .\scripts\install-agent-discovery.ps1
- This should preserve unrelated Codex, Cursor, and Claude configuration.
- Tell me to start a new AI-agent session after MCP registration changes.
- Verify with a harmless request that performs only IBB ping and capabilities;
  do not open a browser tab for this verification.

PHASE 8 — Final report

Report:

- repository installation path and checked-out revision;
- Node.js and pnpm versions;
- build/typecheck/test/lint results;
- Chrome extension ID and loaded dist path (the ID is not a secret);
- Native Host registration status;
- Desktop Authority health and nativeConnected state;
- runtime action count and MCP tool count;
- which AI clients were configured;
- whether any manual action or known limitation remains.

Do not claim success until ping and capabilities work through the normal local
authority. Do not use a temporary test harness that takes over port 47821.

Configurar agentes de IA

Después de pnpm build, instala los registros MCP y las reglas de activación para los agentes locales admitidos:

powershell -ExecutionPolicy Bypass -File .\scripts\install-agent-discovery.ps1

Las frases use IBB, use IBG, use Invictum Browser Bridge y use Invictum Browser Gate (además de sus equivalentes en croata) seleccionan este Bridge. Inicia una nueva sesión de agente después de cambiar un registro MCP.

Consulta configuración de MCP, descubrimiento de agentes y el compacto contrato de activación de agentes.

Flujo de trabajo recomendado para agentes

ping -> capabilities -> open/navigate in background -> identify agent -> wait
     -> outline/snapshot -> find -> typed action -> verify -> unlock in finally

Prefiere las acciones tipadas y las referencias semánticas. Usa capturas de pantalla para la comprensión visual, las coordenadas solo como recurso de reserva y JavaScript sin procesar únicamente cuando el usuario lo haya autorizado explícitamente y ninguna acción tipada más segura pueda resolver la tarea.

La guía de uso completa está en AGENT_USAGE.md.

Documentación

Empieza con el índice de documentación. Las guías importantes incluyen:

• Desarrollo y controles de calidad

• Solución de problemas

• wp-admin de WordPress

• Menús clásicos de WordPress

• Automatización de terminal WHM/cPanel

• Figma en Chrome

• Carga de archivos

• DOM avanzado, CSS, eventos y JavaScript

• Capturas de pantalla y anotaciones de tutoriales

• Autenticación y diálogos nativos

• Ergonomía de MCP

Estructura del repositorio

apps/
  cli/           JSON CLI and authority auto-start
  desktop/       policy/audit authority and loopback control API
  extension/     Manifest V3 Chrome controller
  mcp/           stdio MCP adapter
  native-host/   Native Messaging stdio <-> private local WebSocket
packages/
  agent-sdk/     control client and reserved-tab lifecycle helpers
  audit-log/     redacted audit contract and development sink
  policy-engine/ fail-closed action classification
  protocol/      strict IBP schemas and factories
  shared-types/  transport-neutral contracts
tests/
  fixtures/      deterministic local browser pages
  integration/   emulated transport and real-Chrome smoke tests

Contribuciones

Las issues y las pull requests son bienvenidas. Mantén las políticas, la validación, la auditoría, la reserva y la limpieza en la ruta de Desktop Authority; no añadas una segunda ruta de control a la extensión. Ejecuta todos los controles locales antes de abrir una pull request y sigue CONTRIBUTING.md.

Utiliza los formularios estructurados de GitHub para informes de errores y solicitudes de funciones. Lee SUPPORT.md para obtener orientación diagnóstica y CODE_OF_CONDUCT.md antes de participar. Los problemas de seguridad deben utilizar el informe privado de vulnerabilidades, no una issue pública.

Antes de publicar cambios, utiliza la lista de comprobación de datos privados de GIT_PUBLISHING.md.

Licencia

Invictum Browser Bridge es un software de código abierto licenciado bajo la Licencia MIT. Puedes usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y vender copias con sujeción a los términos de la licencia.

Hecho por invictum.hr