Secretos.

Un secreto es un token o una clave que guardas en tu cuenta de NaN para que tus automatizaciones lo usen sin que tengas que pegarlo en ningún sitio: un token de GitHub, una API key de uno de tus servicios o tu propia clave con un proveedor de IA. Lo guardas una vez y luego lo eliges por su nombre en las automatizaciones, runs y ajustes que lo necesitan.

Los secretos son de solo escritura. Una vez guardado, nadie puede volver a leer un valor: ni el portal, ni la CLI, ni la API, ni tú. Puedes reemplazar un valor, nunca verlo.

Para añadir uno ya, ve a Añade un secreto.

Qué es un secreto

Cada secreto tiene:

Dónde vive. El valor se cifra con una clave que pertenece solo a tu cuenta antes de guardarse, y solo se conserva el valor cifrado. Se descifra únicamente cuando arranca un run que lo ha recibido, y solo los secretos que ese run ha recibido. NaN nunca envía un secreto a ningún sitio para comprobarlo: un token erróneo o caducado se nota cuando un run lo usa.

Qué ves en lugar del valor. La lista del portal, nan secrets ls y la API muestran solo los metadatos:

• Una pista: los 4 últimos caracteres, como …a1b2, cuando el valor tiene al menos 20 caracteres y esos 4 son letras, dígitos, _ o -. Si no, no hay pista. NaN no guarda ningún otro rastro del valor, ni siquiera un hash.
• El tamaño del valor, la descripción y, en una provider key, su proveedor y su URL base.
• Used by: las automatizaciones que lo usan (o Not used by any automation).
• Updated, Last used (o never) y Last changed from. Last used se actualiza cuando un run recibe el secreto, como mucho una vez por minuto.

Dos tipos

Para enterarte en Slack, Microsoft Teams o Discord cuando una automatización te necesita no hace falta un secreto: añade un canal de notificaciones. Su URL se guarda de solo escritura, como un secreto.

Secret

El valor se guarda tal cual lo pegas, hasta 16 KiB: nunca se recorta, así que una clave pegada nunca cambia sin que te enteres. Tiene que ser texto (UTF-8), sin caracteres de control salvo tabuladores y saltos de línea. Los saltos de línea dentro del valor están bien (una clave privada PEM, por ejemplo), pero no al principio ni al final.

Provider key

Una provider key tiene además un Provider, que se fija al crearla (para cambiar de proveedor, añade otra clave):

Su valor es la clave: una línea sin espacios, de 8 a 4096 caracteres ASCII normales. Una clave OpenAI-compatible tiene además una Base URL: la raíz del endpoint, que suele acabar en /v1, por ejemplo https://api.together.xyz/v1. Es lo único de un secreto que puedes cambiar además del valor y la descripción.

La lista la muestra como Provider key · Anthropic (o su proveedor), con su URL base cuando la tiene.

Reglas de la URL base

NaN comprueba la URL base cuando la guardas, y nunca se conecta a ella: solo lo hace el agente de tu workspace.

