Project Tendril

Un navegador Chromium local-first y un runtime de investigación web diseñado para agentes de IA.

Project Tendril ofrece a los clientes MCP y agentes autónomos un proceso Chromium real y aislado con instantáneas semánticas eficientes en tokens, acciones de navegador basadas en refs, extracción de páginas renderizadas, búsqueda, investigación, rastreo, capturas de pantalla, PDF, diagnósticos y acceso autenticado al Chrome DevTools Protocol.

Se ejecuta localmente, no incluye un LLM integrado, no envía telemetría y nunca se adjunta a tu perfil de navegador cotidiano.

[!IMPORTANT] Project Tendril no disfraza la automatización, no evade muros de pago ni fabrica cookies de autorización. Detecta páginas de desafío comunes y puede proporcionar una transferencia con ventana visible y supervisión humana para accesos legítimos. La resolución automatizada de desafíos se admite como capacidad local opcional; consulta Gestión de desafíos para más detalles.

Contenido

• ¿Por qué Project Tendril?

• Características

• Cómo funciona

• Requisitos

• Inicio rápido

• Conectar un cliente MCP

• Herramientas MCP

• REST y CDP

• Búsqueda, investigación y rastreo

• Transferencia de desafíos a humanos

• Configuración

• Modelo de seguridad

• Docker

• Desarrollo

• Solución de problemas

• Estado del proyecto y hoja de ruta

• Contribuciones

¿Por qué Project Tendril?

La mayoría de las integraciones de navegador ofrecen al agente capturas de pantalla en bruto o un DOM grande e inestable. Project Tendril añade una capa orientada a agentes sobre Chromium:

• Compatibilidad real con navegadores — JavaScript, cookies, formularios, descargas, marcos, PDF y renderizado moderno se ejecutan en Chromium.

• Estado semántico compacto — las instantáneas basadas en accesibilidad exponen roles, nombres, valores y refs de elementos de corta duración sin devolver el código fuente completo de la página.

• Acciones deterministas — los agentes actúan sobre refs de la instantánea más reciente; los refs obsoletos fallan en lugar de seleccionar silenciosamente el elemento incorrecto.

• Evidencia web útil — la búsqueda, la extracción de páginas renderizadas y la investigación de múltiples fuentes devuelven URLs estructuradas y evidencia no confiable sin ocultar un LLM en la capa del navegador.

• Aislamiento de procesos — cada sesión de Tendril posee un proceso Chromium, un directorio de perfil, un endpoint CDP y un proxy de red.

• Múltiples interfaces — usa MCP stdio, MCP HTTP Streamable, REST autenticado, CDP en bruto, la CLI o el panel de control local.

• Control local — los perfiles, cookies, descargas, procesos del navegador y registros permanecen en la máquina que ejecuta Tendril.

Project Tendril se inspira en las ideas arquitectónicas del anuncio de Kitesurf de Cloudflare: sesiones nuevas, acceso saliente centralizado, representaciones estructuradas del navegador, fallos acotados y workers desechables. Project Tendril es una implementación independiente, usa Chromium local y no contiene código fuente de Cloudflare.

Características

Automatización del navegador

• Proceso Chromium dedicado y directorio de datos de usuario por sesión.

• Sesiones efímeras por defecto; perfiles nombrados opcionales para inicios de sesión duraderos.

• Múltiples páginas por sesión con operaciones de abrir, listar, seleccionar y cerrar.

• Historial de navegación, recarga, estados de carga configurables y esperas acotadas.

• Acciones de clic, doble clic, pasar el cursor, enfocar, rellenar, escribir, seleccionar, marcar, pulsar, desplazar, arrastrar y subir archivos.

• Diálogos de JavaScript, cookies, almacenamiento, permisos, geolocalización, modo sin conexión, viewport, zona horaria, locale, preferencias multimedia, cabeceras y credenciales HTTP.

