@fastagent-sh/fastagent 0.22.1 → 0.23.0

package/dist/deploy/container.js

@@ -1,6 +1,50 @@
 /** The portable container — Dockerfile + .dockerignore, host-neutral. */
 import { SECRETS_DIRNAME, STATE_DIRNAME } from "../paths.js";
 import { RELEASE_FILE, parseDeploymentRelease } from "./workspace.js";
+/** The result line for a box CLI that refused `login --stdio` as an unknown option (see {@link boxLoginCommand}). */
+const STDIO_PREDATED = JSON.stringify({
+    type: "result",
+    ok: false,
+    reason: "failed",
+    message: "the fastagent installed in the agent on the box predates login --stdio: align the @fastagent-sh/fastagent " +
+        "version in the agent package.json with the CLI that deploys it, then redeploy",
+}).replaceAll('"', '\\"');
+/** Where a generated image keeps its storage (`FASTAGENT_STORAGE_DIR`); every host mounts its volume here. */
+const STORAGE_DIR = "/data";
+/**
+ * The shell command that runs `fastagent login --stdio <args>` inside a running generated image, as the server there
+ * would see it: in the deployed agent directory, with the storage and credential paths resolved by the same defaults
+ * `prepareStartWorkspace` applies. A host's own shell does not reliably hand those over — its session may not start
+ * in the server's directory, and the platform's variables are the only ones it inherits. `storage` names the root
+ * outright for a shell that inherits none of them. The CLI is the one the server runs: the agent's own install when
+ * it has one (under Bun when the image is Bun's), else the pinned global.
+ *
+ * That own install may predate `login --stdio` (an agent pinned to an older release, deployed by a newer CLI). It then
+ * refuses the flag as a usage error, exit 2, which a `login --stdio` that ran never gives (it answers 0 or 1 after its
+ * result line), so the command answers for it: one result line naming the mismatch, instead of a shell that ended
+ * with nothing to say. No quote or backtick in it: hosts wrap this whole line in `sh -c '…'`.
+ */
+export function boxLoginCommand(agent, args, storage) {
+    for (const value of [agent, ...args, ...(storage ? [storage] : [])]) {
+        if (!/^[\w.@/-]+$/.test(value))
+            throw new Error(`cannot pass ${JSON.stringify(value)} to a shell on the box`);
+    }
+    return [
+        ...(storage
+            ? [`root="${storage}"`, `export FASTAGENT_SECRETS_DIR="$root/.secrets"`]
+            : [
+                `root="\${FASTAGENT_STORAGE_DIR:-${STORAGE_DIR}}"`,
+                `export FASTAGENT_SECRETS_DIR="\${FASTAGENT_SECRETS_DIR:-$root/.secrets}"`,
+            ]),
+        `cd "$root/base/${agent}" || exit 1`,
+        `f=fastagent`,
+        `if [ -x node_modules/.bin/fastagent ]; then f=node_modules/.bin/fastagent; if command -v bun >/dev/null; then f="bun run fastagent"; fi; fi`,
+        `$f login --stdio ${args.join(" ")}`,
+        `code=$?`,
+        `if [ $code -eq 2 ]; then printf "%s\\n" "${STDIO_PREDATED}"; fi`,
+        `exit $code`,
+    ].join("; ");
+}
 /** Fixed first-line prefix of a fastagent-generated Dockerfile. */
 export const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
 /** The ONE predicate for "did fastagent generate this Dockerfile?". */
