@fastagent-sh/fastagent 0.16.0 → 0.16.1

package/README.md

@@ -196,7 +196,7 @@ FastAgent is pre-1.0. The stable design center is the Agent Handler contract in
 The neutral contract leaves room for capabilities that are not complete product features yet:
 
 - **Durable execution**: Telegram, Slack, and Feishu/Lark accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
-- **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
+- **Sandboxed execution** — `ExecutionEnv` governs the default coding tools, but ② project context and author-written `tools/` still reach the local process; a complete sandbox adapter is future work.
 - **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
 - **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
 - **More deploy targets** — local Docker, Fly, Railway, and AWS Bedrock AgentCore ship today; the generated container is the portable path for other hosts.

package/dist/bind.d.ts

@@ -0,0 +1,34 @@
+/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". No other DNS name — a
+ *  bind address must be an address of THIS machine, and resolving one is not this module's job. */
+export declare function isBindAddress(host: string): boolean;
+/**
+ * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is
+ * already an address. Applied where a value ENTERS (the flag, `http.host`), so nothing downstream ever
+ * holds a name — not deferring the resolution but removing it, which is the module's whole point.
+ *
+ * Two things go wrong otherwise, and both are silent. `server.listen` hands the name to `dns.lookup`,
+ * which picks ONE of 127.0.0.1/::1 by rules we do not control — so what got bound is unknown here. And
+ * `clientHost` would then write that NAME into control.json and the copyable curl, where a consumer
+ * resolves it again, possibly to the other one.
+ */
+export declare function bindAddress(host: string): string;
+/**
+ * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and
+ * answers on loopback too; `loopback` is this machine only; `specific` is one interface, reachable
+ * only as itself. Loopback covers the whole reserved range (127/8, ::1) — a `127.0.0.2` bind is no
+ * more LAN-reachable than `127.0.0.1`.
+ */
+export declare function classifyBind(host: string | undefined): "wildcard" | "loopback" | "specific";
+/**
+ * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name
+ * resolves to (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that
+ * way. cloudflared dials by name, so `--tunnel` needs this question, not `classifyBind`'s reach.
+ */
+export declare function answersLocalhost(host: string | undefined): boolean;
+/** How to NAME a bind in a message: the wildcard is every interface, so calling it one address would
+ *  understate it; anything else is dialable as itself. THE renderer — the ready lines, the
+ *  already-in-use refusal and the generic bind failure all read a bind through this one, so a reader
+ *  never sees the same bind described two ways. */
+export declare function bindLabel(host: string | undefined, port: number): string;
+/** The address a local client should dial for a serve bound to `host` (control.json, the ready log). */
+export declare function clientHost(host: string | undefined): string;

package/dist/bind.js

