Ejecuciones efímeras.

Una ejecución efímera es un run de agente que no necesita workspace. NaN arranca un contenedor nuevo solo para ese run, clona el repositorio de GitHub que le indicas, ejecuta el agente con el modelo que eliges y destruye el contenedor cuando el run termina. Sigues su log en directo, lo cancelas y lees su resultado exactamente igual que con cualquier otro run.

Usa una ejecución efímera cuando:

• No tienes workspace, o no quieres que una tarea lo toque.
• Quieres muchos runs a la vez: cada uno tiene su propio contenedor, así que nunca comparten archivos, CPU ni memoria.
• La tarea parte del código de un repositorio: revisarlo, analizarlo, responder una pregunta sobre él, pasar sus tests.

Usa un run en un workspace cuando el agente necesite tus propios archivos, tus herramientas configuradas a mano o cambios que sigan ahí después del run: una ejecución efímera no guarda nada.

Antes de empezar

• Un repositorio de GitHub, como owner/name, por ejemplo acme/api. Un run que lanzas tú clona repositorios públicos. Para uno privado, usa una automatización con un token de GitHub.
• Un método de pago registrado, siempre, aunque tus minutos gratis cubran todos los runs. Añádelo en Settings → Ephemeral runs con Add a payment method (el formulario New run también lo ofrece). Consulta Método de pago y moneda.
• Un modelo. No hay configuración de workspace a la que recurrir, así que toda ejecución efímera indica su modelo.
• Un plan con inferencia, o tu propia clave de proveedor. Con la inferencia de NaN, los tokens cuentan para el uso de tu plan como en cualquier otro run. Con tu propia clave de proveedor, los factura tu proveedor, y puede usarla cualquier miembro con una suscripción activa.

Qué se ejecuta en el contenedor

El contenedor viene listo con Pi, Pi + Gentle Shell y Hermes, además de git, Python y Node. Eliges el agente como en cualquier run (pi, pi_gentle o hermes: consulta Elige el agente); no hay que instalar nada antes.

Cada run:

1. Arranca un contenedor nuevo del tamaño que elegiste.
2. Clona el repositorio en el último commit de su rama por defecto (o, en una automatización, en el commit del que trata el evento: consulta Qué commit).
3. Ejecuta el agente en el clon, con tu tarea y el modelo que elegiste.
4. Emite sus eventos como cualquier run, y termina con su estado y el resumen del agente.
5. Destruye el contenedor y todo lo que hay en él, pase lo que pase: terminado, fallido, agotado su tiempo o cancelado.

El agente trabaja en su clon: Folder y Separate branch no aplican, y no se hace push de nada. Para actuar sobre el repositorio (comentar, revisar, poner etiquetas), usa una automatización: NaN aplica sus acciones después del run, con tu token.

Lanza una desde el portal

Abre New run desde la página Runs del portal (cloud.nan.builders/runs), o desde la pestaña Runs de un workspace, y pon Where it runs en Ephemeral container. En la página Runs, sin workspace, es la única opción. Después rellena:

Debajo del formulario, una nota de coste muestra lo máximo que podría costar el run si agota su tiempo límite, y tus minutos S gratis que quedan convertidos al tamaño elegido, por ejemplo 80 free S-minutes left this month = 40 minutes of M. (80 minutos S gratis este mes = 40 minutos de M).

La lista de runs muestra dónde se ejecutó cada uno y, cuando termina una ejecución efímera, lo que costó.

Mientras una ejecución efímera trabaja, su página muestra un contador en directo: Elapsed (tiempo transcurrido), Started minutes (minutos empezados; pasa a llamarse Minutes billed cuando el cobro está activo), S-minutes (lo que gasta de tus minutos gratis, según el tamaño) y Estimated cost (coste estimado, antes de los minutos gratis). La página Runs y Settings → Ephemeral runs muestran los totales del mes: S-minutes, Free S-minutes left (minutos S gratis que quedan) y Chargeable so far (lo cobrable hasta ahora), en euros. Consulta Minutos gratis.

Desde la terminal

nan run --ephemeral --repo acme/api --model glm5.3 --size s "explica cómo funciona el middleware de auth"

