Saltar al contenido

Perfiles, sincronización de cookies, secretos y 2FA

Casi todas las tareas que vale la pena automatizar están detrás de un inicio de sesión. Hay tres formas de dejar un navegador alojado con la sesión iniciada sin poner una contraseña en tu código: inicia sesión una vez y guarda la sesión en un perfil, copia en uno las cookies que ya tienes con la sincronización de cookies, o deja que una ejecución de agente escriba el inicio de sesión a partir de secretos que el modelo nunca ve, códigos 2FA incluidos.

Perfiles

Un perfil guarda las cookies, el localStorage y el IndexedDB de una sesión bajo un nombre. Inicia una sesión con profile: { name: "shop-account", persist: true } para cargarlo y volver a guardarlo cuando la sesión termine, o con profile: "shop-account" para cargarlo en modo de solo lectura. Salvo que pases identity o fingerprint, un perfil también trae su propia identidad: el mismo dispositivo, y la misma IP residencial mientras esa IP siga en línea. Las reglas completas están en Perfiles: inicia sesión una sola vez; desde el SDK, consulta un contexto persistente en un perfil en la nube.

Para ver qué contiene un perfil, sin sus valores:

bash
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 enumera hasta 50 sitios, ordenados y sin punto inicial. bytes es el tamaño comprimido. storage indica el almacenamiento de sitio guardado con él (Local Storage, IndexedDB); está vacío en un perfil que solo contiene cookies importadas. Un nombre desconocido da 404 NOT_FOUND.

Ningún endpoint devuelve el valor de una cookie. El contenido de un perfil solo se abre en nuestros servidores: para fusionar una importación, para contar lo que contiene y en el servidor que ejecuta una sesión sobre él.

Si ya tienes la sesión iniciada en algún lugar (tu propio navegador, un Clearcote local, un script de Playwright), copia esas cookies a un perfil en la nube y cada sesión sobre ese perfil empezará con la sesión iniciada:

bash
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": "…" }
  • Cualquier formato de cookie habitual. El formato de CDP (Network.getCookies, Network.Cookie / CookieParam) y el de Playwright (context.cookies(), las cookies de un archivo de storage state) funcionan tal cual; una url puede reemplazar a domain. Sin expires, con expires: -1 (cualquier valor hasta 0) o con session: true es una cookie de sesión, y una cookie que ya caducó se omite. sameSite es Lax, Strict o None en mayúsculas o minúsculas, y None requiere secure: true.
  • Validadas como lo hace Chrome. Una cookie que Chrome rechazaría (un ; en un valor, sameSite: "None" sin secure, una cookie __Secure- o __Host- que incumple sus reglas, una ruta que no empieza por /) convierte toda la importación en un 400 cuyo mensaje la nombra.
  • Se guardan name, value, domain (en minúsculas), path (por defecto /), secure, httpOnly, sameSite (solo si lo enviaste) y expires (ausente en una cookie de sesión). Los demás campos, como partitionKey, se descartan.
  • mode: "merge" (por defecto) añade tus cookies y reemplaza las que tengan el mismo nombre, dominio y ruta. mode: "replace" deja las cookies del perfil exactamente como la lista que envías. En ambos casos se conservan el localStorage y el IndexedDB del perfil.
  • Límites: como máximo 5000 cookies por solicitud, y 5000 en el perfil tras una fusión (400 TOO_MANY); nombres de hasta 256 caracteres, valores de hasta 4096, rutas de hasta 1024; el perfil completo, como máximo 3.5 MB comprimido (413 TOO_LARGE); 60 importaciones cada 10 minutos.
  • Si el perfil todavía no existe, se crea. Mientras una sesión que guarda en el perfil (persist: true) se está iniciando o ejecutando, una importación se rechaza con 409 PROFILE_IN_USE: la sesión la sobrescribiría al terminar.
  • Las cookies de sesión importadas (sin caducidad) se cargan en las siguientes sesiones como cualquier otra. Una sesión que guarda el perfil las descarta, igual que un navegador real al reiniciarse, así que vuelve a importarlas si las necesitas después.

La respuesta indica cuántas cookies tiene el perfil tras la importación (cookies) y cuántas de las tuyas aceptó (imported: las cookies caducadas y los duplicados quedan fuera), y enumera los primeros 50 de sus dominios, ordenados.

Desde tu máquina, con el SDK

