Runs de agentes.

Un run le da una tarea a un agente dentro de uno de tus workspaces y lo deja trabajar solo. Escribes lo que quieres que haga, eliges el agente (Pi, Pi + Gentle Shell o Hermes, entre los que tengas instalados en ese workspace) y la carpeta, y el run se encarga del resto. Sigue adelante aunque cierres la página o la terminal.

Mientras trabaja, sigues su log en directo. Cuando termina tienes su resultado y, si la carpeta es un repositorio git, una rama con sus cambios lista para que la revises.

Puedes lanzar un run de tres formas, y las tres ven los mismos runs:

• Desde la pestaña Runs de tu workspace en el portal.
• Desde tu terminal, con nan run.
• Desde tus propios scripts, con la API.

Para lanzar la misma tarea una y otra vez, desde un webhook, con una programación o con acciones que esperan tu aprobación, guárdala como una automatización.

Antes de empezar

• Un workspace encendido, con al menos un agente instalado: Pi, Pi + Gentle Shell o Hermes. Se instalan desde el panel de Software del workspace. Consulta Elige el agente.
• Un plan con inferencia, o tu propia clave de proveedor. Con la inferencia de NaN (lo predeterminado), un run usa la clave de inferencia del propio workspace, y lo que gasta el agente cuenta para el uso de tu plan como cualquier otra petición. Con tu propia clave de proveedor, la factura tu proveedor y no hace falta un plan con inferencia: basta con un workspace propio activo.

Elige el agente

Un run puede usar uno de tres agentes. Cada uno necesita sus programas instalados en el workspace:

Los runs y las automatizaciones solo aceptan un agente que el workspace tenga instalado:

• En el portal, la lista Agent de un run nuevo o de una automatización solo muestra los agentes de ese workspace. Si no tiene ninguno, el portal te lo indica y enlaza a su panel de Software: instala uno ahí primero.
• Desde la CLI o la API, pedir un agente que el workspace no tiene se rechaza antes de crear el run, con 409 agent_not_installed (el error señala el campo agent). nan run sale con código 4. Instala el agente desde el panel de Software, o elige otro, y vuelve a intentarlo.
• Una automatización conserva su agente aunque luego lo quites del workspace (el editor lo marca (not installed)), pero sus runs se rechazan hasta que lo vuelvas a instalar o elijas otro agente. Si cambias el workspace de una automatización y el nuevo no tiene su agente, el editor pasa a uno que sí tenga y te lo indica.

Para saber desde un script qué agentes puede usar un workspace, lee su campo run_agents: consulta Referencia de la API → Workspaces.

Lanza un run desde el portal

Abre la pestaña Runs

Entra en cloud.nan.builders/workspaces y abre un workspace. Junto a Overview, Console, SSH keys, Events y Backups tienes la pestaña Runs. Su tarjeta Agent runs lista los runs de ese workspace, del más reciente al más antiguo, cada uno con su estado, el agente, la tarea, cuándo empezó, cuánto duró y los tokens que gastó.

Rellena el formulario

Pulsa New run y rellena el formulario (el portal está en inglés):

Campo	Qué es
Agent	El agente: Pi, Pi + Gentle Shell o Hermes. La lista solo muestra los agentes instalados en el workspace. Consulta Elige el agente.
Task	La tarea, con tus palabras, como se la escribirías al agente en un chat. Hasta 32 KiB (el contador bajo la caja te dice los bytes que llevas).
Folder	La carpeta donde trabaja el agente. Por defecto es /home/nan y tiene que estar dentro de ella.
Separate branch	Rama aparte: Auto (por defecto), On u Off. En un repositorio git, el agente trabaja en su propia rama y tu checkout se queda como está. Consulta Dónde trabaja el agente.
Time limit	El tiempo máximo: 30 min por defecto, igual que en la CLI y la API. Las opciones son 15 min, 30 min, 1 hour y 2 hours (1 hora y 2 horas). El run se para al llegar a él.
Inference	La inferencia: NaN (included in your plan), la predeterminada (aparece como NaN (not in your plan) si tu plan no incluye inferencia), o My own key, una Provider key tuya y el Model que usar. Consulta Usa tu propia clave de proveedor.

Pulsa Start run, o Ctrl+Enter (⌘+Enter en un Mac) desde la caja de la tarea.

Síguelo en directo

