[sre-helmcode]

DO NOT MERGE until ephemeral runs open to the community. Today the feature is live for the owner only (EPHEMERAL_ENABLED + allowlist, billing off). It must also merge together with or after cloud-api #379 (E3: chargeable-only spend cap, payment method required, membership-only free minutes, EUR only), which this page documents. Merging publishes the page on nan.builders and in the /api/docs manifest the Discord bot reads.

What

New docs page Ephemeral runs (/docs/ephemeral-runs) / Ejecuciones efímeras (/es/docs/ephemeral-runs), nested under Agent runs in the sidebar:

• What an ephemeral run is and when to use it vs a workspace run (comparison table): fresh container per run, repo cloned, destroyed at the end, Pi / Pi + Gentle Shell / Hermes ready in the container.
• Portal (Where it runs: Ephemeral, size), CLI (nan run --ephemeral --repo owner/name --model ... --size s, nan ephemeral usage|settings), API (POST /v1/runs with executor, size, github_repo, model; workspace/cwd/git_isolation refused; run object executor, size, cost), credentials (session, token with runs:ephemeral, never sk-).
• Automations: executor: ephemeral, size, checkout: fresh, github_repo, model. Private repos: only via an automation with GITHUB_TOKEN assigned as Agent (read access) (ad-hoc runs never receive secrets, so they clone public repos only).
• Sizes and prices (S/M/L, €0.003/0.006/0.012 per started minute), free minutes per plan (100/300/1000), the S-minutes explanation and the worked example (owner request), "billing not active yet" callout.
• Monthly spend cap (default €100, 0..1000) with how the reservation works (time limit + 2.5 min at the size price; a €0 cap blocks all ephemeral runs), concurrency (default 50, 1..50, extra runs queue).
• Network: HTTP/HTTPS only (no SSH, no SMTP, no other ports), no WebSockets/bare IPs, 30 req/s, 2 GiB in / 512 MiB out (egress_limit). Security notes (keys never enter the container). Error table and FAQ.
• No EU-only claim; no vendor/infrastructure names (guarded by the test).

Cross-links: one sentence each in Agent runs and Automations (EN + ES). Doc order from 20 on shifts by one so the child sits right after its parent (required by the nav tests). The automations guard test that banned the word "ephemeral" now allows only the link to the new page.

Review fixes (round 1)

• Spend cap with E3 semantics: only chargeable money counts (worst case of open + new runs minus free minutes left, never below 0); a €0 cap allows only runs fully covered by free minutes.
• Counters: live counter on a running ephemeral run (Elapsed, Minutes billed, S-minutes, Estimated cost); this month's S-minutes, Free S-minutes left, Chargeable so far on the Runs page and in Settings → Ephemeral runs.
• Exact labels: Ephemeral container, Monthly spend cap (€), Concurrent ephemeral runs (English in bold in ES too).
• Owner decisions: payment method always required (402 payment_method_required, Add a payment method); free minutes only with a membership (no membership = 0); EUR only (402 currency_migration_required, switch in Settings → Billing); ephemeral automations need no workspace (without one, only ephemeral automations).

Review fixes (round 2: final cloud-ui #177 copy)

• Live counter: Started minutes while billing is off, Minutes billed once it is on.
• Automation editor: measured per container minute (not charged yet) / billed per container minute.
• Cost note converts free S-minutes to the chosen size (80 free S-minutes left this month = 40 minutes of M.).
• Currency: Switch billing to EUR in Settings → Ephemeral runs and the New run form (no more "Settings → Billing").

Sources

cloud-api origin/main: internal/runs/ephemeral.go, validate.go, api.go, store_ephemeral.go, internal/handlers/ephemeral.go, runs.go, internal/pat/scopes.go, internal/automations/validate.go, cloudflare/ephemeral-runner/README.md; devops AGENT-EPHEMERAL-EXECUTORS.md §5.5, §6.

To re-check before merge: portal labels (Where it runs, Size, Settings → Ephemeral runs) follow spec §5.5 since the cloud-ui work is in progress; CLI flags and nan ephemeral usage|settings follow the brief/spec since the nan-cli release is pending. The API reference (src/data/openapi.json) does not yet describe the ephemeral fields.

Tests

• New src/tests/layouts/ephemeralRunsDocs.test.ts (spec first): nav nesting, prices, free minutes and S-minute example math, cap/concurrency defaults and reservation math, network rules, CLI/API/scope, automations + private repos, JSON example validity, no vendor names / EU claim / em-dashes, in-page and cross-page anchors resolve, EN/ES structural parity, cross-links present.
• npx vitest run: 88 files, 2548 tests passed (unit + render).
• npm run build: OK.

🤖 Generated with Claude Code