Para agentes & LLMs

O Clearcote é organizado para que ferramentas automatizadas consigam navegar, integrar e contribuir com a mesma facilidade que uma pessoa. Vai instalar o Clearcote para alguém? Siga o runbook de instalação.

Runbook de instalação para agentes de programação

Se você é um agente de programação com IA (Claude Code, Codex, Cursor, Windsurf, Cline e similares) e recebeu o pedido de configurar o Clearcote para alguém, siga as etapas abaixo, nesta ordem: instalado, licença configurada, em execução, verificado. Cada etapa tem uma verificação, e uma etapa só está concluída quando a verificação dela passa. Registre o seu progresso em um arquivo, para que uma nova sessão, ou um usuário que volte amanhã, retome a partir da primeira etapa não concluída em vez de começar do zero. O mesmo runbook existe como um único arquivo markdown em /setup.md, o endereço que a página inicial oferece para você colar em um agente; ele é a cópia canônica, e esta seção o acompanha título por título.

Regras

• Execute você mesmo cada comando e leia a saída dele. Se uma etapa falhar, pare e informe. Diga ao usuário qual etapa falhou, o comando que você executou e a linha exata do erro e, em seguida, a correção indicada na tabela abaixo. Não improvise uma saída para uma verificação que falhou (pular a verificação, fixar um build mais antigo, trocar de build) sem perguntar antes.
• Instale somente a partir das fontes oficiais: o pacote clearcote no PyPI, npm ou NuGet, o clearcote-mcp no PyPI e no npm, a imagem Docker teamflatearth/clearcote e as releases de clearcotelabs/clearcote-browser. O próprio SDK baixa o navegador e confere o SHA-256 dele: nunca baixe um build do navegador de outro lugar e nunca desative essa verificação.
• Nunca peça ao usuário para colar uma chave de licença ou uma chave de API no chat, e nunca imprima, registre em log ou faça commit de uma chave. Se mesmo assim alguém colar uma, não a repita, não a grave em nenhum arquivo que você criar e sugira rotacioná-la na página Licenses.
• Quando um link tiver expirado ou estiver quebrado, não procure uma cópia. Os links de download que o SDK usa duram pouco, e ele pede um novo a cada execução; então rode o comando de novo em vez de reaproveitar uma URL. Para qualquer outro link (de login, de um código de dispositivo, de uma página do painel, um link que o usuário encaminhou), volte ao lugar de onde ele veio ou peça um novo ao usuário. Nunca recorra a um mirror, a uma cópia em cache ou a um pacote não oficial.
• Instale no projeto do usuário (no virtualenv, no package.json ou no .csproj dele), não globalmente, a menos que o usuário peça outra coisa. Pergunte antes de editar configurações fora do projeto (a configuração de um cliente MCP, por exemplo) e antes de iniciar qualquer coisa que custe dinheiro (os navegadores hospedados são cobrados por GB).
• Concluído significa que a versão exata do navegador foi confirmada, e não que um pacote foi instalado.

Mantenha um arquivo de progresso

Crie o clearcote-setup.json na raiz do projeto (ele não guarda nenhum segredo) e atualize-o após cada verificação. route é python, node, dotnet, mcp ou docker; build é open (sem chave) ou licensed (Grátis com GitHub ou Pro); blocked registra o que você está 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" }
}

No início de uma sessão, leia o arquivo e continue a partir da primeira etapa não concluída. Rode de novo a verificação de qualquer etapa anterior da qual você dependa, porque uma chave pode expirar e um cache pode ser limpo entre uma sessão e outra.

Etapa 0: escolha o caminho e o build

Pergunte ao usuário uma única vez e registre as respostas.

• O caminho. Para o código do próprio usuário: o SDK na linguagem do projeto, Python 3.8+, Node 20+ ou .NET 8 (se ainda não houver projeto, sugira Python). Para você, o agente, navegar: o servidor MCP (Python 3.10+). Como endpoint CDP para um framework existente: a imagem Docker.
• O build. O build aberto não precisa de chave nem de cadastro: Chromium 150, de código aberto (BSD-3), bom o bastante para começar. O build mais recente é o Chromium 154, com chave de licença: grátis com GitHub para um navegador por vez, ou o Pro para até 250 navegadores ao mesmo tempo.

O navegador roda em Windows x64 e Linux x64, e a imagem Docker também é x64. Em macOS ou em uma máquina ARM, pare e avise o usuário; os navegadores hospedados são a opção que dispensa um navegador local.

Etapa 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

A verificação: clearcote version (Node: npx clearcote version) imprime 0.45.0 ou uma versão mais nova. Para o Docker, docker image ls teamflatearth/clearcote lista a imagem.