Los demás flags de nan run funcionan igual: --agent, --timeout, --detach, --json, -f, --byok-secret. --cwd y --worktree no aplican. Actualiza antes la CLI (curl -fsSL https://nan.builders/install | bash); nan run --help muestra --ephemeral cuando tu versión lo tiene.

Para ver los minutos de este mes, el coste, los minutos gratis que te quedan y tus límites:

nan ephemeral usage
nan ephemeral settings

Los límites solo se cambian en el portal: consulta Límites.

Desde la API

Créala con POST https://api.nan.builders/v1/runs, con executor a ephemeral y sin workspace:

curl -s https://api.nan.builders/v1/runs \
  -H "Authorization: Bearer $NAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "executor": "ephemeral",
    "size": "s",
    "github_repo": "acme/api",
    "agent": "pi",
    "model": "glm5.3",
    "prompt": "explica cómo funciona el middleware de auth",
    "timeout_seconds": 1800
  }'

Los eventos, el stream en directo, la cancelación y el objeto run son los mismos que en cualquier run, por id de run. El objeto run añade executor (ephemeral), size y, cuando el run ya está medido, cost: eur, eur_micros y billed_seconds. Su workspace es null.

Credenciales. Las ejecuciones efímeras cuestan dinero, así que no cualquier credencial puede lanzarlas:

• Una sesión iniciada (el portal, o la CLI después de nan auth login) puede.
• Un token de plataforma (nan_pat_...) necesita el scope runs:ephemeral, además de runs. Lo añades al crear el token en Settings → Tokens, con la sesión iniciada en el portal.
• Una API key (sk-...) no puede: recibe 403 token_scope_denied.

Un run con tu propia clave de proveedor lanzado por ti sigue necesitando una sesión iniciada, como cualquier run: consulta Quién puede usarla.

En automatizaciones

Una automatización también puede ejecutarse en contenedores efímeros: cada run que lanza, con Run now, un webhook o una programación, tiene su propio contenedor. En el editor, pon Where it runs en Ephemeral container y elige el Size. No necesitas workspace para ello: sin ningún workspace, tus automatizaciones solo pueden ser efímeras. El editor dice que sus runs se cobran por minuto de contenedor (billed per container minute). Entonces necesita:

• Un GitHub repository, y Checkout en Fresh clone per run: no hay carpeta de workspace en la que trabajar.
• Un Model.

Sin Workspace, Folder ni Separate branch. Desde la CLI o la API, los campos son executor: ephemeral, size, checkout: fresh, github_repo y model:

name: PR review api
template: pr_review
executor: ephemeral
size: m
checkout: fresh
github_repo: acme/api
agent: pi
model: glm5.3
secrets:
  - { secret: GITHUB_READ_TOKEN, env: GITHUB_TOKEN, exposure: agent }
  - { secret: GITHUB_WRITE_TOKEN, env: GITHUB_TOKEN, exposure: actions }

Todo lo demás funciona como en cualquier automatización con clon nuevo: qué commit se usa, el filtro de pull requests de forks y de colaboradores externos, los secretos, las aprobaciones y las acciones (comentarios, revisiones y etiquetas, nunca un push). Crear o cambiar una automatización efímera, o sus triggers, necesita una sesión iniciada o un token con runs:ephemeral.

Repositorios privados

Para clonar un repositorio privado, asigna a la automatización un token de GitHub como GITHUB_TOKEN con Agent (read access): un token fine-grained, de solo lectura, limitado a ese repositorio. NaN lo usa para clonar, como se explica en Clon nuevo por run, y el agente lo recibe para leer el repositorio. Consulta El patrón del token de GitHub.

Un run que lanzas tú, desde el portal, nan run o POST /v1/runs, nunca recibe secretos, así que solo puede clonar repositorios públicos.

Tamaños y precios

Los runs se cobran por minuto empezado de tiempo de contenedor, de principio a fin, al precio de su tamaño. Un run de 14 segundos cuenta como 1 minuto; uno de 61 segundos, como 2. Los tokens del modelo no entran en este precio: cuentan para tu plan, o te los factura tu proveedor con tu propia clave.