• Capturas de pantalla de página completa, viewport y elementos, además de salida PDF.

• Eventos de consola acotados, metadatos de solicitud/respuesta, cuerpos de respuesta, descargas y evaluación de JavaScript limitada a la página.

Comprensión de páginas orientada a agentes

• Instantáneas semánticas interactivas, completas, de lectura y diferenciales.

• Refs de elementos cortos vinculados a una página, marco, URL e instantánea específicos.

• Paginación de instantáneas y límites de salida para un uso predecible del contexto.

• Extracción con Mozilla Readability y conversión de HTML a Markdown.

• Enlaces, metadatos, formularios y tablas estructurados.

• Marcadores explícitos untrustedContent: true y advertencias heurísticas de inyección de prompts.

Descubrimiento web

• Búsqueda impulsada por Chromium con adaptadores de Bing, DuckDuckGo, Google y SearXNG opcional.

• Respaldo automático de proveedor cuando un proveedor falla o desafía al navegador.

• Investigación de múltiples consultas con deduplicación de URLs y evidencia atribuida por fuente.

• Rastreo acotado, cancelable y consciente de robots.txt con controles de mismo origen y profundidad.

Interfaces y operaciones

• MCP sobre stdio para una propiedad local simple del cliente.

• MCP HTTP Streamable sin estado para un servicio compartido de larga duración.

• API REST autenticada para acciones rápidas y sesiones.

• WebSockets CDP en bruto autenticados para clientes Playwright, Puppeteer, DevTools y CDP.

• Panel de control local de observación y control.

• Diagnósticos de runtime, registro estructurado, gestión de perfiles, empaquetado Docker y CI.

Cómo funciona

flowchart LR
    A[AI agent or MCP client] -->|stdio MCP| M[MCP server]
    A -->|Bearer-authenticated HTTP| H[HTTP service]
    C[CDP client] -->|Authenticated WebSocket| H
    U[Local operator] -->|Dashboard| H

    M --> B[BrowserManager]
    H --> B
    B --> S1[Tendril session]
    B --> S2[Tendril session]

    S1 --> P1[Per-session egress proxy]
    S1 --> R1[Dedicated Chromium process]
    S2 --> P2[Per-session egress proxy]
    S2 --> R2[Dedicated Chromium process]

    P1 --> W[Public web]
    P2 --> W

Para cada sesión, Project Tendril:

1. Crea un directorio efímero o bloquea un perfil explícitamente nombrado.

2. Inicia un proxy de reenvío en loopback con la política de red de esa sesión.

3. Lanza un proceso Chromium separado con un puerto CDP aleatorio en loopback.

4. Conecta Playwright a través de CDP para el control de alto nivel del navegador.

5. Registra observadores acotados de navegador, consola, red, descargas, fallos, páginas y diálogos.

6. Termina el grupo de procesos completo y elimina el estado efímero cuando la sesión se cierra.

Este modelo de proceso por sesión usa más memoria que la agrupación de contextos de navegador, pero evita que agentes no relacionados compartan cookies, caché, service workers, estado de extensiones o un límite de fallos del navegador.

Consulta Arquitectura para detalles de implementación.

Requisitos

• Node.js 22.19 o más reciente

• Chromium, Google Chrome o Chromium gestionado por Playwright

• Un usuario no root con un sandbox de Chromium funcional

Linux es la plataforma v1.0 completamente probada. Project Tendril incluye detección de Chromium para Windows y macOS, y el CI ejercita los tres sistemas operativos, pero Linux sigue siendo el objetivo de despliegue recomendado.

Inicio rápido

Instalar desde el código fuente

git clone https://github.com/gadgethd/Project-Tendril.git
cd Project-Tendril
npm ci
npm run build
npm link
tendril doctor

Si no hay ningún navegador compatible instalado:

tendril install-browser

Ejecuta el servicio HTTP local, el panel de control, el endpoint MCP y la puerta de enlace CDP:

tendril serve

O ejecuta solo un servidor MCP stdio:

tendril mcp

Usa --headed cuando se requiera un navegador visible:

tendril serve --headed

tendril serve imprime una URL del panel de control que contiene el token bearer local en el fragmento de la URL. El panel de control mueve el token al almacenamiento de sesión; los fragmentos de URL no se envían como parte de las solicitudes HTTP.

Ejecutar sin enlazar

npm ci
npm run build
node dist/cli.js doctor
node dist/cli.js mcp

Conectar un cliente MCP

Stdio local

Stdio es la configuración más simple y segura. El cliente MCP inicia Project Tendril como proceso hijo y controla su ciclo de vida:

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

Para un checkout del código fuente sin npm link:

{
  "mcpServers": {
    "project-tendril": {
      "command": "node",
      "args": [
        "/absolute/path/to/Project-Tendril/dist/cli.js",
        "mcp"
      ]
    }
  }
}

Para permitir que una persona complete un inicio de sesión interactivo o un desafío, añade --headed a los argumentos.

HTTP Streamable

Inicia el servicio compartido:

TENDRIL_TOKEN="replace-with-a-long-random-token" tendril serve

Luego configura un cliente MCP para:

• URL: http://127.0.0.1:3210/mcp

• Cabecera: Authorization: Bearer replace-with-a-long-random-token

Si TENDRIL_TOKEN no está definido, Project Tendril crea un token aleatorio y lo almacena en:

• Linux: ~/.local/share/project-tendril/http-token

• Otras plataformas: el directorio de datos de usuario equivalente del sistema operativo

Flujo de trabajo recomendado para agentes

1. Crea una sesión efímera con browser_session.

2. Navega con browser_navigate.

3. Toma una browser_snapshot nueva.

4. Usa los refs de esa instantánea con browser_act.

5. Toma otra instantánea después de la navegación o de acciones que cambien el DOM.

6. Cierra la sesión cuando la tarea esté completa.

Nunca almacenes en caché refs de elementos entre navegaciones. Los refs se invalidan intencionalmente cuando el estado de su página ya no es actual.

Herramientas MCP

Project Tendril 1.0 expone 18 herramientas:

El recurso MCP tendril://status informa la versión del runtime y el estado de las sesiones activas.

REST y CDP

Todos los endpoints excepto /health, /dashboard y /openapi.json requieren el token bearer. El servicio se vincula a loopback por defecto.

Extraer Markdown de una página renderizada

TOKEN="$(tr -d '\n' < ~/.local/share/project-tendril/http-token)"

curl --fail-with-body --silent --show-error \
  http://127.0.0.1:3210/v1/markdown \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com"}'

Otras acciones rápidas incluyen:

• POST /v1/snapshot

• POST /v1/content

• POST /v1/accessibility-tree

• POST /v1/links

• POST /v1/screenshot

• POST /v1/pdf

• POST /v1/search

• POST /v1/research

• POST /v1/crawl

Crear una sesión de navegador duradera

curl --fail-with-body --silent --show-error \
  http://127.0.0.1:3210/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"profile":"documentation"}'

La respuesta de la sesión incluye un cdpUrl a nivel de navegador. Su token de consulta admite clientes CDP que no pueden proporcionar cabeceras WebSocket personalizadas.

Conectar Playwright a través de CDP

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(process.env.TENDRIL_CDP_URL);
const context = browser.contexts()[0];
const pages = context.pages();

console.log(await pages[0].title());

Trata la posesión de una URL CDP como la posesión del token bearer: un cliente CDP autenticado tiene control total de esa sesión de navegador de Tendril.

El servicio en ejecución expone un documento OpenAPI compacto en http://127.0.0.1:3210/openapi.json.

Búsqueda, investigación y rastreo

browser_search renderiza las páginas de resultados de los proveedores en Chromium y devuelve títulos, URL, fragmentos, rangos y nombres de proveedores normalizados. El orden predeterminado es:

1. Bing

2. DuckDuckGo

3. Google

Configure una instancia SearXNG autoalojada estableciendo searxngUrl y añadiendo searxng a searchProviders.

browser_research acepta hasta diez consultas, elimina duplicados de las URL de resultados, visita un número limitado de fuentes y devuelve fragmentos de evidencia con su URL de origen, título, encabezado y consulta de origen. No genera un resumen; el agente que realiza la llamada sigue siendo responsable del análisis y la citación.

browser_crawl crea un trabajo asíncrono con:

• Un máximo de 100 páginas.

• Una profundidad máxima de 5.

• Restricción de mismo origen habilitada por defecto.

• Cumplimiento de robots.txt habilitado por defecto.

• Cancelación, estado, resultados parciales y errores por página.

Los proveedores de búsqueda y los sitios web pueden limitar la tasa de acceso automatizado. Project Tendril informa del fallo o prueba el siguiente proveedor de búsqueda configurado; no aplica parches de sigilo por defecto.

Gestión de desafíos

Cuando browser_challenge detecta Cloudflare, Turnstile, reCAPTCHA, hCaptcha, DuckDuckGo, Google o un desafío desconocido, Project Tendril ofrece dos vías de resolución:

Intervención humana (manual)

La vía predeterminada. Una persona completa el desafío en una ventana de Chromium con interfaz gráfica:

1. Inicie Project Tendril con --headed, o cree la sesión con headless: false.

2. Llame a browser_challenge con action: "inspect".

3. Llámelo con action: "handoff"; Project Tendril enfoca la página exacta con el desafío.

4. Una persona completa el desafío en Chromium.

5. Llámelo con action: "wait"; la herramienta devuelve el control cuando el desafío desaparece.

6. Reanude la automatización en la misma sesión.

Resolución automatizada (opt-in)

Para flujos de trabajo sin interfaz gráfica y dirigidos por agentes, se puede habilitar la resolución automatizada de desafíos:

{
  "challengeAutoSolve": true
}

O mediante variable de entorno:

TENDRIL_CHALLENGE_AUTO_SOLVE=true

Cuando está habilitada, Project Tendril intentará resolver automáticamente los desafíos compatibles mediante heurísticas locales. Esto no depende de API externas, servicios de resolución de CAPTCHA ni parches de sigilo. Los tipos de desafío no compatibles recurren a la vía de intervención humana.

[!NOTE] La resolución automatizada es una capacidad opt-in. Funciona mejor con Turnstile y desafíos intersticiales más simples. Las instancias complejas de reCAPTCHA o hCaptcha pueden requerir aún intervención humana. La función procesa todo localmente: no se envían datos a servicios de resolución de terceros.

Orientación general

• Utilice un perfil con nombre de alcance limitado cuando una cookie legítima de inicio de sesión o de autorización deba sobrevivir a un reinicio. Project Tendril no copia la autorización entre perfiles ni máquinas.

• Para pruebas automatizadas, prefiera las claves de prueba oficiales y los modos de prueba del proveedor del desafío.

Configuración

Copie el ejemplo:

cp tendril.config.example.json tendril.config.json

La precedencia de configuración es:

1. Valores predeterminados integrados

2. tendril.config.json

3. Variables de entorno TENDRIL_*

4. Banderas de CLI

Opciones importantes

El tiempo de espera de acciones, el tiempo de espera de navegación, el tamaño de la instantánea y el tamaño máximo del cuerpo de respuesta también se pueden establecer en la configuración JSON. Consulte tendril.config.example.json y src/config.ts para conocer el esquema completo y los valores predeterminados.

Acceso de desarrollo local

Los destinos privados y de loopback están bloqueados por defecto. Para probar un sitio local:

tendril mcp --allow-private-network

Esto es intencionadamente explícito. Prefiera una entrada allowedHosts limitada cuando sea posible.