O .NET não tem um comando clearcote próprio. Confira se dotnet list package lista o Clearcote e, depois, rode cada comando clearcote das etapas 1 a 3 como npx -y clearcote <command> (Node 20+) ou pipx run clearcote <command> (Python 3.8+). Isso não adiciona nada ao projeto, e o comando usa o mesmo cache do navegador e o mesmo arquivo de licença (~/.clearcote/license.key) que o SDK .NET. Se a máquina não tiver nem Node nem Python, peça ao usuário para instalar um dos dois: sem o comando, não há como confirmar a versão do navegador, então a instalação não pode ser verificada.

Etapa 2: licença configurada

Para o build aberto, marque esta etapa como concluída com a evidência open build, no key. Para o build mais recente, a chave chega à máquina do usuário sem passar por você:

• Se clearcote --help listar clearcote login --device, rode clearcote login --device (Node: npx clearcote login --device). Ele imprime um link e um código curto. O usuário abre o link no próprio navegador, faz login e aprova (uma chave gratuita exige uma conta do GitHub com pelo menos 30 dias), e o SDK salva a chave em ~/.clearcote/license.key sem exibi-la.
• Caso contrário, o usuário obtém uma chave na página Licenses e roda clearcote login (Node: npx clearcote login) no próprio terminal, colando a chave ali: ela aparece na tela dele, nunca no chat. Passe essas instruções ao usuário e espere até ele dizer que terminou. Ele também pode, em vez disso, definir CLEARCOTE_LICENSE_KEY por conta própria, no perfil do shell, nos secrets do CI, no bloco env da configuração do cliente MCP ou no ambiente do Docker (nesse caso, docker run -e CLEARCOTE_LICENSE_KEY repassa a variável sem que o valor apareça no comando).

Nunca rode clearcote login <key> você mesmo: a chave iria parar na transcrição da sua sessão e no histórico do shell. Também não abra o ~/.clearcote/license.key. A verificação: clearcote info --quick mostra a linha Licence com uma chave mascarada from file ou from env, e isso é tudo o que você precisa ver. none (free build) significa que nenhuma chave foi encontrada. Uma chave definida só na configuração de um cliente MCP ou em um contêiner fica invisível para o seu shell; confira se o nome da variável está lá sem imprimir o valor dela.

Etapa 3: em execução

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

(Node: npx clearcote install e npx clearcote info.) A verificação: clearcote info imprime Launch test ok com a versão do navegador (com --json: launch.ok é true, launch.version traz a versão e binary.tag, o build). Com uma chave gratuita, isso ocupa por um instante a única vaga de navegador, então feche antes qualquer outro navegador Clearcote. Depois, conforme o caminho:

• SDK: rode um primeiro script, clearcote_hello.py ou clearcote_hello.mjs. A verificação: ele imprime Example Domain e um user agent do Chrome e, em seguida, encerra. No .NET, use a aba C# de Playwright & Puppeteer. A seed fingerprint é a identidade: a mesma seed gera o mesmo dispositivo toda vez, então use uma seed por conta.
• Servidor MCP: registre o comando clearcote-mcp no cliente (pergunte antes; informe o caminho completo se ele estiver em um virtualenv), como em Servidor MCP. Reinicie o cliente e chame a ferramenta navigate dele com https://example.com; ela retorna a URL final e o título da página.
• Docker: inicie um contêiner e leia o log e o endpoint dele, como abaixo.

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()

Etapa 4: verificado

Compare o que a etapa 3 imprimiu com o build que o usuário deveria ter. No Docker, a tag do build faz parte do caminho do motor na linha de log.

Um plano Pro que fixa um build mais antigo mostra esse build no lugar. Se não for o build que o usuário escolheu, pare e avise o usuário. Quando a versão bater, marque verified como concluída, com a versão, e informe ao usuário: o caminho, a versão do SDK, qual build está rodando e a versão exata do navegador, onde está o primeiro script e como executá-lo, onde a chave está guardada (arquivo ou variável de ambiente, nunca a chave em si) e a documentação.

Quando uma etapa falha

Opcional, só se o usuário quiser

• Um proxy. Passe um proxy do Playwright e geoip=True, para que o fuso horário e o idioma acompanhem o IP de saída do proxy. Veja Proxies e geoip.
• Um navegador para você, o agente, via MCP, se esse não foi o caminho escolhido: pip install -U clearcote-mcp (Python 3.10+) e, depois, registre-o como na etapa 3. Para o build mais recente, o servidor encontra a chave salva na etapa 2, ou o próprio usuário adiciona CLEARCOTE_LICENSE_KEY ao env desse servidor.
• Sem máquinas para rodá-lo. Os navegadores hospedados iniciam o mesmo navegador nos servidores do Clearcote com uma única chamada de API. Eles exigem uma chave de API e são cobrados por GB, então pergunte antes.

