@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/deploy/box-shell.js

@@ -0,0 +1,28 @@
+/**
+ * A running box's owner-authenticated shell, as a byte channel: what `fastagent login --deployment` speaks through.
+ * Host-neutral: Docker, Fly and Railway open it by running their own CLI (`processShell`); AgentCore opens a
+ * WebSocket (`agentcore/shell.ts`). Whoever opens one only writes bytes in and reads bytes out.
+ */
+import { spawn } from "node:child_process";
+/** A host CLI that runs a command on the box itself: `bin ...args(command)`, run from `cwd`. */
+export function processShell(bin, args, cwd) {
+    return {
+        async open(command) {
+            const child = spawn(bin, args(command), { cwd, stdio: ["pipe", "pipe", "inherit"] });
+            // The box may exit before reading an answer; its result (or its absence) is what gets reported, not the EPIPE.
+            child.stdin.on("error", () => { });
+            const closed = new Promise((resolve) => {
+                child.on("error", (error) => resolve({ opened: false, error: `could not run ${bin}: ${error.message}` }));
+                child.on("close", (code, signal) => resolve({ opened: true, how: signal ? `signal ${signal}` : `exit ${code}` }));
+            });
+            return { output: child.stdout, input: child.stdin, closed };
+        },
+    };
+}
+/**
+ * The command that logs a deployment in, as every message and runbook names it: with the provider when it is known,
+ * because the model needs THAT one, and a menu invites another.
+ */
+export function deploymentLoginCommand(host, provider) {
+    return `fastagent login ${provider ? `${provider} ` : ""}--deployment ${host}`;
+}

package/dist/deploy/build-context.js

@@ -1,8 +1,3 @@
-/**
- * What a deploy's BUILD CONTEXT (the workspace) holds that must not ship, and whether an ignore file the author kept
- * still keeps it out. A kept workspace-root `.dockerignore` silently replaces the generated one's protections, so the
- * pre-flight asks it the same questions the generated one answers by construction.
- */
 import { readdir } from "node:fs/promises";
 import { basename, isAbsolute, join, relative, sep } from "node:path";
 import ignore from "ignore";
@@ -29,6 +24,20 @@ function dockerignoreMatcher(text) {
     const matcher = ignore({ ignorecase: false }).add(anchored);
     return (path) => matcher.ignores(path);
 }