@@ -41,7 +85,7 @@ function dockerfile(input) {
     // PIN the agent into the image.
     const pin = `ENV FASTAGENT_AGENT=${dir}\n`;
     // The caches stay off the volume: they are rebuildable, and a host mount is the slow disk.
-    const deployment = `ENV FASTAGENT_RELEASE_FILE=/app/${into(RELEASE_FILE)}\nENV FASTAGENT_STORAGE_DIR=/data\nENV npm_config_cache=/tmp/fastagent/npm\nENV BUN_INSTALL_CACHE_DIR=/tmp/fastagent/bun\n`;
+    const deployment = `ENV FASTAGENT_RELEASE_FILE=/app/${into(RELEASE_FILE)}\nENV FASTAGENT_STORAGE_DIR=${STORAGE_DIR}\nENV npm_config_cache=/tmp/fastagent/npm\nENV BUN_INSTALL_CACHE_DIR=/tmp/fastagent/bun\n`;
     // No package.json → pure markdown/skills agent: install the pinned CLI GLOBALLY and run `fastagent` from PATH.
     if (!input.hasPackageJson) {
         return `${GENERATED_DOCKERFILE_MARKER}. ${layoutNote}

package/dist/deploy/docker/plan.d.ts

@@ -1,14 +1,17 @@
 /** `fastagent deploy docker` — the local-Docker plan. */
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
-import { type DeploymentSecret } from "../secrets.ts";
+import type { DeploymentSecret } from "../secrets.ts";
 export interface DockerPlanInput extends ContainerInput {
     /** Stable Compose project name, sanitized by {@link toDockerProjectName}. */
     projectName: string;
     /** Container + default host port. */
     port: number;
-    /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
-    modelAuth: string | undefined;
+    /**
+     * The provider the deployment logs in to itself (`fastagent login --deployment`): its credential is not a variable
+     * the plan carries.
+     */
+    boxLogin?: string;
     /** Every declared channel and its ingress — the source of the ingress note. */
     channels: readonly DeclaredChannel[];
     /** Generate an optional Cloudflare Quick Tunnel service in Compose. */
@@ -29,6 +32,7 @@ export interface DockerPlan {
     /** Ordered local build/run/operate instructions. */
     runbook: string[];
 }
+export declare const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
 export declare const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
 /** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
 export declare const CLOUDFLARED_IMAGE = "cloudflare/cloudflared:2026.7.1";

package/dist/deploy/docker/plan.js

@@ -1,9 +1,9 @@
 import { webhookPaths } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
-import { isEnvKey } from "../secrets.js";
+import { deploymentLoginCommand } from "../box-shell.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
 const MOUNT = "/data";
-const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
+export const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
 const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
 export const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
 /** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
@@ -81,17 +81,12 @@ services:
       - ${SECRETS_DIRNAME}/.env
     environment:
       PORT: "${input.port}"
-      # Machinery on the ONE state volume: mutable state and (seeded, possibly rotated) secrets. Pinned AFTER
+      # Machinery on the ONE state volume: mutable state and credentials (logged in on the box). Pinned AFTER
       # env_file so a local path in that file (the scaffold lists these) cannot send the container's state, sessions
       # or credentials somewhere outside the volume — or at a host path that does not exist here at all.
       FASTAGENT_STATE_DIR: "${MOUNT}/.state"
       FASTAGENT_SECRETS_DIR: "${MOUNT}/.secrets"
       FASTAGENT_AUTH_PATH: "${MOUNT}/.secrets/auth.json"
-      # The ONE value that is not in the value file: \`--run\` mints it from the local auth.json. Left as a seam in
-      # the committed topology so a hand-run \`up\` can supply it the same way — from the ENVIRONMENT of that \`up\`.
-      # Writing this one key into the value file does nothing: \`environment:\` is applied after \`env_file\`, so the
-      # line below would blank it and the container would start without seeding auth.json.
-      FASTAGENT_AUTH_SEED: "${composeInterpolation("FASTAGENT_AUTH_SEED")}"
     volumes:
       - state:${MOUNT}
     # The agent's log is where a failure's reason is recorded (a scheduled fire logs the detail; what the turn
@@ -126,13 +121,13 @@ export function planDockerDeploy(input) {
     if (secrets.length > 0) {
         runbook.push(`# Environment: the container reads ${input.valueFile} whole (Compose \`env_file\`) — that file declares the`, `# deployed environment (in CI, write it before running the command):`, ...secrets.map((secret) => `#   ${secret.name}: ${secret.hint}`));
     }
-    if (!isEnvKey(input.modelAuth)) {
-        runbook.push(input.modelAuth === undefined
-            ? `# Model auth: none found locally — run \`fastagent login\` or set a provider API key before --run.`
-            : `# Model auth: local source is "${input.modelAuth}" — \`--run\` carries auth.json as FASTAGENT_AUTH_SEED.`, `# For a manual Compose run, provide a provider API key or set FASTAGENT_AUTH_SEED yourself.`);
-    }
     runbook.push(`# Run from the WORKSPACE ROOT (the directory containing ${input.agentPrefix}).`, `# The build bakes the whole directory as the agent's workspace; only the agent's own`, `# dependencies (${input.agentPrefix}package.json) are installed.`);
-    runbook.push(``, `# Before building a new definition release, run \`fastagent deploy docker\` to refresh its manifest.`, `# The Compose volume at ${MOUNT} retains the workspace, state and credentials.`, `${compose} up -d --build`, `curl --fail http://127.0.0.1:${input.port}/health`, ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: deletes workspace, credentials and all agent state`);
+    runbook.push(``, `# Before building a new definition release, run \`fastagent deploy docker\` to refresh its manifest.`, `# The Compose volume at ${MOUNT} retains the workspace, state and credentials.`, `${compose} up -d --build`, `curl --fail http://127.0.0.1:${input.port}/health`, ...(input.boxLogin
+        ? [
+            `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself:`,
+            `${deploymentLoginCommand("docker", input.boxLogin)}`,
+        ]
+        : []), ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: deletes workspace, credentials and all agent state`);
     if (input.tunnel) {
         runbook.push(``, `# Quick Tunnel: \`--run\` starts the Compose tunnel service and reads its ephemeral public URL.`, `# Telegram/Feishu/Lark and locally onboarded Slack auto-register; manual Slack prints its console URL. Re-run after the`, `# tunnel container/Docker daemon restarts: a new Quick Tunnel URL must replace the old webhook URL.`, `${compose} logs -f tunnel`);
     }