Resumo legível por máquina

Um resumo conciso do projeto, em texto puro, fica em /llms.txt, e a documentação completa, achatada em um único arquivo pronto para prompt, está em /llms-full.txt. O repositório também inclui um AGENTS.md que descreve a estrutura e as convenções para quem quer contribuir.

{
  "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"
}

Receita mínima de integração

1. Instale o SDK (pip install clearcote / npm i clearcote) — ele baixa e verifica o navegador.
2. Derive uma seed de fingerprint determinística a partir da identidade em nome da qual você está agindo.
3. Atrás de um proxy, passe geoip=True para que fuso horário, idioma e WebRTC acompanhem o IP de saída.
4. Para frameworks que esperam uma URL CDP (browser-use, Stagehand, Crawl4AI), use serve() ou clearcote serve em vez disso.

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 o binário do build aberto diretamente com executablePath também funciona, mas o build licenciado só inicia pelo SDK, e uma inicialização direta perde os padrões do SDK — veja Playwright & Puppeteer. Para uma identidade de maior fidelidade, inicie um perfil real capturado em vez de uma seed: launch(profile="auto") escolhe, na biblioteca de perfis (build licenciado), um que combine com esta máquina; ou passe fingerprint_profile="profile.json" (Node: fingerprintProfile). Não combine um perfil com uma seed de fingerprint.

Agente de IA no navegador

O Clearcote traz um agente de IA opcional (opt-in) que controla uma página real de forma autônoma. Ele observa a página ao vivo, pergunta a um LLM configurado pelo usuário o que fazer em seguida e age por meio do framework Actor do Chrome, com eventos de entrada reais e confiáveis em vez de script injetado. Ele vem desativado por padrão (fica inativo a menos que você forneça uma chave de agente ou os switches do agente) e usa a sua própria chave: aponte-o para qualquer endpoint compatível com OpenAI / OpenRouter. Campos de senha são ocultados antes de qualquer coisa ser enviada ao modelo. Use launch_agent() (um contexto persistente) — esse é o caminho suportado.

Pelo SDK, launch_agent (Node: launchAgent) retorna um BrowserContext persistente, e run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) o controla, retornando { success, finalText, steps, stepsJson }. Passe um diretório de perfil como primeiro argumento (userDataDir no Node) para reaproveitar um perfil; sem ele, cada chamada cria uma nova pasta de perfil temporária, que não é removida ao fechar. Somente 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"])

As opções de inicialização do agente correspondem diretamente a switches do binário: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model) e agent_typing / agentTyping. Uma tarefa roda assim que o agente tem uma URL (OpenRouter por padrão), uma chave e um modelo. O agente pede ao modelo uma resposta em JSON em texto puro, então o endpoint não precisa suportar tool calls; o agent_tool_mode / agentToolMode (--agent-tool-mode, CLI --tool-mode) é aceito, mas por enquanto não tem efeito.

O agent_typing / agentTyping ajusta o ritmo de digitação do agente: human (padrão) digita com timing de keydown/keyup por tecla e mantém a digitação de textos longos tecla por tecla, fast é o ritmo rápido do motor e instant digita tudo de uma vez. O padrão evita os dois indícios de digitação — timing uniforme, com precisão de máquina, e texto longo colado instantaneamente (o que não gera nenhum evento de tecla).

CLI clearcote-agent

O mesmo agente está disponível como CLI para execuções rápidas e fáceis de automatizar em scripts. Passe um objetivo avulso ou entre em um REPL interativo. A chave do modelo vem de --key ou das variáveis de ambiente $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

As opções da CLI incluem --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone e --json. Um host sem protocolo passado em --url passa a usar HTTPS.

Onde procurar

• Flags de fingerprint — a referência completa de switches (também fácil de processar por máquina).
• Playwright & Puppeteer — padrões de inicialização drop-in.
• Exemplos — receitas para copiar e colar: SDK, perfil, proxy, canvas bridge, CI e agente.
• Agente de IA no navegador — controle autônomo de páginas (opt-in) e a CLI clearcote-agent.
• Servidor MCP — controle o Clearcote a partir do Claude Desktop, do Cursor ou do Cline.
• Deploy — clearcote serve: uma única URL CDP, com uma identidade separada por conexão.
• Recomendações — quais configurações ativar e quais deixar como estão.
• Verificação — confirme o binário antes de executá-lo.
• Repositório do código-fonte — patches, pipeline de build, AGENTS.md.

Crie identidades determinísticas: derive a seed de um ID estável (tenant, conta, tarefa) para que o mesmo ator sempre receba o mesmo fingerprint do navegador — reproduzível e fácil de depurar.