+/**
+ * A directory's entries, or none when it does not exist. Any other failure throws: the leak scan would otherwise pass
+ * on a directory it never read, and a credential inside it would ship without a word.
+ */
+async function entriesIfExists(path) {
+    try {
+        return await readdir(path, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw new Error(`cannot read ${path} to check what the image would ship: ${error.message}`);
+    }
+}
 export async function buildContextPaths(workspace, agentDir, agentPrefix, authPath) {
     const inContext = (p) => {
         const rel = relative(workspace, p);
@@ -55,7 +64,7 @@ export async function buildContextPaths(workspace, agentDir, agentPrefix, authPa
     const stateShips = stateRel !== undefined && (await exists(join(workspace, stateRel))) ? stateRel : undefined;
     // The `.env` family at the two levels fastagent is RESPONSIBLE for: the agent dir and the workspace root.
     const dotEnvFiles = async (relDir) => {
-        const names = await readdir(join(workspace, relDir || ".")).catch(() => []);
+        const names = (await entriesIfExists(join(workspace, relDir || "."))).map((entry) => entry.name);
         // POSIX separators, like every other context-relative path here (`inContext`).
         return names
             .filter((n) => (n === ".env" || n.startsWith(".env.")) && n !== ".env.example")
@@ -65,7 +74,7 @@ export async function buildContextPaths(workspace, agentDir, agentPrefix, authPa
     // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on purpose (they
     // carry no values; the generated ignore re-includes them by name).
     const secretDirFiles = async (dirRel) => {
-        const entries = await readdir(join(workspace, dirRel), { withFileTypes: true }).catch(() => []);
+        const entries = await entriesIfExists(join(workspace, dirRel));
         const files = [];
         for (const entry of entries) {
             if (entry.name === ".gitignore" || entry.name === ".env.example")

package/dist/deploy/channel-ingress.d.ts

@@ -37,7 +37,8 @@ export type PublicHealthProbe = (healthUrl: string) => Promise<boolean>;
  * report success. The channels that DO verify (Slack/Feishu challenge) would fail here too, but as "registration
  * failed" — a diagnosis that hides the actual cause.
  *
- * Asked ONLY when this deployment actually has a webhook to point. A definition with none (schedules only, the
+ * Asked ONLY when this deployment actually has a webhook to point, or a login on the box follows (the box must
+ * have prepared its workspace and installed the CLI the login runs). A definition with neither (schedules only, the
  * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
  * invent a failure for a deploy run from a network that cannot reach the platform's edge.
  */
@@ -48,7 +49,25 @@ export declare function publicHealthGate(input: {
     /** How THIS host is inspected and re-run — the only per-host words in the gate. */
     inspectHint: string;
     probe?: PublicHealthProbe;
+    /** The login that follows on the box (`fastagent login --deployment <host>`), when one does. */
+    login?: string;
 }): Promise<string | undefined>;
+/**
+ * The gate when the login on the box did not happen. It stops the run BEFORE registration (a channel pointed at a box
+ * with no model credential fails every message), so the login it asks for does not register anything by itself: with
+ * a webhook to point, the refusal says what comes after the login, and prints the lines to do it by hand when the
+ * URL is known.
+ */
+export declare function loginGate(input: {
+    /** What the login reported, ending with the command to run. */
+    notLoggedIn: string;
+    channels: readonly DeclaredChannel[];
+    log: (msg: string) => void;
+    /** What THIS host does about its webhooks once the box is logged in — the only per-host words in the gate. */
+    afterLogin: string;
+    /** Where the channels point; unset when the host has not minted it yet (Docker's tunnel is read after). */
+    baseUrl?: string;
+}): string;
 /** {@link pointChannelsAt} plus the shared gate policy, for a command that EXITS. */
 export declare function registerWebhooks(input: {
     baseUrl: string;

package/dist/deploy/channel-ingress.js

@@ -85,24 +85,51 @@ const WAIT_NOTICE_MS = 15_000;
  * report success. The channels that DO verify (Slack/Feishu challenge) would fail here too, but as "registration
  * failed" — a diagnosis that hides the actual cause.
  *
- * Asked ONLY when this deployment actually has a webhook to point. A definition with none (schedules only, the
+ * Asked ONLY when this deployment actually has a webhook to point, or a login on the box follows (the box must
+ * have prepared its workspace and installed the CLI the login runs). A definition with neither (schedules only, the
  * built-in `POST /invoke`, or long-connection channels) needs no inbound reachability at all, and demanding it would
  * invent a failure for a deploy run from a network that cannot reach the platform's edge.
  */
 export async function publicHealthGate(input) {
-    if (webhookKinds(input.channels).length === 0)
+    if (webhookKinds(input.channels).length === 0 && input.login === undefined)
         return undefined;
     const healthUrl = `${input.baseUrl}/health`;
     input.log(`waiting for ${healthUrl} (up to ${PUBLIC_HEALTH_TIMEOUT_MS / 1000}s)…`);
     const probe = input.probe ?? ((url) => waitForHealth(url, PUBLIC_HEALTH_TIMEOUT_MS, 500, announce(input.log)));
     if (await probe(healthUrl))
         return undefined;
-    // The infrastructure is up and only the webhook is missing, so hand over the manual route rather than leaving
-    // `re-run` as the only way out (a Fly re-run repeats the remote build).
-    for (const line of webhookRunbook(input.baseUrl, input.channels))
+    // The infrastructure is up and only activation is missing, so hand over the manual route rather than leaving
+    // `re-run` as the only way out (a Fly re-run repeats the remote build). The login comes first: a channel pointed at
+    // a box with no model credential fails every message.
+    const steps = [
+        ...(input.login !== undefined ? [`# First, log the box in: ${input.login}`] : []),
+        ...webhookRunbook(input.baseUrl, input.channels),
+    ];
+    for (const line of steps)
+        input.log(line);
+    const byHand = webhookKinds(input.channels).length > 0
+        ? `To finish by hand once it answers, use the lines above.`
+        : `Once it answers, log it in: ${input.login}.`;
+    return (`the deployed agent did not become healthy at ${healthUrl}, so it was not activated — ${input.inspectHint}. ` +
+        byHand);
+}
+/**
+ * The gate when the login on the box did not happen. It stops the run BEFORE registration (a channel pointed at a box
+ * with no model credential fails every message), so the login it asks for does not register anything by itself: with
+ * a webhook to point, the refusal says what comes after the login, and prints the lines to do it by hand when the
+ * URL is known.
+ */
+export function loginGate(input) {
+    if (webhookKinds(input.channels).length === 0)
+        return input.notLoggedIn;
+    const byHand = input.baseUrl === undefined ? [] : webhookRunbook(input.baseUrl, input.channels);
+    for (const line of byHand)
         input.log(line);
-    return (`the deployed agent did not become healthy at ${healthUrl}, so no webhook was registered — ${input.inspectHint}. ` +
-        `To point the channels by hand instead, use the lines above.`);
+    // "No webhook was registered" would be about THIS run only: one an earlier deploy registered still points here.
+    return (`${input.notLoggedIn}. This deploy registered no webhook, and logging in registers none; any an earlier deploy ` +
+        `registered still points here, and every message it brings fails until the box is logged in. Once it is, ` +
+        `${input.afterLogin}` +
+        (byHand.length > 0 ? `. The lines above point the channels by hand.` : ``));
 }
 /**
  * Keep the wait visible. This occupies `waitForHealth`'s liveness slot without answering it: neither Fly nor Railway

package/dist/deploy/container.d.ts

@@ -2,6 +2,20 @@ export interface Artifact {
     path: string;
     content: string;
 }
+/**
+ * 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 declare function boxLoginCommand(agent: string, args: readonly string[], storage?: string): string;
 /** Fixed first-line prefix of a fastagent-generated Dockerfile. */
 export declare const GENERATED_DOCKERFILE_MARKER = "# Generated by `fastagent deploy`";
 /** The ONE predicate for "did fastagent generate this Dockerfile?". */

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);