Modelo de seguridad

Project Tendril asume que cada URL, página, marco, script, descarga y argumento de MCP puede ser hostil.

Límite de red

• Cada sesión utiliza un proxy directo HTTP/HTTPS dedicado.

• El proxy resuelve los nombres de host y se conecta solo a la dirección verificada, lo que reduce la exposición al reenlace de DNS.

• Los destinos de loopback, redes privadas RFC1918, rangos link-local, multidifusión, direcciones reservadas, NAT de operador y metadatos de nube están bloqueados por defecto.

• Las redirecciones y los subrecursos crean nuevas solicitudes de proxy y se vuelven a verificar.

• La navegación de alto nivel acepta solo URL HTTP(S) públicas.

• El UDP de WebRTC sin proxy, QUIC, WebTransport, las extensiones y la red en segundo plano de Chromium están deshabilitados.

Límite de perfil y sistema de archivos

• Project Tendril nunca abre el perfil normal de Chrome o Chromium del usuario.

• Los perfiles con nombre son opt-in y están bloqueados a una sesión activa.

• Las rutas de carga se canonicalizan y se restringen a las raíces de espacio de trabajo configuradas.

• Los perfiles efímeros se eliminan al cerrar.

• Se rechaza Chromium cuando Project Tendril se ejecuta como root, a menos que se proporcione una anulación de desarrollo explícita.

Límite del agente

• Los datos derivados de la página se marcan como no confiables.

• Las frases comunes de anulación de instrucciones y exfiltración generan advertencias.

• La salida de instantáneas, extracción, consola, red y cuerpo de respuesta está limitada.

• La evaluación de JavaScript de la página es explícita y se ejecuta dentro de la página seleccionada, no en el proceso Node.js de Project Tendril.

• La resolución de desafíos es opt-in y solo local; no se contacta con servicios de resolución externos.

Estos controles son salvaguardas, no un límite completo de máquina virtual. Utilice el contenedor reforzado u otro límite de VM para la navegación adversaria. Lea Security y SECURITY.md antes de exponer Project Tendril a otras máquinas.

Docker

Construya la imagen:

docker build -t project-tendril:1.0.0 .

Ejecute Chromium como el usuario tendril no root de la imagen con un sistema de archivos raíz de solo lectura y el perfil seccomp compatible con el sandbox incluido:

docker run --rm --init \
  --name project-tendril \
  -p 127.0.0.1:3210:3210 \
  --ipc=host \
  --read-only \
  --tmpfs /tmp:rw,nosuid,nodev,size=1g \
  --security-opt seccomp=seccomp_profile.json \
  --cap-drop ALL \
  --cap-add SYS_CHROOT \
  -e TENDRIL_TOKEN="replace-with-a-long-random-token" \
  project-tendril:1.0.0

El perfil seccomp incluido es la política predeterminada de Docker con las operaciones de espacio de nombres de usuario requeridas por el sandbox de Chromium. SYS_CHROOT es la única capacidad conservada y también la requiere el sandbox.

No añada la opción no-new-privileges de Docker: impide que el sandbox setuid de Chromium se inicie.

Persista los perfiles con nombre y el token HTTP generado:

docker volume create project-tendril-data

docker run --rm --init \
  --name project-tendril \
  -p 127.0.0.1:3210:3210 \
  --ipc=host \
  --read-only \
  --tmpfs /tmp:rw,nosuid,nodev,size=1g \
  --security-opt seccomp=seccomp_profile.json \
  --cap-drop ALL \
  --cap-add SYS_CHROOT \
  -v project-tendril-data:/data \
  project-tendril:1.0.0

No publique el puerto 3210 más allá del loopback sin un proxy inverso TLS autenticado y una revisión explícita de amenazas.

Desarrollo

git clone https://github.com/gadgethd/Project-Tendril.git
cd Project-Tendril
npm ci
npm run typecheck
npm test
npm run build