La mayoría de los agentes pasan el tiempo esperando al modelo, así que S basta para casi todas las tareas. Elige M o L para builds o baterías de tests pesadas.

Minutos gratis

Cada mes tu membresía incluye minutos gratis:

Los minutos gratis solo vienen con una membresía. Sin ella (por ejemplo, con solo un slot de workspace), se cobra cada minuto.

Los minutos gratis son minutos S. Sirven para cualquier tamaño, pero un minuto de un tamaño mayor gasta más:

Así, 100 minutos gratis son 100 minutos de S, o 50 de M, o 25 de L, o cualquier combinación. Nunca tienes que elegir un tamaño para no salirte de ellos.

Un ejemplo. Con el plan Inference tienes 300 minutos gratis. Este mes ejecutas 100 minutos de M (200 minutos gratis) y 30 minutos de L (120 minutos gratis): 320 en total. Los primeros 300 son gratis, y los 20 minutos S que sobran cuestan 20 × 0,003 € = 0,06 €.

Los minutos gratis se gastan primero y se renuevan el día 1 de cada mes (UTC). Los que no uses no se acumulan. El cost de cada run es el precio completo de sus minutos; los minutos gratis se cuentan sobre el mes. La página Runs y Settings → Ephemeral runs muestran los S-minutes del mes, los Free S-minutes left y el Chargeable so far; también nan ephemeral usage.

Método de pago y moneda

• Hace falta un método de pago para usar ejecuciones efímeras, también con minutos gratis. Sin él, el run se rechaza con 402 payment_method_required. Añádelo en Settings → Ephemeral runs con Add a payment method; el formulario New run ofrece el mismo botón.
• Las ejecuciones efímeras se facturan solo en euros. Si tu membresía se factura en dólares, pásala antes a EUR con Switch billing to EUR, en Settings → Ephemeral runs o en el formulario New run. Hasta entonces, los runs se rechazan con 402 currency_migration_required.

Límite de gasto y concurrencia

Dos límites te protegen de sorpresas. Se cambian en el portal, en Settings → Ephemeral runs, con la sesión iniciada:

El límite de gasto se comprueba antes de que arranque cada run, y solo cuenta el dinero que se cobraría. NaN suma lo cobrable de este mes a lo máximo que podrían costar las ejecuciones efímeras aún abiertas y la nueva, menos los minutos gratis que te quedan (nunca por debajo de cero), y eso tiene que caber en el límite. Lo máximo que puede costar un run es su tiempo límite más 2,5 minutos, al precio de su tamaño: un run de 30 minutos en S reserva 33 minutos, 0,099 €. Si no cabe, el run se rechaza con 402 ephemeral_cap_reached. Sube el límite, espera a que terminen los runs en marcha, o usa un tiempo límite más corto o un tamaño menor. Un límite de 0 € solo permite los runs que tus minutos gratis cubren por completo.

Concurrent ephemeral runs. Los runs que superan tu límite no se rechazan: esperan en la cola y arrancan por orden. Sin membresía, el valor por defecto es 5 y el máximo 10. Los límites habituales para crear runs siguen aplicando.

Minutos prepago y recarga automática

Puedes pagar minutos por adelantado y tener un saldo prepago. Está abierto a cualquier cuenta con un método de pago: miembros de cualquier plan, Community incluido, y cuentas sin membresía. Sin una membresía Inference o Premium, las ejecuciones efímeras usan tu propia key para el modelo, y una cuenta sin membresía funciona solo con su saldo prepago.

Comprar. En Settings → Ephemeral runs, usa Add funds y elige 5 €, 10 € o 25 €, o Other amount: cualquier importe de 5 € a 200 €, en euros enteros. Pagas una vez, con tarjeta, en una página de pago segura; no es una suscripción. Los minutos prepago son minutos S a 0,003 €, así que 5 € compran 1.666 minutos S (los céntimos que sobran se quedan en tu saldo y se suman a tu siguiente compra). La tarjeta con la que pagas se guarda, así que también cuenta como tu método de pago.