Haz clic en un run de la lista para abrir su página. Arriba ves su estado, el workspace, el agente, la carpeta, cuánto lleva, los tokens que ha gastado, su tiempo máximo y la tarea. Debajo, en Output, el log se va llenando en directo mientras el agente trabaja: lo que dice, las herramientas que usa y lo que le responden. Haz clic en una línea Tool call o Tool result para desplegarla. Cuando el run termina, la página muestra cómo ha acabado, el resumen del agente y, si la hay, la rama con sus cambios.

Puedes cerrar la página cuando quieras. El run sigue, y su página estará ahí cuando vuelvas.

Cancélalo, si hace falta

Cancel run para el run en unos segundos. El portal te pide confirmación antes.

Dónde trabaja el agente

Lo que pasa con tus archivos depende de la carpeta (Folder) que elijas y de la opción Separate branch.

Con rama aparte, el agente no toca tu checkout. Trabaja en una copia aparte del repositorio (un git worktree), en una rama nueva que se llama nan-run/ seguido de los 8 primeros caracteres del id del run, por ejemplo nan-run/6f1c2a9b. Cuando el agente acaba, todo lo que ha cambiado queda en un commit en esa rama. El run nunca hace push: la rama se queda en el repositorio dentro de tu workspace y tú decides qué hacer con ella. Si el agente no ha cambiado nada, la rama se borra.

Para revisar los cambios e incorporarlos, abre una terminal en tu workspace (por SSH o desde la pestaña Console) y, desde el repositorio:

git log -p HEAD..nan-run/6f1c2a9b
git merge nan-run/6f1c2a9b

Sin rama aparte, el agente trabaja directamente en la carpeta y no hay rama. Úsalo con carpetas que no son repositorios, o cuando quieras los cambios ahí mismo.

La carpeta tiene que estar dentro de /home/nan, tu carpeta personal en el workspace.

Estados de un run

El portal muestra los mismos estados en inglés y con mayúscula, por ejemplo Running, Succeeded o Cancelled.

Desde la CLI y la API el tiempo máximo va de 60 segundos a 2 horas. El portal ofrece 15 min, 30 min, 1 hora y 2 horas, con 30 min por defecto.

Cuántos runs a la vez

Cuántos runs trabajan a la vez depende del tamaño del workspace:

Además, los runs con la inferencia de NaN comparten tu concurrencia de inferencia, así que puedes tener como mucho 5 de ellos trabajando a la vez entre todos tus workspaces (8 con Premium). Los runs con tu propia clave de proveedor tienen su propio límite: hasta 8 a la vez entre todos tus workspaces.

Los runs que pasan de esos límites no se rechazan: esperan en una cola y arrancan por orden de llegada. En la cola caben hasta 20 runs por workspace y 50 en total, y puedes crear hasta 60 runs por hora.

Cada run trabaja en su propio proceso dentro del workspace, con su parte de CPU y de memoria. Si uno se descontrola, se para solo ese: tus sesiones SSH y tus agentes siempre encendidos siguen funcionando.

Inferencia y secretos

Los runs con la inferencia de NaN usan la clave de inferencia del workspace, la misma que usan sus agentes cuando trabajas con ellos a mano. Sus peticiones cuentan para el uso de tu plan como cualquier otra. Los runs con tu propia clave de proveedor usan tu clave en su lugar, y nunca reciben la del workspace.

Los secretos del archivo de entorno de tu workspace, como esa clave de inferencia o un token de bot de Telegram, aparecen como [masked] en los logs y resultados de los runs, así que un log no los filtra. Consulta Enmascarado en logs y eventos.

Los secretos que guardas en tus ajustes no se les dan a estos runs: solo llegan a los runs de las automatizaciones a las que los asignas. Consulta Secretos.

Usa tu propia clave de proveedor (BYOK)

Un run puede usar tu propia clave con un proveedor de IA en lugar de la inferencia de NaN: trae tu propia clave (BYOK, bring your own key). El agente trabaja exactamente igual, pero sus llamadas al modelo salen de tu workspace directamente hacia tu proveedor, con tu clave, y es tu proveedor quien las factura.

Lo eliges en cada run y en cada automatización: NaN sigue siendo lo predeterminado.

Proveedores

OpenAI-compatible es cualquier endpoint que hable la API de OpenAI en una URL base que tú indicas: un proveedor como Together, Groq u OpenRouter, o tu propio servidor, siempre que se pueda alcanzar desde internet por https.

Escribe el id del modelo tal como lo llama tu proveedor. NaN no lo comprueba con tu proveedor: un id equivocado, o una clave equivocada, aparece como un run fallido con el error de tu proveedor en su log (con la clave enmascarada).

Guarda tu clave como provider key

Abre tus ajustes en el portal, Secrets, y pulsa Add secret. Rellena (el portal está en inglés):

