Para agentes & LLM

Clearcote está organizado para que las herramientas automatizadas puedan recorrerlo, integrarlo y contribuir con la misma facilidad que una persona. ¿Vas a configurar Clearcote para otra persona? Sigue la guía de instalación.

Guía de instalación para agentes de programación

Si eres un agente de programación con IA (Claude Code, Codex, Cursor, Windsurf, Cline y similares) y te pidieron configurar Clearcote para alguien, sigue en orden los pasos de abajo: instalado, licencia configurada, en ejecución y verificado. Cada paso tiene una comprobación, y un paso solo está terminado cuando su comprobación pasa. Guarda tu progreso en un archivo, para que una sesión nueva, o un usuario que vuelve al día siguiente, retome desde el primer paso pendiente en lugar de empezar de cero. La misma guía está en un único archivo markdown en /setup.md, la dirección que la página de inicio te da para que la pegues en un agente; esa es la copia canónica, y esta sección la sigue encabezado por encabezado.

Reglas

• Ejecuta tú mismo cada comando y lee su salida. Si un paso falla, detente e informa. Dile al usuario qué paso falló, el comando que ejecutaste y la línea de error exacta, y después la solución de la tabla de abajo. No resuelvas una comprobación fallida por otro camino (saltarte la verificación, fijar un build anterior, cambiar de build) sin preguntar antes.
• Instala solo desde las fuentes oficiales: el paquete clearcote en PyPI, npm o NuGet, clearcote-mcp en PyPI y npm, la imagen de Docker teamflatearth/clearcote y las versiones publicadas en clearcotelabs/clearcote-browser. El SDK descarga el navegador por su cuenta y comprueba su SHA-256: nunca descargues un build del navegador de ningún otro lugar y nunca desactives esa comprobación.
• Nunca le pidas al usuario que pegue una clave de licencia o una clave de API en el chat, y nunca imprimas, registres en un log ni incluyas en un commit ninguna clave. Si aun así alguien la pega, no la repitas, no la escribas en ningún archivo que crees y sugiere rotarla en la página “Licenses”.
• Si un enlace expiró o no funciona, no busques una copia. Los enlaces de descarga que usa el SDK duran poco y el SDK pide uno nuevo en cada ejecución, así que vuelve a ejecutar el comando en lugar de reutilizar una URL. Para cualquier otro enlace (un inicio de sesión, un código de dispositivo, una página del panel, un enlace que te reenvió el usuario), vuelve al lugar de donde salió o pídele uno nuevo al usuario. Nunca recurras a un mirror, a una copia en caché ni a un paquete no oficial.
• Instala en el proyecto del usuario (su entorno virtual, package.json o .csproj), no de forma global, salvo que el usuario pida otra cosa. Pregunta antes de editar configuración fuera del proyecto (la configuración de un cliente MCP, por ejemplo) y antes de iniciar cualquier cosa que cueste dinero (los navegadores alojados se cobran por GB).
• Terminado significa que la versión exacta del navegador está confirmada, no que se instaló un paquete.

Mantén un archivo de progreso

Escribe clearcote-setup.json en la raíz del proyecto (no contiene secretos) y actualízalo después de cada comprobación. route es python, node, dotnet, mcp o docker; build es open (sin clave) o licensed (Gratis con GitHub o Pro); blocked registra qué estás esperando.

{
  "route": "python",
  "build": "licensed",
  "steps": {
    "installed":   { "done": true,  "checked": "2026-10-06T10:12:00Z", "evidence": "clearcote SDK 0.45.0" },
    "licence_set": { "done": false },
    "running":     { "done": false },
    "verified":    { "done": false, "browser_version": null }
  },
  "blocked": { "step": "licence_set", "waiting_for": "user approves the device sign-in" }
}

Al empezar una sesión, lee el archivo y continúa desde el primer paso pendiente. Vuelve a ejecutar la comprobación de cualquier paso anterior del que dependas, porque entre una sesión y otra una clave puede expirar y una caché puede borrarse.

Paso 0: elige la vía y el build

Pregúntale al usuario una sola vez y anota las respuestas.