package/dist/deploy/docker/run.d.ts

@@ -1,3 +1,6 @@
+/** `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally. */
+import type { BoxLoginStep } from "../box-shell.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import type { RegistrationOutcome } from "../../channels/registration.ts";
 import type { CliRunner } from "../runner.ts";
 export interface DockerRunPlan {
@@ -6,21 +9,25 @@ export interface DockerRunPlan {
     /** Container port from config; used to ask Compose for the effective published host port. */
     port: number;
     /**
-     * What `--run` assembled. The container reads the value file itself through the generated `env_file`, so the only
-     * entry that has to travel through this process is `FASTAGENT_AUTH_SEED`, which is minted here; the rest is
-     * reported to the operator and otherwise unused.
+     * What `--run` assembled. The container reads the value file itself through the generated `env_file`, so nothing
+     * travels through this process: the names are reported to the operator and otherwise unused.
      */
     secrets: Record<string, string>;
     /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
     /** That value file, workspace-relative, so the gate names the file this deploy actually read. */
     valueFile: string;
-    /** Neither an env-key credential nor a readable auth.json is available. */
-    needsModelCredential: boolean;
     /** Register the deployment's webhooks against the tunnel URL, reporting what each registrar answered. */
     announce: DockerAnnounce;
+    /** Every declared channel and its ingress: which of them a failed login leaves unregistered. */
+    channels: readonly DeclaredChannel[];
     /** `--tunnel` was requested for this run; a kept Compose file must actually contain that service. */
     requireTunnel: boolean;
+    /**
+     * Log the box in (`fastagent login --deployment`) once it is up and before any webhook is pointed at it: a channel pointed at
+     * a box with no model credential answers every message with a failure. Resolves a gate line, or undefined.
+     */
+    boxLogin?: BoxLoginStep;
 }
 export type DockerRunOutcome = {
     ok: true;
@@ -52,14 +59,14 @@ export interface ComposeTunnel {
     url: string;
     connected: boolean;
 }
-export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv) => Promise<ComposeTunnel | undefined>;
+export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string) => Promise<ComposeTunnel | undefined>;
 /** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
 export declare function localUrlFromComposePort(stdout: string): string | undefined;
 /**
  * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
  * connection.
  */