• Name: cómo la nombran los runs y las automatizaciones, por ejemplo ANTHROPIC_KEY. Mayúsculas, dígitos y _, empezando por una letra.
• Kind: Provider key.
• Provider: Anthropic, OpenAI, Google Gemini u OpenAI-compatible. No se puede cambiar después: para cambiar de proveedor, añade otra clave.
• Base URL, solo para OpenAI-compatible: la raíz del endpoint, que suele acabar en /v1, por ejemplo https://api.together.xyz/v1. Mira las reglas de la URL base.
• Value: la clave, una sola línea sin espacios, de 8 a 4096 caracteres.
• Description (optional).

Como todo secreto, una provider key es de solo escritura: nadie puede volver a leerla, ni siquiera tú. La lista la muestra como Provider key · Anthropic (o su proveedor) normalmente con sus 4 últimos caracteres y, en una clave OpenAI-compatible, su URL base, que puedes cambiar con Base URL. Replace value cambia la clave para todos los runs que arranquen a partir de ese momento. nan secrets ls la muestra con KIND provider_key, su PROVIDER y su BASE URL.

Si tu cuenta tiene la API de escritura, también puedes guardarla desde la CLI, leyendo la clave de un archivo o de una tubería: nan secrets set ANTHROPIC_KEY --value-file key.txt --kind provider_key --provider anthropic. Consulta Gestiona los secretos desde la CLI.

Reglas de la URL base. NaN comprueba la URL base al guardarla y nunca se conecta a ella: solo lo hace el agente de tu workspace. Tiene que ser una dirección https pública, que no sea uno de los hosts de NaN, sin usuario:contraseña@, parámetros ni fragmento: la lista completa está en Reglas de la URL base. No pongas nunca un token en la URL base: no es un secreto, y el portal, nan secrets ls y la API la muestran en claro.

Elígela para un run

En el portal, en el formulario New run, pon Inference en My own key, elige la Provider key y escribe el Model.

Desde la terminal (CLI 0.1.32 o posterior):

nan run --byok-secret ANTHROPIC_KEY --model claude-sonnet-4-5 "arregla el test inestable del parser de fechas"

--byok-secret recibe el nombre del secreto, nunca la clave, y necesita --model. nan runs show <id> muestra la elección en su línea inference, y nan runs ls en su columna INFERENCE.

Desde la API, con una sesión iniciada (consulta Quién puede usarla), añade un objeto inference y no mandes el model de primer nivel:

{
  "workspace": "develop",
  "agent": "pi",
  "prompt": "arregla el test inestable del parser de fechas",
  "inference": { "source": "byok", "secret": "ANTHROPIC_KEY", "model": "claude-sonnet-4-5" }
}

El run que recibes dice lo mismo en su inference ("source": "byok", el provider, el secret y el model), y su usage.source es byok. Sin inference, o con {"source": "nan"}, el run usa la inferencia de NaN como siempre.

Quién puede usarla

• Sin un plan con inferencia de NaN, los runs y las automatizaciones con tu propia clave funcionan si tienes un workspace propio activo. Con un plan con inferencia, puedes elegir una u otra en cada run.
• Un run que lanzas tú con tu clave necesita una sesión iniciada: el portal, o la CLI después de nan auth login. Una API key (sk-...) o un token de plataforma (nan_pat_...) recibe 403 session_required, y nan run rechaza NAN_TOKEN y --token-file para estos runs. El motivo: el prompt de un run puede hacer que el agente imprima la clave que tiene, y esas credenciales no pueden leer tus secretos, así que tampoco deben poder conseguir que un agente revele uno. Sí pueden lanzar una automatización que usa tu clave: sus instrucciones son las que tú guardaste.
• Si My own key aparece desactivado con “isn’t available for your account yet”, se está abriendo poco a poco y tu cuenta todavía no lo tiene: mientras tanto usa la inferencia de NaN, o pregunta en #support en Discord.

Facturación y uso

Tu proveedor factura todos los tokens de estos runs, en tu cuenta con él. NaN no los mide: nada cuenta para tu plan de NaN ni para su uso. Los tokens que muestra un run son los que ha informado el agente (Pi y Pi + Gentle Shell los informan, Hermes no); la referencia es la factura de tu proveedor.

Límites

• Hasta 8 runs con tus propias claves trabajando a la vez entre todos tus workspaces. No ocupan plazas de tu límite de inferencia de NaN (5, u 8 con Premium).
• El tamaño de cada workspace sigue limitando todos sus runs juntos, sean de NaN o no: consulta Cuántos runs a la vez. Igual que la cola (20 por workspace, 50 en total) y los 60 runs por hora.