El comando clearcote lee las cookies de donde las tengas y sube solo los dominios que indiques:

bash
# 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 (repítelo para varios) elige las cookies que un navegador enviaría a ese dominio: las suyas, las de sus subdominios y las de sus dominios superiores (--domain shop.example.com también toma las cookies de .example.com, nunca las de un sufijo a secas como .com). Sin --domain ni --all-domains, el comando se niega a ejecutarse, para que nada suba por accidente todas las cookies de un perfil.
  • --all-domains lo sube todo. Úsalo solo con un perfil creado para esta única tarea.
  • --replace envía mode: "replace"; por defecto se fusiona.
  • Desde el código, profiles.sync(name, …) acepta las mismas opciones: exactamente una de from_profile, from_cdp, from_file o login_url (Node: fromProfile, fromCdp, fromFile, loginUrl), luego domains=[…] o all_domains=True (allDomains: true), y replace=True. Devuelve la respuesta de importación descrita arriba, y lanza ValueError (un Error en Node) sin subir nada cuando ninguna cookie coincide.
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"

Mientras es válida, una cookie vale tanto como una contraseña: quien tenga una cookie de sesión tiene la sesión iniciada como tú. Sube los dominios que necesita la tarea y nada más. Algunos sitios vinculan un inicio de sesión al dispositivo o a la IP desde donde se hizo y cierran la sesión de una cookie copiada; en esos casos, inicia sesión una vez dentro de una sesión alojada con persist: true.

Secretos y 2FA

Una ejecución de agente puede escribir valores que el modelo nunca ve: contraseñas, números de cuenta y el código vigente de un autenticador TOTP. Ponlos en secrets y haz referencia a ellos en la tarea 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"])
Esta pestaña se ejecuta en tu máquina.
CampoTipoSignificado
"name": "value"stringUn valor simple, que se escribe en el host de la url de la ejecución (y sus subdominios).
valuestringEl valor, de 1 a 1024 caracteres.
totpbase32 stringUn secreto de 2FA en lugar de un valor: la clave de configuración que aparece junto al código QR (letras A–Z y dígitos 2–7, como máximo 128; se admiten espacios y minúsculas). La ejecución escribe el código vigente.
digits6 | 8Solo TOTP. Por defecto 6.
period30 | 60Solo TOTP, en segundos. Por defecto 30.
domainsstring[]Los hosts en los que se puede escribir: de 1 a 10 nombres de host como example.com (al menos dos etiquetas; sin esquema, ruta, puerto ni *), cada uno con sus subdominios. Por defecto: el host de url.
  • Un secreto es un string, { value, domains? } o { totp, domains?, digits?, period? }. Como máximo 20 por ejecución. Los nombres empiezan por una letra y usan letras, dígitos y _, hasta 32 caracteres.
  • Un {{name}} en la tarea que no está en secrets da un 400 (unknown secret "name"). Lo mismo un secreto sin domains en una ejecución sin url: no hay ningún host al que vincularlo. Escribe la referencia exactamente como {{name}}, sin espacios.
  • Se admite un secreto que la tarea nunca menciona; los warnings de la respuesta de creación lo indican.
  • Cuidado con el host. Por defecto, un secreto queda vinculado al host de url y a sus subdominios: https://shop.example.com/login cubre shop.example.com, no login.example.com. Si el formulario de inicio de sesión está en otro host (inicio de sesión único, un proveedor de identidad), inclúyelo en domains.
  • Los códigos TOTP siguen la RFC 6238 con SHA-1, que es lo que usan las apps de autenticación. El código se calcula en el momento en que se escribe, así que siempre es el vigente.
  • Los secretos pertenecen a una sola ejecución. No se guardan con un perfil ni se conservan después de la ejecución: envíalos de nuevo con la siguiente (o ejecuta la siguiente sobre un perfil con la sesión iniciada y sáltate el inicio de sesión).

Lo que ve el modelo

Antes de que Jet arranque, cada {{name}} de la tarea se reemplaza por un marcador aleatorio como CCSECRET_password_k3x9qa, y la tarea recibe una frase que indica que los marcadores deben escribirse exactamente como están. Es todo lo que el modelo recibe. Cuando Jet escribe un marcador, la capa del navegador en el servidor lo sustituye en ese momento por el valor real, o por el código TOTP vigente, y solo si el host de la página es uno de los domains del secreto o un subdominio de uno de ellos (para un campo dentro de un iframe, también el host del frame). En cualquier otro host el paso se detiene con needs_input («secret password is not allowed on other.example») y no se escribe nada.