Comandos útiles:

La suite de integración inicia Chromium real y cubre:

• Instantáneas semánticas y acciones basadas en referencias.

• Descubrimiento de servidores MCP y control del navegador.

• Acciones rápidas REST y CDP sin procesar autenticado.

• Primitivas de búsqueda/rastreo y robots.txt.

• Detección de desafíos.

• Política de red privada y navegación.

• Generación de capturas de pantalla y limpieza de procesos.

Estructura del repositorio

Project-Tendril/
├── src/
│   ├── browser/          Chromium, sessions, snapshots, extraction, search, crawl
│   ├── security/         Network policy and per-session egress proxy
│   ├── server/           MCP, HTTP, CDP gateway, and dashboard
│   ├── cli.ts            Command-line entry point
│   ├── config.ts         Defaults, file, and environment configuration
│   └── runtime.ts        Shared service composition
├── tests/                Real-Chromium integration tests
├── docs/                 Architecture and security documentation
├── .github/              CI, security scanning, releases, and community files
├── Dockerfile
├── seccomp_profile.json
└── tendril.config.example.json

Solución de problemas

No se encontró ningún ejecutable de Chromium

tendril install-browser
tendril doctor

O establezca TENDRIL_EXECUTABLE_PATH en un ejecutable de Chromium o Google Chrome.

Chromium se niega a iniciarse como root

Ejecute Project Tendril como un usuario normal. El sandbox del navegador es parte del modelo de seguridad. La imagen de Docker ya utiliza una cuenta no root dedicada.

Docker informa de un error de sandbox o espacio de nombres

Utilice el seccomp_profile.json documentado, conserve solo SYS_CHROOT y no establezca no-new-privileges. Ejecute docker build de nuevo después de cambiar el Dockerfile.

Una URL de desarrollo local está bloqueada

Los destinos privados se deniegan por defecto. Añada el nombre de host exacto a allowedHosts o use --allow-private-network solo para una sesión de desarrollo local confiable.

La referencia de elemento está obsoleta

Tome una nueva browser_snapshot y use una referencia de ese resultado. Las acciones de navegación y de cambio de DOM invalidan deliberadamente las referencias antiguas.

El proveedor de búsqueda devuelve un desafío

Permita que Project Tendril pruebe el siguiente proveedor configurado, configure SearXNG o use una entrega manual con interfaz gráfica donde el proveedor lo permita. No reintente de forma agresiva.

Estado del proyecto y hoja de ruta

Project Tendril 1.0 está completo en cuanto a funciones para el despliegue local en Linux. Las vías nativa, MCP, REST, CDP, paquete y Docker están cubiertas por pruebas de integración automatizadas.

Trabajo probable posterior a 1.0:

• Validación de tiempo de ejecución más amplia en Windows y macOS.

• Más adaptadores de búsqueda y opciones de descubrimiento autoalojadas.

• Herramientas de grabación y reproducción de trazas.

• Estrategias adicionales de compresión y diff de instantáneas.

• Exportación local opcional de métricas compatible con OpenTelemetry sin telemetría alojada.

• Artefactos publicados en npm y en el registro de contenedores.

Los elementos de la hoja de ruta no son promesas. Abre una solicitud de funcionalidad con un flujo de trabajo de agente concreto y el límite de seguridad esperado.

Contribuciones

Las contribuciones son bienvenidas. Lee:

• Guía de contribución

• Código de conducta

• Política de seguridad

• Guía de soporte

• Registro de cambios

Antes de abrir una pull request:

npm ci
npm run typecheck
npm test
npm run build

Los cambios que añadan resolución de CAPTCHA, evasión de stealth/huellas digitales, telemetría, acceso implícito a perfiles de navegador normales o acceso a redes privadas por defecto están fuera del alcance del proyecto.

Licencia

Project Tendril está licenciado bajo la Apache License 2.0.

Copyright 2026 contribuyentes de Project Tendril.