Seguridad

• Tu clave se guarda como cualquier secreto: cifrada, de solo escritura y enmascarada en logs, resultados y propuestas.
• Solo llega al agente del run, dentro de tu propio workspace, como variable de entorno: nunca en la línea de comandos, en un archivo ni en los logs de NaN. El run no recibe la clave de inferencia de NaN de tu workspace.
• NaN nunca llama a tu URL base ni a tu proveedor. Lo hace el agente de tu workspace, por la red de tu workspace.
• El run lee los ajustes de tu agente para conservar tus skills y preferencias, pero usa su propia copia de la configuración, con solo el proveedor de tu clave: tus archivos de configuración no cambian.
• El agente tiene la clave. Un prompt, o unos datos que lea, que lo convenzan de imprimirla o enviarla pueden filtrarla. Usa una clave limitada a lo que necesita el run, con un límite de gasto en tu proveedor, y cámbiala si se filtra.
• Una automatización que lanza un webhook le da al agente un texto que ha escrito otra persona, mientras tiene tu clave. Tenlo en cuenta antes de conectar un webhook público a una automatización con tu clave.

Si algo sale mal

Limitación conocida: Hermes con una clave de Anthropic

Hermes todavía no puede usar una clave de Anthropic en los workspaces: sus runs fallan con config_error hasta que la imagen del workspace incluya soporte para Anthropic. Usa Pi o Pi + Gentle Shell con una clave de Anthropic, o apunta Hermes a un endpoint OpenAI-compatible.

Desde la terminal: nan run

La CLI de NaN lanza y sigue runs desde tu propia terminal. Necesitas la versión 0.1.25 o posterior, y la 0.1.29 o posterior para --agent pi_gentle: nan --version imprime nan <versión>.

curl -fsSL https://nan.builders/install | bash

nan auth login --email tu@correo

nan run "añade tests al parser de fechas y haz que pasen"

Otras formas de lanzarlo:

# Un workspace, un agente y una carpeta concretos
nan run --ws develop --agent hermes --cwd /home/nan/projects/api "revisa los TODO pendientes"

# Pi + Gentle Shell (el workspace necesita Pi y gentle-shell)
nan run --ws develop --agent pi_gentle "refactoriza el cargador de configuración sin romper los tests"

# La tarea desde un archivo, o desde stdin
nan run -f tarea.md
git diff | nan run -

# Lánzalo y quédate con el id sin esperar
nan run --detach "actualiza las dependencias"

Los flags equivalen al formulario del portal: Agent es --agent, Folder es --cwd, Separate branch es --worktree / --no-worktree y Time limit es --timeout. La tarea es el texto entre comillas.

Mientras se muestra el log, Ctrl-C una vez te desconecta del log: el run sigue y la CLI te dice cómo retomarlo. Ctrl-C dos veces en menos de 2 segundos lo cancela.

Gestiona tus runs

nan runs ls                # tus runs, del más reciente al más antiguo
nan runs show <id>         # estado, resultado y prompt
nan runs logs <id> -f      # sigue el log hasta que termine
nan runs cancel <id>

nan runs logs <id> --json imprime un evento JSON por línea, cómodo para scripts. Cada evento tiene un type; estos son los principales:

Códigos de salida

nan run y nan runs logs -f salen con el resultado del run, así que un script puede actuar sin leer el texto:

Con set -e, ten en cuenta el 75 de --detach:

id=$(nan run --detach "actualiza las dependencias") || [ $? -eq 75 ]

Autenticación

nan run y nan runs usan lo primero que encuentren de esta lista:

1. NAN_TOKEN: una variable de entorno con un token de plataforma (nan_pat_...) o una API key (sk-...). Se lee en cada comando y nunca se escribe en disco.
2. --token-file PATH: el token en la primera línea de un archivo. El archivo tiene que ser privado (chmod 600): en macOS y Linux, si otros usuarios pueden leerlo o escribirlo, se rechaza.
3. Un token guardado, con nan auth login --api-token.
4. Tu sesión, de nan auth login (el enlace de acceso por correo).
5. Una API key guardada, desde la pestaña Setup (o una clave sk-... guardada con nan auth login --api-token).

nan auth login --api-token lee el token solo de stdin, oculto mientras lo pegas, lo comprueba contra nan.builders y lo guarda con permisos 0600. Lo guarda aparte de la API key, así que la pestaña Setup nunca copia un token de plataforma en la configuración de tus herramientas:

nan auth login --api-token              # pégalo cuando te lo pida
nan auth login --api-token < token.txt  # o pásalo por stdin

No pongas nunca un token en la propia línea de comandos: acabaría en el historial de tu shell y en ps.

Un run con tu propia clave de proveedor (--byok-secret) usa solo tu sesión de nan auth login: la CLI rechaza NAN_TOKEN y --token-file para él, y se salta un token o una API key guardados.

En la CLI, un token de plataforma solo sirve para nan run, nan runs, nan automations y nan approvals (consulta API keys y tokens). nan me, nan metrics usage y el panel siguen necesitando una sesión de nan auth login.

Usa la CLI en CI o en un servidor

Crea un token, guárdalo en los secretos de tu CI y pásalo como NAN_TOKEN. Por ejemplo, en GitHub Actions:

- name: Review the PR with an agent
  env:
    NAN_TOKEN: ${{ secrets.NAN_TOKEN }}
  run: |
    curl -fsSL https://nan.builders/install | bash
    nan run --ws ci --timeout 20m -f .github/review-task.md

Ese paso espera al run y falla si el run falla. Para lanzarlo y seguir sin esperar, usa --detach y ten en cuenta su código de salida 75:

nan run --ws ci --detach "actualiza las dependencias" || [ $? -eq 75 ]

En un servidor que configuras una vez, guárdalo mejor con nan auth login --api-token.

Desde la API

Los mismos runs están disponibles por HTTP, en https://api.nan.builders/v1/runs, para tus scripts e integraciones.

API keys y tokens

Hay dos tipos de credenciales que sirven para la API de runs. Las dos están en tus ajustes del portal:

Un token es lo que conviene darle a un script que solo gestiona runs. No sirve para llamar a los modelos directamente, pero sí para lanzar runs que gastan tu plan: guárdalo igual de bien que una API key y revócalo si se filtra. Créalo en Settings → Tokens:

• Se muestra una sola vez, al crearlo. Cópialo en ese momento.
• Puedes tener hasta 10 tokens activos.
• Cada uno caduca a los 30, 90 o 365 días, o nunca.
• Puedes revocar cualquiera en cualquier momento.
• Lleva scopes, lo que puede hacer: runs y workspaces:read por defecto. Para listar o lanzar automatizaciones, añade automations:read o automations:run. Consulta Tokens para automatizaciones.

Para crear runs con la inferencia de NaN sigue haciendo falta un plan con inferencia, uses la credencial que uses. Los runs con tu propia clave de proveedor necesitan una sesión iniciada en lugar de una API key o un token. La referencia de la API indica qué credencial acepta cada endpoint.

Crea un run y síguelo

Un ejemplo de principio a fin: crea un run, guarda su id (con jq) y sigue su log en directo hasta que termine. Si el run no se puede crear, muestra el error en lugar de seguir el log.

export NAN_TOKEN="nan_pat_..."

RESP=$(curl -s https://api.nan.builders/v1/runs \
  -H "Authorization: Bearer $NAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "develop",
    "agent": "pi",
    "prompt": "añade tests al parser de fechas y haz que pasen",
    "cwd": "/home/nan/projects/api"
  }')
RUN_ID=$(echo "$RESP" | jq -r '.id // empty')
if [ -z "$RUN_ID" ]; then
  echo "$RESP"
else
  curl -N "https://api.nan.builders/v1/runs/$RUN_ID/events" \
    -H "Authorization: Bearer $NAN_TOKEN" \
    -H "Accept: text/event-stream"
fi

Los campos equivalen al formulario del portal: Agent es agent, Task es prompt, Folder es cwd, y los opcionales Separate branch y Time limit son git_isolation y timeout_seconds.

agent es pi, pi_gentle o hermes, como en Elige el agente. Si el workspace no tiene ese agente instalado, no se crea ningún run y el ejemplo imprime el error:

{
  "error": {
    "message": "Pi + Gentle Shell is not installed in this workspace",
    "type": "invalid_request_error",
    "param": "agent",
    "code": "agent_not_installed"
  }
}

El stream manda un frame run_event por cada evento del log, un frame state cuando el run cambia de estado y un frame end con el run terminado, y después se cierra.

Referencia completa: Referencia de la API → Runs. Ahí están todos los endpoints (listar, consultar, cancelar), los campos de cada petición y respuesta, los tipos de evento, cómo retomar un stream, los reintentos idempotentes y todos los códigos de error. Para sacar el nombre o el id de un workspace desde un script, consulta Referencia de la API → Workspaces.

Preguntas frecuentes