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 o Hermes, el que tengas instalado 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.

Antes de empezar

• Un workspace encendido, con Pi o Hermes instalado. Puedes instalar cualquiera de los dos desde el panel de Software del workspace.
• Un plan con inferencia. 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. Si tu plan no incluye inferencia no puedes crear runs: el portal te enseña las opciones para mejorarlo.

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 o Hermes, el que tengas instalado en el workspace.
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.

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 comparten tu concurrencia de inferencia, así que puedes tener como mucho 5 runs trabajando a la vez entre todos tus workspaces (8 con Premium).

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 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 secretos del archivo de entorno de tu workspace, como esa clave de inferencia o un token de bot de Telegram, aparecen como *** en los logs y resultados de los runs, así que un log no los filtra.

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: 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"

# 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.

En la CLI, un token de plataforma solo sirve para nan run y nan runs (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.

Para crear runs sigue haciendo falta un plan con inferencia, uses la credencial que uses. 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.

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