Todo lo que vuelve se limpia de la misma manera: en detail, markdown, el text de cada paso, el JSON de output y los eventos, el valor de un secreto, su código TOTP vigente y su marcador aparecen como {{name}}. Una consecuencia: si la página muestra un secreto (por ejemplo, la dirección de correo tras iniciar sesión) y tu schema la pide, recibes {{email}}, no la dirección.

Modelo de seguridad

Qué protege qué, y dónde están los límites:

  1. Tu clave de API es tu cuenta. Con ella se pueden iniciar navegadores con tu saldo, usar tus perfiles y leer tus ejecuciones. Guárdala en un servidor, nunca en un navegador ni en una app que distribuyas.
  2. Los perfiles son privados y están cifrados. Cada uno se guarda cifrado (AES-256-GCM, con una clave por cliente) y solo se abre en nuestros servidores: para fusionar una importación, para contar lo que contiene y en el servidor que ejecuta una sesión sobre él. El perfil de otro cliente con el mismo nombre es un perfil distinto. Ningún endpoint devuelve el valor de una cookie (una sesión sobre el perfil sí puede, claro, leer sus propias cookies por CDP).
  3. La sincronización de cookies sube lo que tú eliges. Solo tú puedes importar a tus perfiles, dentro de los límites anteriores (5000 cookies, 3.5 MB), y nunca a uno en el que una sesión que se está iniciando o ejecutando está guardando. La elección de dominios se hace de tu lado: clearcote cloud profile sync y profiles.sync() se niegan a subir un almacén de cookies completo salvo que pases --all-domains / all_domains=True.
  4. Los secretos permanecen sellados hasta que empieza la ejecución. Se guardan cifrados de la misma manera, dentro de la configuración de la ejecución, y solo se abren cuando un servidor toma la ejecución. Se entregan a ese servidor una sola vez, y en ese momento se borra la configuración guardada. En el servidor permanecen en memoria y llegan al proceso de Jet por su entrada estándar: nunca en variables de entorno, líneas de comandos, logs ni eventos. Si ya no se pueden abrir cuando un servidor toma la ejecución, esta termina en failed con session.endReason secrets_unreadable.
  5. El modelo nunca recibe un secreto. Trabaja con marcadores, y el valor real solo se escribe en los hosts que permitiste. Una página que intenta convencer al agente de escribir tu contraseña en otro lugar (prompt injection) recibe un paso rechazado, no la contraseña.
  6. Las salidas se depuran. Los valores, los códigos TOTP y los marcadores se reemplazan por {{name}} en todo lo que una ejecución devuelve o guarda.
  7. Jet se ejecuta aparte de las credenciales del propio servidor. Cada ejecución es un proceso independiente con un entorno explícito y mínimo: las claves del servidor y las credenciales del proxy nunca se le pasan, ni a él ni al navegador. El navegador mantiene las protecciones del servicio alojado: sin archivos locales, sin redes privadas.

Y lo que esto no cubre:

  • El sitio en el que inicias sesión recibe el valor. Ese es el objetivo; elige domains con cuidado.
  • La página puede mostrarlo. Después de escribir un valor en un campo normal, la página lo muestra. Jet vuelve a cambiar un valor escrito por su marcador antes de que el modelo lea la página, pero solo donde aparece exactamente como se escribió (o codificado como URL): una página que lo muestra modificado, por ejemplo reformateado u oculto en parte, no se detecta. Los campos de contraseña nunca se leen.
  • Las grabaciones muestran la pantalla. Un valor en un campo normal aparece en el video. Deja record desactivado en los inicios de sesión que no quieras que queden registrados.
  • La tarea no es secreta. Se guarda con la ejecución y se muestra en el panel y en la lista de ejecuciones. Nunca escribas un valor en la propia tarea; usa siempre {{name}}.
  • Los enlaces son llaves. Un enlace de traspaso o de control permite a quien lo tenga manejar el navegador, con la sesión iniciada, hasta que caduque. Envíalo solo a la persona que debe actuar.

Actualizado el 5 oct 2026 · SDK 0.70.5 · navegador r63

¿Te resultó útil esta página?