Orden de uso. Cada run gasta primero los minutos gratis, después tu saldo prepago y después, solo para miembros, el cobro por minuto habitual en tu membresía. Un run solo arranca si entre todo eso se cubre lo máximo que puede costar (consulta Límite de gasto y concurrencia). Las cuentas sin membresía no tienen cobro por minuto, así que un run que el saldo no cubre se rechaza con 402 ephemeral_funds_insufficient.

Caducidad. Tu saldo es válido durante 6 meses desde tu última compra o recarga. Cada nueva compra o recarga amplía todo el saldo a 6 meses desde ese momento. El saldo caducado se pierde; te avisamos por email 30 días antes. Settings muestra el saldo en euros, cuántos minutos S compra aproximadamente y cuándo caduca.

Recarga automática. Activa Recharge automatically y fija dos importes:

• La recarga tiene que ser mayor que el umbral, y no mayor que tu límite de gasto mensual.
• La recarga automática necesita una tarjeta. Siempre cobra la tarjeta que elegiste al activarla, aunque después cambies tu método de pago por defecto.
• Activarla no te cobra nada ahora. Cobramos el importe de la recarga solo cuando un run usa tu saldo prepago y lo deja por debajo del umbral, o cuando un run necesita más de lo que tienes y una recarga basta para cubrirlo. La caducidad, los reembolsos y las disputas nunca provocan una recarga.
• Va sin límite diario. Las recargas cuentan para tu límite de gasto mensual, así que el límite acota cuánto se cobra sin un clic cada mes. Las compras manuales no cuentan para el límite, ni tampoco gastar tu saldo prepago (se pagó al comprarlo).
• Mientras hay una recarga en curso, un run nuevo recibe 402 ephemeral_recharge_pending: vuelve a intentarlo en unos segundos.
• La recarga automática se desactiva sola si tu banco pide confirmar un pago, tras 3 pagos rechazados seguidos, si se elimina su tarjeta, o tras un reembolso o una disputa del pago. Settings te dice por qué; actívala de nuevo para seguir usándola.

Saldo congelado. Si el pago de tu membresía está pendiente (periodo de gracia) o tu cuenta está bloqueada, el saldo se conserva pero queda Frozen (congelado): los runs nuevos no pueden usarlo, no se puede recargar, la recarga automática queda en pausa y la caducidad sigue corriendo. Los runs que ya habían arrancado sí lo usan. Dejar una membresía no lo congela: tu cuenta lo sigue usando con tu propia key.

Reembolsos. Al comprar, pides que los minutos se añadan de inmediato y aceptas que pierdes tu derecho de desistimiento una vez añadidos; lo mismo aplica a cada recarga automática. Los minutos prepago no son reembolsables. Si un run falla por un problema nuestro, escribe en #support y te abonamos el saldo. El saldo se pierde si eliminas tu cuenta. Las condiciones completas están en los términos.

Red

Desde el contenedor, el agente solo puede salir a internet por HTTP y HTTPS (puertos 80 y 443): registros de paquetes, GitHub, documentación, APIs.

• Ningún otro puerto: ni SSH, ni SMTP (correo), ni bases de datos u otros servicios en sus propios puertos, ni URLs con un puerto explícito distinto de 80 o 443.
• Sin WebSockets, sin direcciones IP sueltas (usa nombres de host) y sin sitios de NaN distintos de api.nan.builders.
• Hasta 30 peticiones por segundo por run.
• Hasta 2 GiB descargados y 512 MiB enviados por run. Por encima, el run se detiene y falla con egress_limit.

Así que clona por HTTPS, no por SSH, y descarga las dependencias de registros que sirvan HTTPS.

Seguridad

• Cada run tiene su propio contenedor, creado para él y destruido después. No se comparte nada entre runs, miembros ni con tus workspaces.
• La clave de inferencia nunca entra en el contenedor, ni la de NaN ni la tuya. Las peticiones del agente al modelo salen con un marcador, y la clave real se añade por el camino, solo para el proveedor del modelo de ese run.
• El contenedor solo recibe los secretos que asignas a la automatización, enmascarados en logs y resultados, como en cualquier run.
• El código que clonas se ejecuta en el contenedor, junto a esos secretos. El consejo sobre pull requests de forks también aplica aquí.

Si algo sale mal

Preguntas frecuentes