-export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv, options?: {
+export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile: string, options?: {
     attempts?: number;
     intervalMs?: number;
     sleep?: (ms: number) => Promise<void>;

package/dist/deploy/docker/run.js

@@ -1,5 +1,5 @@
-/** `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally. */
 import { waitForHealth } from "../../channels/wait-health.js";
+import { loginGate } from "../channel-ingress.js";
 import { TUNNEL_DNS_LAG_MS, hasTunnelConnection, parseTunnelUrl } from "../../tunnel.js";
 import { registrationGate } from "../registration-gate.js";
 import { MIN_DOCKER_COMPOSE_VERSION } from "./plan.js";
@@ -23,12 +23,12 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * Poll the detached cloudflared service's logs until its Quick Tunnel URL is assigned AND the tunnel reports an edge
  * connection.
  */
-export async function waitForComposeTunnelUrl(docker, composeFile, env, options = {}) {
+export async function waitForComposeTunnelUrl(docker, composeFile, options = {}) {
     const compose = ["compose", "-f", composeFile];
     const attempts = options.attempts ?? 60;
     let assigned;
     for (let attempt = 0; attempt < attempts; attempt++) {
-        const logs = await docker([...compose, "logs", "--no-color", "tunnel"], { capture: true, env });
+        const logs = await docker([...compose, "logs", "--no-color", "tunnel"], { capture: true });
         if (logs.code === 0) {
             assigned ??= parseTunnelUrl(logs.stdout);
             if (assigned && hasTunnelConnection(logs.stdout)) {
@@ -41,14 +41,27 @@ export async function waitForComposeTunnelUrl(docker, composeFile, env, options
     }
     return assigned ? { url: assigned, connected: false } : undefined;
 }
-const defaultTunnelUrlProbe = (docker, composeFile, env) => waitForComposeTunnelUrl(docker, composeFile, env);
+const defaultTunnelUrlProbe = (docker, composeFile) => waitForComposeTunnelUrl(docker, composeFile);
+/**
+ * `/health` asked from inside the agent container, for a topology that publishes no host port. The image always has
+ * node or bun (the generated Dockerfile's base), and both have `fetch`; nothing else is assumed installed.
+ */
+async function containerHealthy(docker, compose, port, stillStarting) {
+    const probe = `r=$(command -v node || command -v bun) && "$r" -e ` +
+        `"fetch('http://127.0.0.1:${port}/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"`;
+    const deadline = Date.now() + 180_000; // the same first-boot budget as the published-port probe
+    while (Date.now() < deadline) {
+        if ((await docker([...compose, "exec", "-T", "agent", "sh", "-c", probe], { capture: true })).code === 0)
+            return true;
+        if (!(await stillStarting()))
+            return false;
+        await sleep(1_000);
+    }
+    return false;
+}
 export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, tunnelUrlProbe = defaultTunnelUrlProbe) {
     const gate = (message) => ({ ok: false, gate: message });
     const compose = ["compose", "-f", plan.composeFile];
-    // The ONE value that is not in the value file, so the ONE that has to cross this process. Set even when absent, so
-    // a same-named variable in the builder's shell cannot interpolate into the container in its place — `spawnRunner`
-    // merges over `process.env`.
-    const env = { FASTAGENT_AUTH_SEED: plan.secrets.FASTAGENT_AUTH_SEED ?? "" };
     // CLI/plugin gate first: unlike a daemon error, spawn ENOENT becomes 127 at the shared runner seam.
     const version = await docker(["compose", "version"], { capture: true });
     if (version.code === 127) {
@@ -57,17 +70,14 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     if (version.code !== 0) {
         return gate("Docker Compose plugin is unavailable — install/enable `docker compose`, then re-run");
     }
-    // Credential gates precede the first side effect (build/create), with distinct remediation.
-    if (plan.needsModelCredential) {
-        return gate("no model credential — run `fastagent login`, or set a provider API key in .env, then re-run");
-    }
+    // The values gate precedes the first side effect (build/create).
     const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
     if (missingValues)
         return gate(missingValues);
     // Name what the container must find, and WHERE — the generated Compose reads the value file itself, so this run
-    // hands Compose nothing but the seed. Saying "passing N secrets to Compose" would be false, and doubly so on a
-    // hand-owned Compose file that has no `env_file` entry at all.
-    const secretNames = Object.keys(plan.secrets).filter((name) => name !== "FASTAGENT_AUTH_SEED");
+    // hands Compose nothing. Saying "passing N secrets to Compose" would be false, and doubly so on a hand-owned
+    // Compose file that has no `env_file` entry at all.
+    const secretNames = Object.keys(plan.secrets);
     if (secretNames.length > 0) {
         log(`${secretNames.length} value(s) the container reads from ${plan.valueFile}: ${secretNames.join(", ")}`);
     }
@@ -75,7 +85,7 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
         return gate("Docker daemon is unavailable — start Docker Engine/Desktop, then re-run");
     }
     // The file on disk is authoritative.
-    const configured = await docker([...compose, "config", "--services"], { capture: true, env });
+    const configured = await docker([...compose, "config", "--services"], { capture: true });
     if (configured.code !== 0) {
         return gate(`could not load ${plan.composeFile} — generated files require Docker Compose >= ` +
             `${MIN_DOCKER_COMPOSE_VERSION}; upgrade Compose or fix the file, then re-run`);
@@ -92,19 +102,16 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
     // Quick Tunnel logs are the control-plane output (the assigned URL).
     if (hasTunnel) {
         log("recreating the ephemeral tunnel service…");
-        if ((await docker([...compose, "rm", "-s", "-f", "tunnel"], { env })).code !== 0) {
+        if ((await docker([...compose, "rm", "-s", "-f", "tunnel"])).code !== 0) {
             return gate(`could not recreate the tunnel service — inspect \`docker compose -f ${plan.composeFile} ps\``);
         }
     }
     log(`building and reconciling ${plan.composeFile}…`);
-    if ((await docker([...compose, "up", "-d", "--build"], { env })).code !== 0) {
+    if ((await docker([...compose, "up", "-d", "--build"])).code !== 0) {
         return gate(`\`docker compose up\` failed — see the Docker output above; fix ${plan.composeFile} and re-run`);
     }
     // Detached `up` can return 0 just before a bad command exits.
-    const running = await docker([...compose, "ps", "--status", "running", "--services"], {
-        capture: true,
-        env,
-    });
+    const running = await docker([...compose, "ps", "--status", "running", "--services"], { capture: true });
     const runningServices = running.stdout.split(/\s+/).filter(Boolean);
     if (running.code !== 0 || !runningServices.includes("agent")) {
         return gate(`the Compose service "agent" is not running — inspect with \`docker compose -f ${plan.composeFile} logs agent\``);
@@ -113,31 +120,47 @@ export async function deployDockerRun(plan, docker, log, healthProbe = defaultHe
         return gate(`the Compose service "tunnel" is not running — inspect with \`docker compose -f ${plan.composeFile} logs tunnel\``);
     }
     // A user-owned topology may deliberately remove the host port and expose only through its own ingress.
-    const published = await docker([...compose, "port", "agent", String(plan.port)], { capture: true, env });
+    const published = await docker([...compose, "port", "agent", String(plan.port)], { capture: true });
     const url = published.code === 0 ? localUrlFromComposePort(published.stdout) : undefined;
-    if (!url) {
+    // Throttled, and an unreadable answer reads as "still starting": the health poll runs twice a second, and a
+    // `compose ps` per poll would cost more than the wait it shortens.
+    let lastCheck = Date.now();
+    const stillStarting = async () => {
+        if (Date.now() - lastCheck < 5_000)
+            return true;
+        lastCheck = Date.now();
+        const ps = await docker([...compose, "ps", "--status", "running", "--services"], { capture: true });
+        return ps.code !== 0 || ps.stdout.split(/\s+/).includes("agent");
+    };
+    if (!url && plan.boxLogin) {
+        // The login runs in the prepared workspace, with the CLI the first boot installs: it needs the box READY, and
+        // with no published port the only place to ask `/health` is inside the container.
+        log("agent is running (no host-published port found); waiting for /health inside the container before login…");
+        if (!(await containerHealthy(docker, compose, plan.port, stillStarting))) {
+            return gate(`agent did not become healthy inside the container — inspect \`docker compose -f ${plan.composeFile} logs agent\``);
+        }
+    }
+    else if (!url) {
         log("agent is running (no host-published port found; using the Compose ingress readiness floor)");
     }
     else {
         const healthUrl = `${url}/health`;
-        // Throttled, and an unreadable answer reads as "still starting": the health poll runs twice a second, and a
-        // `compose ps` per poll would cost more than the wait it shortens.
-        let lastCheck = Date.now();
-        const stillStarting = async () => {
-            if (Date.now() - lastCheck < 5_000)
-                return true;
-            lastCheck = Date.now();
-            const ps = await docker([...compose, "ps", "--status", "running", "--services"], { capture: true, env });
-            return ps.code !== 0 || ps.stdout.split(/\s+/).includes("agent");
-        };
         if (!(await healthProbe(healthUrl, stillStarting))) {
             return gate(`agent did not become healthy at ${healthUrl} — inspect \`docker compose -f ${plan.composeFile} logs agent\``);
         }
     }
+    // `url` travels with this gate: Compose is up, and the operator needs to know where.
+    const notLoggedIn = await plan.boxLogin?.run();
+    if (notLoggedIn) {
+        // Only a tunnel is ours to announce; without one, the webhooks were never this run's to register.
+        const afterLogin = "re-run `fastagent deploy docker --run` (it keeps the login and announces the tunnel)";
+        const channels = hasTunnel ? plan.channels : [];
+        return { ok: false, gate: loginGate({ notLoggedIn, channels, log, afterLogin }), url };
+    }
     if (!hasTunnel)
         return { ok: true, url };
     log("waiting for the Compose tunnel service to publish its Quick Tunnel URL…");
-    const tunnel = await tunnelUrlProbe(docker, plan.composeFile, env);
+    const tunnel = await tunnelUrlProbe(docker, plan.composeFile);
     if (!tunnel) {
         return gate(`tunnel did not publish a Quick Tunnel URL — inspect \`docker compose -f ${plan.composeFile} logs tunnel\``);
     }

package/dist/deploy/fly/plan.d.ts

@@ -1,14 +1,17 @@
 /** `fastagent deploy fly` — the Fly.io deploy PLAN, computed from the resolved definition. */
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type Artifact, type ContainerInput } from "../container.ts";
-import { type DeploymentSecret } from "../secrets.ts";
+import type { DeploymentSecret } from "../secrets.ts";
 export interface FlyPlanInput extends ContainerInput {
     /** Fly app name — globally unique, lowercase; the CLI sanitizes it from the dir basename. */
     appName: string;
     /** The port the app listens on (config.http.port ?? 8787); fly.toml routes to it. */
     port: number;
-    /** What satisfies model auth locally ({@link probeAuthSource}). */
-    modelAuth: string | undefined;
+    /**
+     * The provider the deployment logs in to itself (`fastagent login --deployment`): its credential is not a variable
+     * the plan carries.
+     */
+    boxLogin?: string;
     /**
      * Every declared channel and its ingress — the source of the webhook steps, and whether a machine
      * must stay up for an outbound connection.

package/dist/deploy/fly/plan.js

@@ -1,7 +1,7 @@
 import { webhookRunbook } from "../channel-ingress.js";
 import { containerArtifacts } from "../container.js";
+import { deploymentLoginCommand } from "../box-shell.js";
 import { CRON_CAN_BE_EXTERNAL, WAKEUPS_WHEN_ASLEEP, residencyFor } from "../residency.js";
-import { isEnvKey } from "../secrets.js";
 function flyToml(appName, port, residency) {
     // WHY is residency.ts's to decide; the SETTING and its wording are Fly's. Anything else is an edit to the
     // generated file, which is the artifact's job.
@@ -26,7 +26,7 @@ primary_region = "iad"  # set your region (list: \`fly platform regions\`)
 
 [env]
   FASTAGENT_STATE_DIR = "/data/.state"      # mutable machine state — sessions, channel state, schedule
-  FASTAGENT_SECRETS_DIR = "/data/.secrets"  # seeded (and rotated) credentials — must persist across restarts
+  FASTAGENT_SECRETS_DIR = "/data/.secrets"  # credentials the box logged in with — must persist across restarts
   PORT = "${port}"
 
 [http_service]
@@ -54,7 +54,7 @@ export function isGeneratedFlyToml(content) {
 }
 /** Compute the Fly deploy plan from the resolved definition. */
 export function planFlyDeploy(input) {
-    const { appName, port, modelAuth, channels } = input;
+    const { appName, port, channels } = input;
     // Artifacts sit under the agent prefix, so they never touch the workspace's own deploy files.
     const flyTomlPath = `${input.agentPrefix}fly.toml`;
     const artifacts = [
@@ -92,11 +92,9 @@ export function planFlyDeploy(input) {
     runbook.push(``, `# The volume keeps /data/base (including uncommitted work), .state and .secrets across restarts and deploys.`, `# Each generated release replaces only /data/base/${input.agentPrefix}; other workspace files are initialized once.`, input.shipsGit
         ? `# Git is available for optional collaboration. Verify uploaded history with \`git status\`; clone if the host stripped it.`
         : `# To use Git for collaboration, add deploy: { apt: ["git"] }. Storage durability does not require Git.`);
-    // Model-auth guidance: an env key becomes a secret above.
-    if (!isEnvKey(modelAuth)) {
-        runbook.push(``, modelAuth === undefined
-            ? `# Model auth: none found at the local auth path — a global \`fastagent login\` isn't read here; set FASTAGENT_AUTH_PATH (e.g. ~/.fastagent/.secrets/auth.json), or \`--run\` carries it automatically.`
-            : `# Model auth: your local auth is "${modelAuth}" — the plan can't read its value to set as a secret.`, `#   Set your provider API key as a Fly secret (fly secrets set KEY=...), OR place auth.json at /data/.secrets/ on the volume.`);
+    // The credential is created on the box, never carried: the box is then the only holder of its grant.
+    if (input.boxLogin) {
+        runbook.push(``, `# Model auth: once it is up, the deployment logs in to ${input.boxLogin} itself (from this workspace):`, `${deploymentLoginCommand("fly", input.boxLogin)}`);
     }
     // The fastagent-only post-step: point each channel at the live URL.
     const steps = webhookRunbook(`https://${appName}.fly.dev`, channels);

package/dist/deploy/fly/run.d.ts

@@ -1,10 +1,11 @@
 /** `fastagent deploy fly --run` — drive flyctl to completion. */
+import type { BoxLoginStep } from "../box-shell.ts";
 import { type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";
-import type { CliRunner } from "../runner.ts";
+import { type CliRunner } from "../runner.ts";
 export interface FlyRunPlan {
     appName: string;
-    /** `KEY=value` secrets to set on Fly: the value file's variables + `FASTAGENT_AUTH_SEED` for a file credential. */
+    /** `KEY=value` secrets to set on Fly: the value file's variables. */
     secrets: Record<string, string>;
     /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
@@ -19,6 +20,11 @@ export interface FlyRunPlan {
      * resolve it relative to the config's own directory).
      */
     dockerfile: string;
+    /**
+     * Log the box in (`fastagent login --deployment`) once it is up and before any webhook is pointed at it: a channel pointed at
+     * a box with no model credential answers every message with a failure. Resolves a gate line, or undefined.
+     */
+    boxLogin?: BoxLoginStep;
 }
 /** Done, or a gate the operator must clear before re-running (printed + non-zero exit by the CLI). */
 export type FlyRunOutcome = {

package/dist/deploy/fly/run.js

@@ -1,5 +1,5 @@
-/** `fastagent deploy fly --run` — drive flyctl to completion. */
-import { publicHealthGate, registerWebhooks } from "../channel-ingress.js";
+import { loginGate, publicHealthGate, registerWebhooks, } from "../channel-ingress.js";
+import { readOutput } from "../runner.js";
 import { missingValuesGate } from "../secrets.js";
 /**
  * The `Type` values that put an app on `https://<app>.fly.dev`, BY FAMILY — one entry per allocate command, because
@@ -28,27 +28,6 @@ export function listHasName(stdout, name) {
         throw new Error(`expected a JSON array, got ${typeof entries}`);
     return entries.some((o) => o.Name === name);
 }
-/**
- * A read-only `fly … list --json`, reduced to the question the next step asks of it — or the gate for a list we cannot
- * act on.
- */
-async function readList(fly, args, read) {
-    // The command as RUN, not a restatement of it.
-    const cmd = `fly ${args.join(" ")}`;
-    const result = await fly(args, { capture: true });
-    if (result.code !== 0)
-        return { gate: `\`${cmd}\` failed — see the flyctl output above; fix and re-run` };
-    try {
-        return { value: read(result.stdout) };
-    }
-    catch (error) {
-        // The one place a parse failure is allowed to stop being an exception.
-        return {
-            gate: `\`${cmd}\` was unreadable (${error instanceof Error ? error.message : String(error)}) — ` +
-                `run it yourself and check the flyctl version; fix and re-run`,
-        };
-    }
-}
 export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
     const gate = (g) => ({ ok: false, gate: g });
     // 1.
@@ -60,7 +39,7 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
     if (missingValues)
         return gate(missingValues);
     // 3.
-    const appExists = await readList(fly, ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
+    const appExists = await readOutput(fly, "fly", ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
     if ("gate" in appExists)
         return gate(appExists.gate);
     if (appExists.value) {
@@ -77,7 +56,7 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
     // which machine (guest size + image) must fit on the host the volume is pinned to. Pre-creating one here placed it
     // blind, and a host with disk but no compute failed the deploy with `insufficient resources … with existing volume`.
     // 5.
-    const addresses = await readList(fly, ["ips", "list", "-a", plan.appName, "--json"], ingressAddresses);
+    const addresses = await readOutput(fly, "fly", ["ips", "list", "-a", plan.appName, "--json"], ingressAddresses);
     if ("gate" in addresses)
         return gate(addresses.gate);
     // Check-then-act PER FAMILY: an app that already holds one must still be given the other, or the gate between the
@@ -131,9 +110,20 @@ export async function deployFlyRun(plan, fly, log, registrars, healthProbe) {
         inspectHint: `the app itself deployed — inspect \`fly logs -a ${plan.appName}\`, then re-run once it answers ` +
             `(a re-run repeats the remote build)`,
         probe: healthProbe,
+        ...(plan.boxLogin ? { login: plan.boxLogin.command } : {}),
     });
     if (healthGate)
         return gate(healthGate);
+    const notLoggedIn = await plan.boxLogin?.run();
+    if (notLoggedIn) {
+        return gate(loginGate({
+            notLoggedIn,
+            channels: plan.channels,
+            log,
+            baseUrl,
+            afterLogin: "re-run `fastagent deploy fly --run` (it keeps the login)",
+        }));
+    }
     // 9.
     const registrationGateMsg = await registerWebhooks({
         baseUrl,

package/dist/deploy/preflight.d.ts

@@ -26,20 +26,22 @@ interface DeployFacts {
     values: ReadonlyMap<string, string>;
     /** That file, workspace-relative — the name every "set it here" message must use. */
     valueFile: string;
-    /** What satisfies model auth locally — an env-var name, an OAuth/stored label, or undefined. */
+    /**
+     * The variable the value file carries the model's key in (the provider's own, or a models.json `"$NAME"`), or
+     * undefined when no key travels that way ({@link credentialRoute}).
+     */
     modelAuth: string | undefined;
     /**
-     * The definition itself carries the model key (a models.json literal `apiKey`, or a `!command` run on the host), so
-     * there is nothing for `--run` to carry AND nothing to gate: `fastagent login` cannot serve a custom provider, so
-     * gating on it would strand a correctly configured agent.
+     * The provider the deployment must log in to itself (`fastagent login --deployment`): the model's credential does
+     * not travel, because it is neither a variable in the value file nor carried by the definition (a models.json
+     * literal `apiKey` or `!command`). Nothing from this machine's credentials file is ever copied, so a login on the
+     * box is its only holder.
      */
-    modelKeyInDefinition: boolean;
+    boxLogin: string | undefined;
     /** Every tool/routine/channel declaration — the names the value file must supply, by declaring file. */
     declaredSecrets: DeclaredSecret[];
     /** The runbook's variable list: the declared names, then everything else the value file carries. */
     secrets: DeploymentSecret[];
-    /** The project-level auth file `--run` reads to carry the credential (probed with the same path). */
-    authPath: string;
     /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */
     container: ContainerInput;
     port: number;