• Solo https, hasta 512 caracteres. Un puerto está bien (https://llm.example.com:8443/v1).
• Un nombre de host público (con al menos un punto) o una dirección IP pública. Se rechazan localhost, las direcciones privadas y de enlace local, y los nombres que acaban en .local, .internal, .lan, .home.arpa o .svc.
• No los hosts de NaN (nan.builders, helmcode.com y sus subdominios): para los modelos de NaN, elige NaN como inferencia.
• Sin user:password@, sin query string (?...), sin fragmento (#...) y sin espacios.

Gestiona los secretos en el portal

Tus secretos están en tus ajustes de cloud.nan.builders: abre Settings y luego Secrets, debajo de Tokens.

Añade un secreto

1. Pulsa Add secret y escribe el Name.
2. Elige el Kind: Secret para un token que reciben tus automatizaciones, Provider key para tu propia clave de un proveedor de IA. En una provider key, elige el Provider y, para OpenAI-compatible, escribe la Base URL.
3. Pega el Value: hasta 16 KiB en un secreto, una línea de 8 a 4096 caracteres en una provider key.
4. Añade una Description si quieres y pulsa Save secret.

Si el guardado falla, el portal borra el valor por seguridad (“The value was cleared for safety. Paste it again to retry.”): corrige lo que te indica y vuelve a pegarlo.

Reemplaza el valor

Replace value, en la fila del secreto, pide el valor nuevo. El anterior se sobrescribe y no se puede recuperar. El nombre, la descripción y todas las automatizaciones que usan el secreto se quedan como están: Cuando reemplazas o borras un secreto explica qué runs reciben el valor nuevo.

Cambia la descripción o la URL base

Description edita la descripción. Base URL (solo en una provider key OpenAI-compatible) edita su URL base, con las mismas reglas. El nombre, el tipo y el proveedor no se pueden cambiar.

Borra un secreto

Delete te pide confirmación, y el secreto desaparece para siempre. Mientras una automatización lo use, como uno de sus secretos o como su provider key, el borrado se rechaza y el portal lista esas automatizaciones: quítalo primero de ellas.

Gestiona los secretos desde la CLI

Con la CLI de NaN 0.1.33 o posterior, si tu cuenta tiene la API de escritura (se está abriendo poco a poco):

nan secrets ls                                           # nombres y metadatos, nunca valores
nan secrets show GITHUB_TOKEN                            # los metadatos de un secreto
nan secrets set GITHUB_WRITE_TOKEN --value-file ./token.txt --description "repo acme/api, write"
gh auth token | nan secrets set GITHUB_READ_TOKEN --value-stdin
nan secrets set ANTHROPIC_KEY --value-file key.txt --kind provider_key --provider anthropic
nan secrets set TOGETHER_KEY --value-file key.txt --kind provider_key \
  --provider openai_compatible --base-url https://api.together.xyz/v1
nan secrets edit GITHUB_WRITE_TOKEN --description "expires in December"
nan secrets rm GITHUB_READ_TOKEN

• El valor nunca va en la línea de comandos, donde se quedaría en el historial de tu shell y lo verían otros programas de tu máquina. --value-file PATH lo lee de un archivo, --value-stdin de una tubería, y --value-stdin se niega a leer de la terminal, así que un valor nunca se teclea en claro. Si has escrito un valor en la línea de comandos por error, ya está en tu historial: revócalo donde se emitió y guarda uno nuevo.
• Si otros usuarios de tu máquina pueden leer el archivo, la CLI te avisa (hazle chmod 600).
• Se quita un salto de línea al final (los archivos suelen acabar con uno).
• set crea el secreto, o reemplaza el valor del que tiene ese nombre. --kind (generic o provider_key), --provider (anthropic, openai, gemini o openai_compatible) y el nombre se fijan al crearlo.
• edit cambia la descripción (--description "" la vacía) o la URL base de una clave OpenAI-compatible. No el valor: eso es set.
• rm pregunta antes de borrar (si respondes que no, sale con código 1); --yes se salta la pregunta en scripts. Se rechaza mientras una automatización use el secreto, y la CLI te dice cuáles.
• show, edit y rm aceptan el nombre del secreto o su id. ls, show, set y edit aceptan --json e imprimen los metadatos en JSON.
• Hasta que tu cuenta tenga la API de escritura, los comandos que cambian secretos te dicen que uses el portal y salen con código 64.

La CLI usa la primera credencial que encuentra: --token-file, luego tu sesión de nan auth login, luego NAN_TOKEN y luego un token guardado con nan auth login --api-token. Con un token, necesita secrets:read para listar secretos o encontrar uno (show, edit y rm buscan antes el secreto, incluso por id), y secrets:write para cambiarlos. Un token solo con secrets:write puede crear un secreto nuevo con set; reemplazar el valor de uno que ya existe necesita los dos. Una API key (sk-...) se rechaza antes de enviar nada.

Gestiona los secretos desde la API

Las mismas operaciones están en la API, en https://api.nan.builders/v1/secrets:

Qué credenciales sirven:

• Tu sesión de la CLI, de nan auth login en tu propia máquina.
• Un token de plataforma con el scope de la ruta. Lo creas en el portal, Settings → Tokens, con sesión iniciada en el navegador: un token con un scope secrets: no se puede crear desde la CLI ni desde otro token. Los dos scopes son independientes: secrets:write no incluye secrets:read. Consulta Tokens para automatizaciones.
• Nunca una API key (sk-...), la clave de dentro de un workspace ni una sesión de una CLI antigua: reciben 403 credential_not_allowed (workspace_key_not_allowed para la clave del workspace). Un token sin el scope recibe 403 token_scope_denied.

Si tu cuenta todavía no tiene la API de escritura, todas las rutas de /v1/secrets responden 404.

Crea un secreto desde un archivo, para que el valor nunca aparezca en el historial de tu shell ni en una lista de procesos:

jq -n --rawfile v token.txt '{name: "GITHUB_WRITE_TOKEN", value: ($v | rtrimstr("\n")), description: "repo acme/api, write"}' |
  curl https://api.nan.builders/v1/secrets \
    -H "Authorization: Bearer $NAN_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-github-write-token-1" \
    --data-binary @-

La respuesta son los metadatos del secreto. Nunca lleva un valor, en ninguna ruta:

{
  "id": "…",
  "object": "secret",
  "name": "GITHUB_WRITE_TOKEN",
  "kind": "generic",
  "provider": null,
  "base_url": null,
  "hint": "…a1b2",
  "value_bytes": 93,
  "description": "repo acme/api, write",
  "used_by": [{ "id": "…", "name": "PR review api" }],
  "updated_by": "platform_token",
  "created_at": "…",
  "updated_at": "…",
  "last_used_at": null
}

• Idempotencia. Idempotency-Key (de 1 a 128 caracteres de A-Z a-z 0-9 . _ : -) hace seguro reintentar una creación: la misma clave con el mismo nombre, tipo y proveedor devuelve el secreto ya creado (200), y el valor del reintento se ignora. La misma clave para un secreto distinto es 409 idempotency_key_reused. Borrar el secreto libera su clave. Sin la cabecera, un reintento recibe 409 name_taken.
• Cuerpo de la petición. Un objeto JSON de hasta 32 KiB, solo con los campos documentados.
• Los errores llegan como {"error": {"message", "type", "param", "code"}}. param nombra el campo que está mal y nunca repite lo que enviaste. secret_in_use y secrets_too_large añaden las automations afectadas.
• Límite de ritmo. Los cambios en secretos (crear, reemplazar, editar, borrar) comparten un mismo cupo por cuenta: una ráfaga de 30 y luego 120 por hora, sumando el portal, la CLI y la API. Por encima, 429 rate_limited.

Todas las rutas, cuerpos y errores están en Referencia de la API → Secrets.

Usa secretos en automatizaciones

Un secreto no hace nada hasta que se lo das a una automatización. Los secretos solo llegan a los runs de las automatizaciones a las que los asignas: un run que lanzas con nan run o desde la pestaña Runs de un workspace nunca recibe ninguno (salvo la provider key que elijas para ese run).

Asigna un secreto

En la tarjeta Secrets de la automatización, Add a secret y elige, para cada uno:

• El secreto, por su nombre.
• El nombre de la variable con el que lo ve el run. Puede ser distinto del nombre del secreto, y no puede ser un nombre que fije el propio entorno de ejecución: OPENAI_API_KEY, OPENAI_BASE_URL, HOME, USER, PATH, LANG, CREDENTIALS_DIRECTORY ni nada que empiece por NAN_, PI_ o HERMES_.
• Quién lo recibe:

Desde la CLI o la API, la misma asignación es una línea de los secrets de la automatización:

secrets:
  - { secret: GITHUB_READ_TOKEN, env: GITHUB_TOKEN, exposure: agent }
  - { secret: GITHUB_WRITE_TOKEN, env: GITHUB_TOKEN, exposure: actions }

El mismo nombre de variable puede aparecer una vez por opción. Una automatización admite hasta 20 secretos, y todo lo que recibe un run (sus secretos y su provider key) puede sumar como mucho 48 KiB. Un run solo arranca si se pueden leer todos los secretos que necesita; si no, falla con secrets_unavailable y nada se ejecuta sin ellos. El resto de los ajustes de la automatización están en Automatizaciones.

El patrón del token de GitHub

La configuración habitual de GitHub usa dos fine-grained personal access tokens, cada uno limitado al único repositorio en el que trabaja la automatización, con fecha de caducidad:

Las dos filas usan el nombre de variable GITHUB_TOKEN, cada una para su receptor: el agente lee con uno y NaN escribe con el otro. Un repositorio público que el agente solo lee no necesita token de lectura. El detalle de cada permiso está en Un token de GitHub para las acciones, y un recorrido completo en la guía del PR gatekeeper.

Tu propia clave de proveedor

Una provider key no se asigna como variable: la eliges como inferencia. En un run o una automatización, pon Inference en My own key, elige la Provider key y escribe el Model. El agente de ese run recibe la clave en su entorno, como la espera ese agente, y llama con ella a tu proveedor. Desde la CLI, nan run --byok-secret ANTHROPIC_KEY --model claude-sonnet-4-5 "..." recibe el nombre del secreto, nunca la clave.

El flujo completo, quién puede usarla, la facturación y sus propios errores están en Usa tu propia clave de proveedor (BYOK) y, para las automatizaciones, en Usa tu propia clave de proveedor.

Mantén tus secretos a salvo

Enmascarado en logs y eventos

Cuando arranca un run, todos los valores que recibe (sus secretos, su provider key y los secretos del propio archivo de entorno del workspace) se añaden a una máscara. Antes de guardar o mostrar nada de lo que escribe el run, cada aparición se sustituye por [masked]:

• En los eventos y el log del run, su resultado y los textos libres de una propuesta: mensajes de commit, títulos y cuerpos de pull requests, comentarios, reviews y las rutas de los archivos cambiados.
• El propio valor y sus codificaciones habituales: base64, codificado para URL y escapado para JSON.
• El principio de un valor impreso por separado: si el agente imprime los primeros caracteres de un token (GITHUB_TOKEN=ghp_6Z8A...), también se enmascara un fragmento de 8 caracteres o más.

El enmascarado tiene límites. Los valores de menos de 8 caracteres no se enmascaran nunca, así que usa secretos largos de verdad. Pueden escaparse los fragmentos de menos de 8 caracteres, el final de un valor o un fragmento pegado a más letras o dígitos. Un nombre de rama o una etiqueta que contendría un secreto no se reescribe: la propuesta se rechaza (proposal_invalid). Si el diff de un push contiene el valor de uno de los secretos del run, el portal te avisa antes de que lo apruebes.

El enmascarado protege lo que NaN guarda y muestra. No impide que un agente que tiene un secreto lo envíe a algún sitio.

Qué puede hacer el agente con un secreto

Un agente que recibe un secreto como Agent (read access) puede leerlo, imprimirlo, usarlo y enviarlo por la red, como cualquier programa que ejecutes con esa variable puesta. Es así a propósito: es como el agente clona, trae cosas y llama a tus servicios. Lo que haga con él es responsabilidad tuya, así que:

• Dale al agente solo tokens de lectura. Deja todo token que pueda escribir como Actions only: esos nunca llegan al agente ni a ningún modelo de IA.
• Limita cada token al único repositorio o recurso para el que es, con fecha de caducidad.
• Recuerda que al agente le llega texto escrito por otros. Una entrega de webhook, una pull request, una issue o un test dentro de una pull request pueden intentar que el agente imprima o envíe un secreto (prompt injection). Por eso Fresh clone per run ignora por defecto las pull requests de forks y de colaboradores externos: consulta Pull requests de forks y de colaboradores externos.
• En una provider key, pon un límite de gasto en tu proveedor.

El peligro está en la escritura

Un token que puede escribir vale mucho más para quien lo roba que uno que solo puede leer: puede subir código, hacer merge, borrar ramas o cambiar ajustes.

• Un token de escritura de GitHub en manos del agente puede hacer todo lo que le permitan sus permisos, sin pasar por la aprobación de tu automatización. Asígnalo como Actions only (write access), para que solo lo use el paso de aplicación de NaN, y solo para las acciones que permitiste.
• Un token de plataforma de NaN con secrets:write puede reemplazar cualquiera de tus secretos (por ejemplo, cambiar el token de GitHub con el que hace push una automatización). Uno con automations:write puede crear una automatización que reciba todos tus secretos, con las instrucciones que quiera y nada esperando tu aprobación: es como leerlos todos. Da esos scopes solo a los tokens que los necesitan, con una caducidad corta, y nunca se los des a un agente.
• Ejecuta nan auth login en tu propia máquina, nunca dentro de un workspace: los agentes que corren allí pueden leer la sesión que guarda, y una sesión de la CLI puede cambiar tus secretos.

Rótalos

Mejor tokens de vida corta, y rótalos antes de que caduquen o en cuanto uno pueda haberse filtrado:

1. Crea el token nuevo en su origen (GitHub, tu proveedor).
2. Replace value en el portal, o nan secrets set NAME --value-file new.txt. El nombre se mantiene, así que todas las automatizaciones lo siguen usando sin cambiar nada.
3. Revoca el token antiguo en su origen. NaN no puede revocar un token por ti: reemplazarlo en NaN no impide que el antiguo siga funcionando en otros sitios.

Si un token se ha filtrado, revócalo primero en su origen y luego reemplázalo. Anotar la fecha de caducidad en la Description (“expires 2026-12-31”) te ayuda a ver qué toca renovar.

Cuando reemplazas o borras un secreto

• Reemplazar un valor se aplica al siguiente run que arranque, incluidos los que ya están en cola: un run lee sus secretos cuando arranca. Los runs que ya están trabajando conservan el valor con el que arrancaron. El reemplazo se rechaza con 409 secrets_too_large si el valor nuevo haría que alguna de las automatizaciones que lo usan pasara de 48 KiB por run.
• Borrar se rechaza con 409 secret_in_use mientras una automatización use el secreto, como uno de sus secretos o como su provider key. La respuesta lista esas automatizaciones: cámbialas antes y luego bórralo. Un run con tu propia clave cuya provider key se borró después de ponerlo en cola falla con secret_missing.

Quién lo cambió por última vez

Cada secreto registra desde dónde llegó su último cambio: Last changed from en el portal (Browser, CLI o API token), CHANGED FROM en nan secrets ls y updated_by en la API (browser_session, cli_session o platform_token). Un cambio que no hiciste tú salta a la vista: si ves uno, revoca en Settings → Tokens los tokens que ya no usas y reemplaza el secreto.

Límites

Añadir un secreto o reemplazar un valor necesita una membresía activa. Sin ella puedes seguir listando y borrando tus secretos.

Si algo sale mal