• La vía. Para su propio código: el SDK en el lenguaje del proyecto, Python 3.8+, Node 20+ o .NET 8 (si todavía no hay proyecto, sugiere Python). Para que tú, el agente, navegues con él: el servidor MCP (Python 3.10+). Como endpoint de CDP para un framework existente: la imagen de Docker.
• El build. El build abierto no necesita clave ni registro: Chromium 150, de código abierto (BSD-3), suficiente para empezar. El build más reciente es Chromium 154, con clave de licencia: gratis con GitHub para un navegador a la vez, o Pro para hasta 250 navegadores simultáneos.

El navegador funciona en Windows x64 y Linux x64, y la imagen de Docker también es x64. En macOS o en una máquina ARM, detente y avísalo; los navegadores alojados son la opción que no necesita un navegador local.

Paso 1: instalado

pip install -U clearcote                  # Python, inside the project's virtualenv
npm install clearcote                     # Node
dotnet add package Clearcote              # .NET (see below for the checks)
pip install -U clearcote clearcote-mcp    # MCP server: Python 3.10+, no mcp pin needed
docker pull teamflatearth/clearcote       # Docker

La comprobación: clearcote version (Node: npx clearcote version) imprime 0.45.0 o una versión posterior. Para Docker, docker image ls teamflatearth/clearcote muestra la imagen.

.NET no tiene un comando clearcote propio. Comprueba que dotnet list package muestre Clearcote y, después, ejecuta cada comando clearcote de los pasos 1 a 3 como npx -y clearcote <command> (Node 20+) o pipx run clearcote <command> (Python 3.8+). Eso no agrega nada al proyecto, y el comando usa la misma caché del navegador y el mismo archivo de licencia (~/.clearcote/license.key) que el SDK de .NET. Si la máquina no tiene ni Node ni Python, pídele al usuario que instale uno de los dos: sin el comando no se puede confirmar la versión del navegador, así que no se puede verificar la instalación.

Paso 2: licencia configurada

Con el build abierto, marca este paso como terminado con la evidencia open build, no key. Con el build más reciente, la clave llega a la máquina del usuario sin pasar por ti:

• Si clearcote --help incluye clearcote login --device, ejecuta clearcote login --device (Node: npx clearcote login --device). Imprime un enlace y un código corto. El usuario abre el enlace en su propio navegador, inicia sesión y lo aprueba (una clave gratuita requiere una cuenta de GitHub con al menos 30 días de antigüedad), y el SDK guarda la clave en ~/.clearcote/license.key sin mostrarla.
• Si no, el usuario obtiene una clave en la página “Licenses” y ejecuta clearcote login (Node: npx clearcote login) en su propia terminal, donde pega la clave: se ve en su pantalla, nunca en el chat. Dale esos pasos y espera a que te diga que terminó. También puede definir él mismo CLEARCOTE_LICENSE_KEY en el perfil de su shell, en los secretos de CI, en el bloque env de la configuración de su cliente MCP o en su entorno de Docker (así, docker run -e CLEARCOTE_LICENSE_KEY la pasa sin que el valor aparezca en el comando).

Nunca ejecutes tú clearcote login <key>: la clave quedaría en tu transcripción y en el historial del shell. Tampoco abras ~/.clearcote/license.key. La comprobación: clearcote info --quick muestra la línea Licence como una clave enmascarada from file o from env, y eso es todo lo que necesitas ver. none (free build) significa que no se encontró ninguna clave. Una clave definida solo en la configuración de un cliente MCP o en un contenedor no es visible desde tu shell; comprueba que el nombre de la variable esté ahí sin imprimir su valor.

Paso 3: en ejecución

clearcote install    # downloads and verifies the build the key allows
clearcote info       # starts the browser once, headless

(Node: npx clearcote install y npx clearcote info.) La comprobación: clearcote info imprime Launch test ok con la versión del navegador (con --json: launch.ok es true, launch.version contiene la versión y binary.tag, el build). Con una clave gratuita, esto ocupa por un momento el único slot de navegador, así que antes cierra cualquier otro navegador de Clearcote. Después, según la vía:

• SDK: ejecuta un primer script, clearcote_hello.py o clearcote_hello.mjs. La comprobación: imprime Example Domain y un user agent de Chrome, y termina. En .NET, usa la pestaña C# de Playwright & Puppeteer. El seed fingerprint es la identidad: el mismo seed da el mismo dispositivo cada vez, así que usa un seed por cuenta.
• Servidor MCP: registra el comando clearcote-mcp en el cliente (pregunta antes; da la ruta completa si está en un entorno virtual), como en Servidor MCP. Reinicia el cliente y llama a su herramienta navigate con https://example.com; devuelve la URL final y el título de la página.
• Docker: inicia un contenedor y lee su log y su endpoint, como se muestra abajo.