@@ -0,0 +1,74 @@
+/**
+ * The ONE reading of a bind address, shared by everything that parses, binds, warns about, or ships
+ * one (the CLI flag, `http.host` validation, the Node host, the deploy pre-flight). Engine- and
+ * host-neutral on purpose: a bind address is a plain value, and two parsers of it would disagree.
+ */
+import { isIP } from "node:net";
+/** Lowercase, unbracketed, IPv4-mapped IPv6 reduced to its IPv4 form — the form the checks below read.
+ *  Brackets come off only as a PAIR: a half-bracketed `[::1` must stay invalid, not become an address. */
+function normalize(host) {
+    return host
+        .toLowerCase()
+        .replace(/^\[(.+)]$/, "$1")
+        .replace(/^::ffff:/, "");
+}
+/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". No other DNS name — a
+ *  bind address must be an address of THIS machine, and resolving one is not this module's job. */
+export function isBindAddress(host) {
+    const h = normalize(host);
+    return h === "localhost" || isIP(h) !== 0;
+}
+/**
+ * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is
+ * already an address. Applied where a value ENTERS (the flag, `http.host`), so nothing downstream ever
+ * holds a name — not deferring the resolution but removing it, which is the module's whole point.
+ *
+ * Two things go wrong otherwise, and both are silent. `server.listen` hands the name to `dns.lookup`,
+ * which picks ONE of 127.0.0.1/::1 by rules we do not control — so what got bound is unknown here. And
+ * `clientHost` would then write that NAME into control.json and the copyable curl, where a consumer
+ * resolves it again, possibly to the other one.
+ */
+export function bindAddress(host) {
+    return normalize(host) === "localhost" ? "127.0.0.1" : host;
+}
+/**
+ * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and
+ * answers on loopback too; `loopback` is this machine only; `specific` is one interface, reachable
+ * only as itself. Loopback covers the whole reserved range (127/8, ::1) — a `127.0.0.2` bind is no
+ * more LAN-reachable than `127.0.0.1`.
+ */
+export function classifyBind(host) {
+    if (host === undefined)
+        return "wildcard";
+    const h = normalize(host);
+    if (h === "0.0.0.0" || h === "::" || h === "::0")
+        return "wildcard";
+    if (h === "localhost" || h === "::1" || /^127\.\d+\.\d+\.\d+$/.test(h))
+        return "loopback";
+    return "specific";
+}
+/**
+ * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name
+ * resolves to (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that
+ * way. cloudflared dials by name, so `--tunnel` needs this question, not `classifyBind`'s reach.
+ */
+export function answersLocalhost(host) {
+    if (classifyBind(host) === "wildcard")
+        return true;
+    const h = normalize(host);
+    return h === "localhost" || h === "127.0.0.1" || h === "::1";
+}
+/** How to NAME a bind in a message: the wildcard is every interface, so calling it one address would
+ *  understate it; anything else is dialable as itself. THE renderer — the ready lines, the
+ *  already-in-use refusal and the generic bind failure all read a bind through this one, so a reader
+ *  never sees the same bind described two ways. */
+export function bindLabel(host, port) {
+    return classifyBind(host) === "wildcard" ? `port ${port}` : `${clientHost(host)}:${port}`;
+}
+/** The address a local client should dial for a serve bound to `host` (control.json, the ready log). */
+export function clientHost(host) {
+    if (classifyBind(host) === "wildcard")
+        return "127.0.0.1";
+    // biome-ignore lint/style/noNonNullAssertion: only a wildcard bind leaves host undefined
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}

package/dist/channels/agentcore-state.js

