Perfis, sincronização de cookies, segredos e 2FA
A maioria das tarefas que vale a pena automatizar fica atrás de um login. Há três formas de deixar um navegador hospedado logado sem colocar uma senha no seu código: faça login uma vez e guarde a sessão em um perfil, copie para um perfil os cookies que você já tem com a sincronização de cookies, ou deixe uma execução de agente digitar o login a partir de segredos que o modelo nunca vê, códigos 2FA incluídos.
Perfis
Um perfil guarda os cookies, o localStorage e o IndexedDB de uma sessão sob um nome. Inicie uma sessão com profile: { name: "shop-account", persist: true } para carregá-lo e salvá-lo de volta quando a sessão terminar, ou com profile: "shop-account" para carregá-lo somente para leitura. A menos que você passe identity ou fingerprint, um perfil também traz a própria identidade: o mesmo dispositivo, e o mesmo IP residencial enquanto esse IP continuar online. As regras completas estão em Perfis: faça login uma vez só; pelo SDK, veja um contexto persistente em um perfil na nuvem.
Para ver o que um perfil contém, sem os valores:
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account
# {
# "name": "shop-account",
# "cookies": 42,
# "domains": ["example.com", "shop.example.com"],
# "bytes": 18211,
# "storage": "Local Storage,IndexedDB",
# "updatedAt": "2026-10-02T09:20:11.000Z"
# }domains lista até 50 sites, em ordem, sem ponto inicial. bytes é o tamanho comprimido. storage indica o armazenamento de site salvo junto (Local Storage, IndexedDB); fica vazio em um perfil que só contém cookies importados. Um nome desconhecido retorna 404 NOT_FOUND.
Nenhum endpoint retorna o valor de um cookie. O conteúdo de um perfil só é aberto nos nossos servidores: para mesclar uma importação, para contar o que ele contém e no servidor que executa uma sessão nele.
Sincronização de cookies
Se você já está logado em algum lugar (seu próprio navegador, um Clearcote local, um script do Playwright), copie esses cookies para um perfil na nuvem e toda sessão nesse perfil começa logada:
curl -X PUT https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account/cookies \
-H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
-d '{
"mode": "merge",
"cookies": [
{ "name": "session_id", "value": "…", "domain": "shop.example.com", "path": "/",
"secure": true, "httpOnly": true, "sameSite": "Lax", "expires": 1798761600 }
]
}'
# { "name": "shop-account", "cookies": 42, "imported": 1, "domains": ["example.com", "shop.example.com"],
# "bytes": 18211, "updatedAt": "…" }- Qualquer formato de cookie comum. O formato do CDP (
Network.getCookies,Network.Cookie/CookieParam) e o do Playwright (context.cookies(), oscookiesde um arquivo de storage state) funcionam como estão; umaurlpode substituirdomain. Semexpires, comexpires: -1(qualquer valor até 0) ou comsession: true, é um cookie de sessão, e um cookie que já expirou é ignorado.sameSiteéLax,StrictouNone, em maiúsculas ou minúsculas, eNoneexigesecure: true. - Validados como o Chrome valida. Um cookie que o Chrome recusaria (um
;em um valor,sameSite: "None"semsecure, um cookie__Secure-ou__Host-que quebra as regras deles, um caminho que não começa com/) transforma a importação inteira em um400cuja mensagem o identifica. - Armazenados como
name,value,domain(em minúsculas),path(padrão/),secure,httpOnly,sameSite(só se você o enviou) eexpires(ausente em um cookie de sessão). Outros campos, comopartitionKey, são descartados. mode: "merge"(o padrão) adiciona seus cookies e substitui os que têm o mesmo nome, domínio e caminho.mode: "replace"deixa os cookies do perfil exatamente iguais à lista que você envia. Em ambos os casos, o localStorage e o IndexedDB do perfil são mantidos.- Limites: no máximo 5000 cookies por requisição, e 5000 no perfil depois de uma mesclagem (
400 TOO_MANY); nomes de até 256 caracteres, valores de até 4096, caminhos de até 1024; o perfil inteiro, no máximo 3.5 MB comprimido (413 TOO_LARGE); 60 importações a cada 10 minutos. - Um perfil que ainda não existe é criado. Enquanto uma sessão que salva no perfil (
persist: true) estiver iniciando ou em execução, uma importação é recusada com409 PROFILE_IN_USE: a sessão a sobrescreveria ao terminar. - Cookies de sessão importados (sem expiração) são carregados nas próximas sessões como qualquer outro. Uma sessão que salva o perfil os descarta, como um navegador real faz ao reiniciar; então importe-os de novo se precisar deles depois disso.
A resposta informa quantos cookies o perfil tem depois da importação (cookies) e quantos dos seus foram aceitos (imported: cookies expirados e duplicados ficam de fora), e lista os primeiros 50 domínios dele, em ordem.
Da sua máquina, com o SDK
O comando clearcote lê os cookies de onde você os tem e envia apenas os domínios que você indicar:
# a local Clearcote profile folder (the user_data_dir of launch_persistent_context)
clearcote cloud profile sync shop-account --from-profile ./profiles/shop --domain example.com
# a browser that is running with a CDP endpoint, for example clearcote serve
clearcote cloud profile sync shop-account --from-cdp http://127.0.0.1:9222 --domain example.com
# a Playwright storage-state file: context.storage_state(path="state.json")
clearcote cloud profile sync shop-account --from-file state.json --domain example.com --domain example-cdn.net
# sign in by hand: opens a local Clearcote window on a throwaway profile at the URL,
# you sign in and press Enter, and the cookies for the chosen domains are uploaded
clearcote cloud profile sync shop-account --login https://shop.example.com/login --domain example.com--domain(repita para vários) escolhe os cookies que um navegador enviaria para esse domínio: os dele, os dos subdomínios e os dos domínios pais (--domain shop.example.comtambém pega cookies de.example.com, nunca os de um sufixo isolado como.com). Sem--domainou--all-domains, o comando se recusa a rodar, para que nada envie por acidente todos os cookies de um perfil.--all-domainsenvia tudo. Use só em um perfil criado para essa única tarefa.--replaceenviamode: "replace"; o padrão é mesclar.- No código,
profiles.sync(name, …)aceita as mesmas escolhas: exatamente um entrefrom_profile,from_cdp,from_fileoulogin_url(Node:fromProfile,fromCdp,fromFile,loginUrl), depoisdomains=[…]ouall_domains=True(allDomains: true), ereplace=True. Retorna a resposta de importação descrita acima e lançaValueError(umErrorno Node) sem enviar nada quando nenhum cookie corresponde.
from clearcote import launch_persistent_context
from clearcote.cloud import Cloud
cloud = Cloud()
# the same as the command line
cloud.profiles.sync("shop-account", from_file="state.json", domains=["example.com"])
# or upload cookies you have in hand, here from a local profile you signed in with
# (cloud=False: this folder is on your machine, whatever CLEARCOTE_CLOUD says)
ctx = launch_persistent_context("./profiles/shop", cloud=False)
cookies = ctx.cookies("https://shop.example.com") # only this site's cookies
ctx.close()
cloud.profiles.import_cookies("shop-account", cookies) # mode="merge"Enquanto é válido, um cookie vale tanto quanto uma senha: quem tem um cookie de sessão está logado como você. Envie os domínios de que a tarefa precisa e nada mais. Alguns sites vinculam um login ao dispositivo ou ao IP em que ele foi feito e deslogam um cookie copiado; nesses casos, faça login uma vez dentro de uma sessão hospedada com persist: true.
Segredos e 2FA
Uma execução de agente pode digitar valores que o modelo nunca vê: senhas, números de conta e o código atual de um autenticador TOTP. Coloque-os em secrets e faça referência a eles na tarefa como {{name}}:
import os
from clearcote.cloud import Cloud
run = Cloud().runs.create(
"Sign in with {{email}} and {{password}}. If a code is asked for, enter {{otp}}. "
"Then open Orders and read the number of the latest order.",
url="https://shop.example.com/login",
secrets={
"email": "me@example.com",
"password": {"value": os.environ["SHOP_PASSWORD"]},
"otp": {"totp": os.environ["SHOP_TOTP_SECRET"]},
},
schema={"type": "object", "properties": {"order": {"type": "string"}}, "required": ["order"]},
profile={"name": "shop-account", "persist": True}, # next time it starts signed in
)
print(run["status"], run["result"]["output"])| Campo | Tipo | Significado |
|---|---|---|
"name": "value" | string | Um valor simples, digitado no host da url da execução (e nos subdomínios dele). |
value | string | O valor, de 1 a 1024 caracteres. |
totp | base32 string | Um segredo de 2FA no lugar de um valor: a chave de configuração mostrada ao lado do QR code (letras A–Z e dígitos 2–7, no máximo 128; espaços e minúsculas são aceitos). A execução digita o código atual. |
digits | 6 | 8 | Só TOTP. Padrão 6. |
period | 30 | 60 | Só TOTP, em segundos. Padrão 30. |
domains | string[] | Os hosts em que ele pode ser digitado: de 1 a 10 nomes de host como example.com (pelo menos dois rótulos; sem esquema, caminho, porta nem *), cada um incluindo seus subdomínios. Padrão: o host de url. |
- Um segredo é uma string,
{ value, domains? }ou{ totp, domains?, digits?, period? }. No máximo 20 por execução. Os nomes começam com uma letra e usam letras, dígitos e_, com até 32 caracteres. - Um
{{name}}na tarefa que não está emsecretsretorna400(unknown secret "name"). O mesmo vale para um segredo semdomainsem uma execução semurl: não há host ao qual vinculá-lo. Escreva a referência exatamente como{{name}}, sem espaços. - Um segredo que a tarefa nunca menciona é permitido; os
warningsda resposta de criação avisam sobre isso. - Atenção ao host. Por padrão, um segredo fica vinculado ao host de
urle aos subdomínios dele:https://shop.example.com/logincobreshop.example.com, nãologin.example.com. Se o formulário de login estiver em outro host (single sign-on, um provedor de identidade), inclua-o emdomains. - Os códigos TOTP seguem a RFC 6238 com SHA-1, que é o que os apps autenticadores usam. O código é calculado no momento em que é digitado, então é sempre o atual.
- Os segredos pertencem a uma única execução. Eles não são armazenados com um perfil nem mantidos depois da execução: envie-os de novo na próxima (ou rode a próxima em um perfil já logado e pule o login).
O que o modelo vê
Antes de o Jet começar, cada {{name}} na tarefa é substituído por um placeholder aleatório como CCSECRET_password_k3x9qa, e a tarefa recebe uma frase dizendo que os placeholders devem ser digitados exatamente como estão escritos. Isso é tudo o que o modelo recebe. Quando o Jet digita um placeholder, a camada do navegador no servidor coloca no lugar o valor real, ou o código TOTP atual, naquele momento, e só se o host da página for um dos domains do segredo ou um subdomínio de um deles (para um campo dentro de um iframe, o host do frame também). Em qualquer outro host, a etapa para com needs_input (“secret password is not allowed on other.example”) e nada é digitado.
Tudo o que volta é limpo do mesmo jeito: em detail, markdown, no text de cada etapa, no JSON de output e nos eventos, o valor de um segredo, o código TOTP atual dele e o placeholder aparecem como {{name}}. Uma consequência: se a página mostrar um segredo (por exemplo, o endereço de e-mail depois do login) e o seu schema pedir esse dado, você recebe {{email}}, não o endereço.
Modelo de segurança
O que protege o quê, e onde estão os limites:
- Sua chave de API é a sua conta. Com ela é possível iniciar navegadores com o seu saldo, usar seus perfis e ler suas execuções. Mantenha-a em um servidor, nunca em um navegador ou em um app que você distribui.
- Os perfis são privados e criptografados. Cada um é armazenado criptografado (AES-256-GCM, com uma chave por cliente) e aberto apenas nos nossos servidores: para mesclar uma importação, para contar o que contém e no servidor que executa uma sessão nele. O perfil de outro cliente com o mesmo nome é um perfil diferente. Nenhum endpoint retorna o valor de um cookie (uma sessão no perfil pode, é claro, ler os próprios cookies via CDP).
- A sincronização de cookies envia o que você escolhe. Só você pode importar para os seus perfis, dentro dos limites acima (5000 cookies, 3.5 MB), e nunca para um perfil em que uma sessão iniciando ou em execução está salvando. A escolha dos domínios acontece do seu lado:
clearcote cloud profile synceprofiles.sync()se recusam a enviar o conjunto de cookies inteiro, a menos que você passe--all-domains/all_domains=True. - Os segredos ficam lacrados até a execução começar. Eles são armazenados criptografados da mesma forma, dentro das configurações da execução, e abertos apenas quando um servidor pega a execução. São entregues a esse servidor uma única vez, e as configurações armazenadas são apagadas nesse momento. No servidor, ficam na memória e chegam ao processo do Jet pela entrada padrão: nunca em variáveis de ambiente, linhas de comando, logs ou eventos. Se não puderem mais ser abertos quando um servidor pegar a execução, ela termina como
failedcomsession.endReasonsecrets_unreadable. - O modelo nunca recebe um segredo. Ele trabalha com placeholders, e o valor real só é digitado nos hosts que você permitiu. Uma página que tenta convencer o agente a digitar sua senha em outro lugar (prompt injection) recebe uma etapa recusada, não a senha.
- As saídas são limpas. Valores, códigos TOTP e placeholders são substituídos por
{{name}}em tudo o que uma execução retorna ou armazena. - O Jet roda separado das credenciais do próprio servidor. Cada execução é um processo à parte com um ambiente explícito e mínimo: as chaves do servidor e as credenciais do proxy nunca são passadas a ele nem ao navegador. O navegador mantém as proteções do ambiente hospedado: nada de arquivos locais, nada de redes privadas.
E o que isso não cobre:
- O site em que você faz login recebe o valor. Esse é o objetivo; escolha os
domainscom cuidado. - A página pode exibi-lo. Depois que um valor é digitado em um campo comum, a página o exibe. O Jet troca um valor digitado de volta pelo placeholder antes de o modelo ler a página, mas só onde ele aparece exatamente como foi digitado (ou codificado para URL): uma página que o mostra alterado, por exemplo reformatado ou parcialmente oculto, não é detectada. Campos de senha nunca são lidos.
- As gravações mostram a tela. Um valor em um campo comum aparece no vídeo. Deixe
recorddesligado em logins que você não quer registrados. - A tarefa não é secreta. Ela é armazenada com a execução e exibida no painel e na lista de execuções. Nunca escreva um valor na própria tarefa; use sempre
{{name}}. - Links são chaves. Um link de transferência ou de controle permite que quem o tiver controle o navegador, logado, até ele expirar. Envie-o só para a pessoa que deve agir.