import clearcote

browser = clearcote.launch(fingerprint="first-run")
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
print(page.evaluate("navigator.userAgent"))
browser.close()

Paso 4: verificado

Compara lo que imprimió el paso 3 con el build que debería tener el usuario. En Docker, la etiqueta de build forma parte de la ruta del motor en la línea del log.

Un plan Pro que fija un build anterior muestra ese build en su lugar. Si no es el build que eligió el usuario, detente y avísale. Cuando la versión coincide, marca verified como terminado con la versión y dile al usuario: la vía, la versión del SDK, qué build se ejecuta y la versión exacta de su navegador, dónde está el primer script y cómo ejecutarlo, dónde se guarda la clave (archivo o variable de entorno, nunca la clave en sí) y la documentación.

Si un paso falla

Opcional, solo si el usuario lo quiere

• Un proxy. Pasa un proxy de Playwright y geoip=True, para que la zona horaria y el idioma sigan a la IP de salida del proxy. Consulta Proxies y geoip.
• Un navegador para ti, el agente, por MCP, si esa no fue la vía elegida: pip install -U clearcote-mcp (Python 3.10+), y después regístralo como en el paso 3. Con el build más reciente, el servidor encuentra la clave guardada en el paso 2, o el usuario agrega él mismo CLEARCOTE_LICENSE_KEY al env de ese servidor.
• Sin máquinas donde ejecutarlo. Los navegadores alojados inician el mismo navegador en los servidores de Clearcote con una sola llamada a la API. Necesitan una clave de API y se cobran por GB, así que pregunta antes.

Resumen legible por máquinas

En /llms.txt hay un resumen conciso del proyecto en texto plano, y en /llms-full.txt está toda la documentación aplanada en un único archivo listo para usar como prompt. El repositorio también incluye un AGENTS.md que describe la estructura y las convenciones para quienes contribuyen.

{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 150 (v0.1.0-pre.23), licensed build 154.0.8037.57-r36",
  "identity_model": "engine-level, coherent seed persona + per-site render noise",
  "automation": "SDK (npm/PyPI/NuGet package clearcote) returning Playwright objects; CDP endpoint for Puppeteer and others",
  "platforms": ["windows-x64", "linux-x64"],
  "license": "BSD-3-Clause (open build + SDKs); the licensed build adds unpublished patches",
  "repo": "https://github.com/clearcotelabs/clearcote-browser",
  "verify": "open build: GPG-signed SHA256SUMS + pinned key; every SDK download: SHA-256",
  "control_via": "SDK options, or chromium command-line switches (args) on the open build"
}

Receta mínima de integración

1. Instala el SDK (pip install clearcote / npm i clearcote): descarga y verifica el navegador.
2. Deriva un seed de fingerprint determinista a partir de la identidad con la que actúas.
3. Detrás de un proxy, pasa geoip=True para que la zona horaria, el idioma y WebRTC sigan a la salida del proxy.
4. Para los frameworks que piden una URL de CDP (browser-use, Stagehand, Crawl4AI), usa en su lugar serve() o clearcote serve.

from clearcote import launch

task_id = "1234"
SEED = "agent:" + task_id          # stable, reproducible identity per task

browser = launch(fingerprint=SEED, geoip=True, humanize=True)
page = browser.new_page()
page.goto("https://example.com")

Controlar directamente el binario del build abierto con executablePath también funciona, pero el build con licencia solo se inicia a través del SDK, y un lanzamiento directo pierde los valores por defecto del SDK; consulta Playwright & Puppeteer. Para una identidad más fiel, lanza un perfil real capturado en lugar de un seed: launch(profile="auto") elige de la biblioteca de perfiles (build con licencia) uno que encaje con esta máquina, o pasa fingerprint_profile="profile.json" (Node: fingerprintProfile). No combines un perfil con un seed de fingerprint.

Agente de IA integrado en el navegador