@@ -126,17 +126,25 @@ export function createStateSync(options) {
     let looping = false;
     const runRestore = async (urls) => {
         const res = await doFetch(urls.getUrl, { method: "GET" });
-        // ONLY a proven 404 is "first deploy". The signer holds s3:GetObject on exactly this key, so a
-        // missing object answers NoSuchKey/404; a 403 means an expired or malformed signature, or a
-        // revoked permission — i.e. the snapshot may well exist. Reading 403 as "absent" would serve an
-        // empty agent and then overwrite the real snapshot with that emptiness.
+        // ONLY a proven 404 is "first deploy". A missing key answers 404 only because the generated
+        // template grants the signer s3:ListBucket on the snapshot prefix — without it S3 folds "absent"
+        // into 403 (anti-enumeration). A 403 therefore means an expired or malformed signature, a
+        // revoked permission, or a template from before that grant — i.e. the snapshot may well exist.
+        // Reading 403 as "absent" would serve an empty agent and then overwrite the real snapshot with
+        // that emptiness.
         if (res.status === 404) {
             log.info("[agentcore] no state snapshot yet — starting from an empty state root (first deploy)");
             restored = true;
             return;
         }
-        if (!res.ok)
-            throw new Error(`state snapshot GET failed: ${res.status}`);
+        if (!res.ok) {
+            const hint = res.status === 403
+                ? " (an expired presigned URL, a revoked permission, or a template generated before the " +
+                    "ForwarderRole granted s3:ListBucket — S3 answers 403 even for a MISSING first-deploy " +
+                    "snapshot without it; regenerate with `fastagent deploy agentcore --force` and redeploy)"
+                : "";
+            throw new Error(`state snapshot GET failed: ${res.status}${hint}`);
+        }
         const written = await unpackIntoStateRoot(stateRoot, Buffer.from(await res.arrayBuffer()));
         log.info(`[agentcore] restored ${written} state file(s) from the snapshot`);
         restored = true;

package/dist/cli/commands/deploy.d.ts

@@ -13,3 +13,16 @@ export interface DeployOptions {
     input?: boolean;
 }
 export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;
+/**
+ * Write the plan's artifacts under `target`, honouring the ownership rule: a file we did not generate is
+ * never touched, ours is kept unless `--force`. Exported for its own test — this is a four-branch state
+ * machine over (exists, ours, force) that used to be proven by spawning the CLI eight times, which is
+ * command LOGIC re-run through a subprocess (see vitest.config.ts) and the suite's slowest test.
+ */
+export declare function writeArtifacts(target: string, artifacts: {
+    path: string;
+    content: string;
+}[], options: {
+    force: boolean;
+    alwaysWrite?: string[];
+}): Promise<void>;

package/dist/cli/commands/deploy.js

@@ -413,7 +413,13 @@ function isOurArtifact(path, content) {
         return isGeneratedAgentcoreTemplate(content);
     return false;
 }
-async function writeArtifacts(target, artifacts, options) {
+/**
+ * Write the plan's artifacts under `target`, honouring the ownership rule: a file we did not generate is
+ * never touched, ours is kept unless `--force`. Exported for its own test — this is a four-branch state
+ * machine over (exists, ours, force) that used to be proven by spawning the CLI eight times, which is
+ * command LOGIC re-run through a subprocess (see vitest.config.ts) and the suite's slowest test.
+ */
+export async function writeArtifacts(target, artifacts, options) {
     for (const a of artifacts) {
         const abs = join(target, a.path);
         // Pure build output, not operator-owned configuration. It must track the generated template/runbook.

package/dist/cli/commands/dev.d.ts

@@ -1,5 +1,6 @@
 export interface DevOptions {
     port?: string;
+    bind?: string;
     model?: string;
     authPath?: string;
     /** false ⇔ `--no-watch`. */

package/dist/cli/commands/dev.js

@@ -12,9 +12,10 @@ import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { workspaceHint } from "../../paths.js";
+import { bindAddress } from "../../bind.js";
 import { failStartup, placementOrExit } from "../fail.js";
-import { maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
-import { parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { assertTunnelBindable, maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
+import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runDev(dirArg, opts) {
     const dir = resolve(dirArg);
     const placement = placementOrExit(dir);
@@ -33,12 +34,16 @@ export async function runDev(dirArg, opts) {
         await serveOnce(dir, opts);
         return;
     }
-    parsePort(opts.port, "--port", "flag"); // flag-shape check before spawning
+    parsePort(opts.port, "--port", "flag"); // flag-shape checks before spawning
+    // The --bind/--tunnel conflict is decidable from flags alone: refuse it HERE, before a worker and a
+    // tunnel exist. The worker repeats the check because `http.host` can supply the address instead.
+    assertTunnelBindable(parseBind(opts.bind), opts.tunnel ?? false, "flag");
     await runDevSupervisor(placement, { tunnel: opts.tunnel ?? false });
 }
 /** Assemble the agent and serve it once (the dev worker; also the --no-watch path). */
 async function serveOnce(dir, opts) {
     const portFlag = parsePort(opts.port, "--port", "flag");
+    const bindFlag = parseBind(opts.bind);
     loadDotEnv(placementOrExit(dir).agentDir);
     installProxyFetch();
     const a = await createPiAgentFromDir(dir, {
@@ -57,12 +62,18 @@ async function serveOnce(dir, opts) {
     // out in start (level info), keeping end-user content out of production logs. Wired in both postures.
     const traced = logAgentLoop(a.agent);
     const routed = await routesFor(a.agentDir, traced, a.stateRoot, a.sessionControl).catch(failStartup);
+    // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
+    // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
+    const configured = a.config.http?.host;
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
     const withControl = mountSessionControl(routed.routes, a.sessionControl, a.stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced, // the remote data plane (POST /control/invoke) drives the SAME traced agent
+        host,
     });
     await startSchedules(a.agentDir, traced, a.stateRoot, a.config.selfSchedule ?? false);
-    serve({ ...routed, routes: withControl.routes }, portFlag ?? a.config.http?.port ?? 8787, (p) => {
+    serve({ ...routed, routes: withControl.routes }, { port: portFlag ?? a.config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
         maybeTunnel(a.agentDir, routed.routeChannels, p, opts.tunnel ?? false, a.stateRoot);
     });

package/dist/cli/commands/info.js

@@ -24,7 +24,7 @@ export async function runInfo(dirArg, opts) {
     // tool), is isolated the same way everywhere (G2): info, dev, AND start report it and keep going with
     // the tools that loaded. The `error`/`.catch` below only fires for a whole-load fault (an unreadable
     // tools/ dir), not a single bad file.
-    const tools = await resolveAgentTools(config, agentDir, workspace)
+    const tools = await resolveAgentTools(config, agentDir)
         .then((r) => ({
         names: r.toolNames,
         deferred: r.deferredToolNames,

package/dist/cli/commands/start.d.ts

@@ -1,5 +1,6 @@
 export interface StartOptions {
     port?: string;
+    bind?: string;
     model?: string;
     sessionsDir?: string;
     authPath?: string;

package/dist/cli/commands/start.js

@@ -17,14 +17,16 @@ import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { exists } from "../../paths.js";
+import { bindAddress } from "../../bind.js";
 import { failStartup, placementOrExit } from "../fail.js";
-import { maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
-import { parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { assertTunnelBindable, maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules, } from "../serve.js";
+import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
     // Flag validation first: a bad --port is a USAGE error (exit 2), and reporting it must not depend on
     // the directory being an agent (which is a runtime/environment failure, exit 1).
     const portFlag = parsePort(opts.port, "--port", "flag");
+    const bindFlag = parseBind(opts.bind);
     const placement = placementOrExit(dir);
     setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
     loadDotEnv(placement.agentDir);
@@ -88,9 +90,15 @@ export async function runStart(dirArg, opts) {
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
     const routed = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: !agentcore }).catch(failStartup);
+    // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
+    // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
+    const configured = config.http?.host;
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
     const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced,
+        host,
     });
     // AgentCore + selfSchedule: register the wake-ALARM sink BEFORE the scheduler starts — the boot
     // wake pump may advance a recurring entry (a store save) and that save must already re-arm its
@@ -126,7 +134,7 @@ export async function runStart(dirArg, opts) {
         }
         log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
     }
-    serve({ ...routed, routes }, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => {
+    serve({ ...routed, routes }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
         maybeTunnel(agentDir, routed.routeChannels, p, opts.tunnel ?? false, stateRoot);
     });

package/dist/cli/commands/tool.js

@@ -1,5 +1,6 @@
 /** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
 import { resolve } from "node:path";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadDotEnv } from "../../env.js";
 import { loadConfig } from "../../engines/pi/config.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
@@ -16,7 +17,7 @@ export async function runTool(name, argsJson, dirArg) {
     // The same tool set dev/start mount (defaults + config.tools + discovered, deduped), so the runner
     // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve the
     // placement like the openers, so `fastagent tool` finds the SAME tools/ as dev/start.
-    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir, workspace).catch(failStartup);
+    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir).catch(failStartup);
     for (const c of toolCollisions) {
         console.error(`[fastagent] warn: tool "${c.name}" (${c.source}) is shadowed by a default/config tool — not mounted`);
     }
@@ -25,7 +26,14 @@ export async function runTool(name, argsJson, dirArg) {
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
-    const result = await turnContext.run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args)).catch(failStartup);
+    // Two contexts, because the two tool families read different ones and this command must serve both
+    // exactly as serving does: fastagent's own tools take cwd/session/activation from `turnContext`
+    // (AsyncLocalStorage), and pi's default coding tools take the ExecutionEnv from the harness's TOOL
+    // context — which no harness supplies here, so this stands in for it, rooted at the same workspace.
+    const env = new NodeExecutionEnv({ cwd: workspace });
+    const result = await turnContext
+        .run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args, undefined, undefined, { env }))
+        .catch(failStartup);
     const out = result?.details !== undefined
         ? result.details
         : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");

package/dist/cli/program.js

@@ -27,6 +27,10 @@ const NO_INPUT = {
     description: "never prompt (CI/scripts) — missing information becomes an error instead of a question",
 };
 const PORT = { flags: "--port <n>", description: "HTTP port" };
+const BIND = {
+    flags: "--bind <addr>",
+    description: "bind address (default: all interfaces; 127.0.0.1 keeps it off the LAN)",
+};
 const TUNNEL = {
     flags: "--tunnel",
     description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
@@ -85,6 +89,7 @@ const dev = {
     args: [DIR_ARG],
     flags: [
         PORT,
+        BIND,
         MODEL,
         AUTH_PATH,
         { flags: "--no-watch", description: "serve once, no file-watching" },
@@ -97,6 +102,7 @@ const dev = {
     ],
     run: async (args, f) => (await import("./commands/dev.js")).runDev(args[0], {
         port: f.port,
+        bind: f.bind,
         model: f.model,
         authPath: f.authPath,
         watch: f.watch !== false,
@@ -218,6 +224,7 @@ const start = {
     args: [DIR_ARG],
     flags: [
         PORT,
+        BIND,
         MODEL,
         { flags: "--sessions-dir <dir>", description: "sessions directory override" },
         AUTH_PATH,
@@ -230,6 +237,7 @@ const start = {
     ],
     notes: "Precedence chains:\n" +
         "  port:     --port > PORT env > fastagent.config.ts http.port > 8787\n" +
+        "  bind:     --bind > fastagent.config.ts http.host > all interfaces\n" +
         "  state:    FASTAGENT_STATE_DIR > <agent dir>/.state — mutable machine state\n" +
         "            (sessions, channel state, schedule state); point it at a mounted\n" +
         "            volume so a redeploy that replaces the directory never wipes it\n" +
@@ -240,6 +248,7 @@ const start = {
         "            share one credential across projects)",
     run: async (args, f) => (await import("./commands/start.js")).runStart(args[0], {
         port: f.port,
+        bind: f.bind,
         model: f.model,
         sessionsDir: f.sessionsDir,
         authPath: f.authPath,

package/dist/cli/serve.d.ts

@@ -32,6 +32,7 @@ export declare function routesFor(agentDir: string, agent: Agent, stateRoot: str
 export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
     tunnel?: boolean;
     agent?: Agent;
+    host?: string;
 }): {
     routes: Routes;
     announce: (boundPort: number) => void;
@@ -49,12 +50,35 @@ export declare function mountAgentcore(routes: Routes, options: {
     schedules: LoadedSchedule[];
     onStateReady?: () => void;
 }): Routes;
+/**
+ * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
+ * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
+ * `127.0.0.2` bind, loopback though it is — would leave the tunnel up and 502ing every request.
+ * Checked BEFORE the bind (the flag alone pre-spawn in `dev`, again once config is loaded, since
+ * `http.host` can carry the address), so the failure is clean rather than a live-but-broken public URL.
+ * `source` decides the exit code, per fail.ts: a flag COMBINATION is a usage error (2), a value that
+ * came from config is broken runtime configuration (1).
+ */
+export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean, source: "flag" | "config"): void;
+/**
+ * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
+ * ONE function because they are one message — they were two, and `--bind` updated the first while the
+ * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
+ * neither can be changed without the other in view, and the address has a single derivation.
+ *
+ * A wildcard bind is every interface, and naming one address there would understate it — but the curl
+ * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ */
+export declare function readyAddressLines(host: string | undefined, boundPort: number, builtinInvoke: boolean): string[];
 /**
  * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
  * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
- * the sole clean-shutdown command.
+ * the sole clean-shutdown command. `host` unset binds all interfaces.
  */
-export declare function serve(surface: ServingSurface, port: number, onListening?: (boundPort: number) => void): void;
+export declare function serve(surface: ServingSurface, bind: {
+    port: number;
+    host?: string;
+}, onListening?: (boundPort: number) => void): void;
 /** Start a Cloudflare tunnel for route channels only. */
 export declare function maybeTunnel(agentDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): void;
 /**

package/dist/cli/serve.js

@@ -12,13 +12,14 @@ import { INVOKE_EXAMPLE_BODY, createInvokeHandler } from "../channels/http.js";
 import { text } from "../channels/respond.js";
 import { loadChannels } from "../engines/pi/channel.js";
 import { reportModuleLoadFailures } from "../engines/pi/report.js";
+import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
 import { parseRouteKey, router, serveNode } from "../host/node.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
 import { loadSchedules } from "../schedule/discover.js";
 import { createScheduler, fireScheduleOnce } from "../schedule/scheduler.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
-import { failStartup } from "./fail.js";
+import { failStartup, failUsage } from "./fail.js";
 /**
  * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
  * POST `/invoke` only when neither a route nor a long-connection channel was declared.
@@ -90,15 +91,22 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
             // Atomic (tmp+rename, the state.ts pattern): attach re-reads this file exactly during the
             // restart window — a torn read would be misdiagnosed as "serve gone".
             const tmp = `${path}.tmp`;
-            writeFileSync(tmp, `${JSON.stringify({ url: `http://127.0.0.1:${boundPort}`, token })}\n`, { mode: 0o600 });
+            writeFileSync(tmp, `${JSON.stringify({ url: `http://${clientHost(options.host)}:${boundPort}`, token })}\n`, {
+                mode: 0o600,
+            });
             chmodSync(tmp, 0o600); // an existing file keeps its old mode on rewrite — pin it
             renameSync(tmp, path);
             log.info(`[fastagent] session control on /control/* (token in ${path})`);
-            // The serve binds ALL interfaces (containers require it), so /control/* is LAN-reachable
-            // with the bearer token as the only protection — the tunnel and deploy paths warn loudly,
-            // and the LAN path must not be the silent third way past the local trust story.
-            log.warn("[fastagent] the port binds all interfaces: /control/* is reachable on your LAN, protected only by " +
-                "the bearer token — firewall the port or wrap it for real exposure (docs: design §14)");
+            // The serve binds ALL interfaces by DEFAULT (containers require it), so /control/* is
+            // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths warn
+            // loudly, and the LAN path must not be the silent third way past the local trust story. A
+            // loopback bind closes exactly that reach, so it earns silence.
+            const bind = classifyBind(options.host);
+            if (bind !== "loopback") {
+                log.warn(`[fastagent] the port binds ${bind === "wildcard" ? "all interfaces" : `${options.host} (off this machine)`}: ` +
+                    "/control/* is reachable on your LAN, protected only by the bearer token — bind loopback " +
+                    "(--bind 127.0.0.1), firewall the port, or wrap it for real exposure (docs: design §14)");
+            }
             if (options.tunnel) {
                 // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC
                 // (beyond even the LAN reach the mount already warned about). The operator asked for the tunnel (webhooks), but must not DISCOVER the control
@@ -175,13 +183,55 @@ export function mountAgentcore(routes, options) {
     }
     return { ...routes, ...mounted };
 }
+/**
+ * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
+ * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
+ * `127.0.0.2` bind, loopback though it is — would leave the tunnel up and 502ing every request.
+ * Checked BEFORE the bind (the flag alone pre-spawn in `dev`, again once config is loaded, since
+ * `http.host` can carry the address), so the failure is clean rather than a live-but-broken public URL.
+ * `source` decides the exit code, per fail.ts: a flag COMBINATION is a usage error (2), a value that
+ * came from config is broken runtime configuration (1).
+ */
+export function assertTunnelBindable(host, tunnel, source) {
+    if (!tunnel || answersLocalhost(host))
+        return;
+    // Name the source, not just the exit code: under `config` there is no `--bind` to change and no flag
+    // to drop, so flag-only wording would send the reader looking for something they never typed.
+    const fix = source === "flag"
+        ? "bind 0.0.0.0 (or 127.0.0.1), or drop --tunnel"
+        : "set http.host to 0.0.0.0 (or 127.0.0.1) in fastagent.config.*, override it with --bind, or drop --tunnel";
+    const message = `--tunnel reaches the serve by dialing localhost, which the bind address ${host} does not answer — ${fix}`;
+    if (source === "flag")
+        failUsage(message);
+    failStartup(new Error(message));
+}
+/**
+ * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
+ * ONE function because they are one message — they were two, and `--bind` updated the first while the
+ * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
+ * neither can be changed without the other in view, and the address has a single derivation.
+ *
+ * A wildcard bind is every interface, and naming one address there would understate it — but the curl
+ * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ */
+export function readyAddressLines(host, boundPort, builtinInvoke) {
+    const dial = `${clientHost(host)}:${boundPort}`;
+    const lines = [
+        `[fastagent] http host on ${classifyBind(host) === "wildcard" ? `:${boundPort} (all interfaces)` : bindLabel(host, boundPort)}`,
+    ];
+    if (builtinInvoke) {
+        lines.push(`[fastagent] try it: curl -s ${dial}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`);
+    }
+    return lines;
+}
 /**
  * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
  * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
- * the sole clean-shutdown command.
+ * the sole clean-shutdown command. `host` unset binds all interfaces.
  */
-export function serve(surface, port, onListening) {
-    const hosted = serveNode(router(surface.routes), { port });
+export function serve(surface, bind, onListening) {
+    const { port, host } = bind;
+    const hosted = serveNode(router(surface.routes), { port, host });
     const abort = new AbortController();
     let stopping = false;
     const stop = (exitCode) => {
@@ -236,14 +286,12 @@ export function serve(surface, port, onListening) {
                 port: boundPort,
                 routeChannels: surface.routeChannels,
             });
-            log.info(`[fastagent] http host on :${boundPort}`);
+            for (const line of readyAddressLines(host, boundPort, surface.builtinInvoke))
+                log.info(line);
             log.info(`[fastagent] routes: ${Object.keys(surface.routes).join(", ") || "(none)"}`);
             if (surface.longConnections.length > 0) {
                 log.info(`[fastagent] long connections: ${surface.longConnections.map((connection) => connection.name).join(", ")}`);
             }
-            if (surface.builtinInvoke) {
-                log.info(`[fastagent] try it: curl -s localhost:${boundPort}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`);
-            }
             onListening?.(boundPort);
         }
         catch (error) {
@@ -254,9 +302,15 @@ export function serve(surface, port, onListening) {
             failStartup(error);
         }
     }, (error) => {
-        if (error.code === "EADDRINUSE")
-            failStartup(new Error(`port ${port} is already in use; choose another with --port`));
-        failStartup(new Error(`cannot bind http channel on :${port}: ${error.message}`));
+        if (error.code === "EADDRINUSE") {
+            // With a bind address the port is only taken ON THAT interface, so moving the bind is as valid
+            // a fix as moving the port.
+            failStartup(new Error(`${bindLabel(host, port)} is already in use; choose another with ` +
+                `--port${classifyBind(host) === "wildcard" ? "" : " or --bind"}`));
+        }
+        // Through `bindLabel`, like every other message about a bind: hand-concatenating gives `:::8787`
+        // for an IPv6 bind and a bare `:8787` for the wildcard, which reads as an explicit bind of nothing.
+        failStartup(new Error(`cannot bind http channel on ${bindLabel(host, port)}: ${error.message}`));
     });
 }
 /** Start a Cloudflare tunnel for route channels only. */

package/dist/cli/shared.d.ts

@@ -20,6 +20,12 @@ export declare function isInteractive(): boolean;
  * bad `PORT` env is broken runtime configuration (1).
  */
 export declare function parsePort(value: string | undefined, source: string, from: "flag" | "env"): number | undefined;
+/**
+ * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to
+ * config, then all interfaces). An unbindable string is a USAGE error (2) — caught here rather than as
+ * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
+ */
+export declare function parseBind(value: string | undefined): string | undefined;
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
 export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
 /**

package/dist/cli/shared.js

@@ -14,6 +14,7 @@ import { createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses } fr
 import { formatAuthReport } from "./auth-view.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
+import { bindAddress, isBindAddress } from "../bind.js";
 import { failStartup, failUsage } from "./fail.js";
 /**
  * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
@@ -56,6 +57,19 @@ export function parsePort(value, source, from) {
     }
     return Number(trimmed);
 }
+/**
+ * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to
+ * config, then all interfaces). An unbindable string is a USAGE error (2) — caught here rather than as
+ * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
+ */
+export function parseBind(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    if (!isBindAddress(trimmed))
+        failUsage(`invalid --bind "${value}": must be an IP address or "localhost"`);
+    return bindAddress(trimmed); // a name never travels past this point — see bind.ts
+}
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
 export async function reportAuth(modelSpec, authPath) {
     const provider = providerOf(modelSpec);