Clearcote incluye un agente de IA opcional —solo funciona si lo activas— que controla una página real de forma autónoma. Percibe la página en vivo, le pregunta a un LLM configurado por el usuario qué hacer a continuación y actúa a través del framework Actor de Chrome con eventos de entrada reales y de confianza (trusted), no con scripts inyectados. Está desactivado por defecto (inactivo salvo que proporciones una clave de agente o los switches del agente) y funciona con tu propia clave: apúntalo a cualquier endpoint compatible con OpenAI / OpenRouter. Los campos de contraseña se ocultan antes de enviar nada al modelo. Usa launch_agent() (un contexto persistente): es la vía soportada.

Desde el SDK, launch_agent (Node: launchAgent) devuelve un BrowserContext persistente, y run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) lo controla y devuelve { success, finalText, steps, stepsJson }. Pasa un directorio de perfil como primer argumento (userDataDir en Node) para reutilizar un perfil; sin él, cada llamada crea una carpeta de perfil temporal nueva que no se elimina al cerrar. Solo Python & Node.

import os
from clearcote import launch_agent, run_agent_task

# Returns a persistent BrowserContext.
ctx = launch_agent(
    agent_llm_key=os.environ["OPENROUTER_API_KEY"],   # required: the SDK does not read env vars (the CLI does)
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(
    page,
    goal="Find the pricing page and read the cheapest plan",
    model="openai/gpt-4o-mini",                # optional per-task override
    max_steps=20,
)
print(result["success"], result["finalText"], result["steps"])

Las opciones de lanzamiento del agente se corresponden directamente con switches del binario: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model) y agent_typing / agentTyping. Una tarea se ejecuta cuando el agente tiene una URL (OpenRouter por defecto), una clave y un modelo. El agente le pide al modelo una respuesta JSON en texto plano, así que el endpoint no necesita soporte de tool calls; agent_tool_mode / agentToolMode (--agent-tool-mode, en la CLI --tool-mode) se acepta, pero por ahora no tiene ningún efecto.

agent_typing / agentTyping ajusta la cadencia de tecleo del agente: human (por defecto) escribe con tiempos de keydown/keyup por tecla y mantiene los textos largos tecla por tecla, fast es la cadencia rápida del motor e instant lo escribe todo de una sola vez. El valor por defecto evita las dos señales delatoras al escribir: tiempos uniformes, de una perfección mecánica, y textos largos pegados al instante (lo que no emite ningún evento de teclado).

La CLI clearcote-agent

El mismo agente está disponible como CLI para ejecuciones rápidas y fáciles de automatizar con scripts. Pásale un objetivo para una sola ejecución o entra en un REPL interactivo. La clave del modelo se toma de --key o de las variables de entorno $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY.

# One-shot: run a single goal against a URL, then exit
clearcote-agent --goal "Accept cookies and list the top 3 headlines" --url https://example.com

# Interactive REPL: keep the browser open and issue goals one at a time
clearcote-agent -i

# Use a custom endpoint/model, persistent profile, proxy and step cap
clearcote-agent --llm-url http://localhost:8000/v1 --model local/model \
  --profile ~/.clearcote/agent-profile --proxy http://user:pass@host:8080 \
  --max-steps 12 --goal "Open the dashboard" --url example.com

# Provide the key explicitly (otherwise read from the environment)
clearcote-agent --key sk-or-... --json \
  --goal "Search for 'clearcote' and open the first result" --url https://example.com

Entre las opciones de la CLI están --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone y --json. Un host sin esquema que se pase a --url se convierte a HTTPS.

Dónde buscar

• Flags de huella digital: la referencia completa de switches (también fácil de procesar por máquinas).
• Playwright & Puppeteer: patrones de lanzamiento como reemplazo directo.
• Ejemplos: recetas listas para copiar y pegar de SDK, perfiles, proxy, canvas bridge, CI y agentes.
• Agente de IA integrado en el navegador: control autónomo de páginas (opcional, hay que activarlo) y la CLI clearcote-agent.
• Servidor MCP: controla Clearcote desde Claude Desktop, Cursor o Cline.
• Despliegue: clearcote serve, una sola URL de CDP y una identidad distinta por conexión.
• Recomendaciones: qué ajustes activar y cuáles dejar como están.
• Verificación: confirma el binario antes de ejecutarlo.
• Repositorio del código fuente: parches, pipeline de build, AGENTS.md.

Crea identidades deterministas: deriva el seed de un ID estable (tenant, cuenta, tarea) para que el mismo actor reciba siempre la misma huella digital del navegador, reproducible y fácil de depurar.