@desplega.ai/agent-swarm 2.7.2 → 2.7.3

package/src/tests/install-sh-bind.test.ts

@@ -0,0 +1,242 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { type DeployStubs, makeDeployStubs } from "./deploy-stubs";
+import { CHILD_PROCESS_TEST_BUDGET_MS, runChild } from "./test-proc";
+
+// `install.sh --bind` runs for real against a fake docker that publishes ports
+// the way Compose does (fixtures/deploy-stubs), so these tests check where the
+// running stack listens, not what the script prints.
+
+const INSTALL_SH = resolve(import.meta.dir, "../../install.sh");
+const BOUND = "Publishing ports on 127.0.0.1 only";
+// What the onboard compose generator puts before each published port.
+// biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
+const BIND_PREFIX = "${AGENT_SWARM_BIND_ADDRESS:+${AGENT_SWARM_BIND_ADDRESS:-}:}";
+
+let dir: string;
+let installDir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "install-sh-bind-"));
+  installDir = join(dir, "agent-swarm");
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+// An install from before AGENT_SWARM_BIND_ADDRESS, with `ports` as given.
+async function existingInstall(ports: string) {
+  await Bun.write(
+    join(installDir, "docker-compose.yml"),
+    `services:\n  swarm-api:\n    image: ghcr.io/desplega-ai/agent-swarm:latest\n    ports:\n      - ${ports}\n    volumes:\n      - swarm_data:/app/data\n`,
+  );
+  await Bun.write(join(installDir, ".env"), "API_KEY=k\nMCP_BASE_URL=http://localhost:3013\n");
+}
+
+interface InstallOptions {
+  env?: Record<string, string>;
+  args?: string[];
+  /** Runs against the fake docker before install.sh, e.g. to leave a network behind. */
+  before?: (stubs: DeployStubs) => Promise<void>;
+}
+
+async function install({ env = {}, args = ["--no-tunnel"], before }: InstallOptions = {}) {
+  const stubs = await makeDeployStubs(dir, env);
+  await before?.(stubs);
+  const r = await runChild(
+    ["bash", INSTALL_SH, "--dir", installDir, ...args, "--bind", "127.0.0.1"],
+    {
+      env: stubs.env,
+    },
+  );
+  return { ...r, out: r.stdout + r.stderr, stubs };
+}
+
+const NETWORK = "agent-swarm_default";
+const NETWORK_OPTION = 'com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"';
+const override = () => readFile(join(installDir, "docker-compose.override.yml"), "utf8");
+
+describe("install.sh --bind", () => {
+  test(
+    "rewrites an existing literal 3013:3013 mapping before starting the stack",
+    async () => {
+      await existingInstall('"3013:3013"');
+      // The earlier install's network, without a default address. Compose reuses it.
+      const r = await install({ before: (stubs) => stubs.network(NETWORK, "") });
+      expect(r.exitCode).toBe(0);
+      expect(await r.stubs.ups()).toEqual([`${NETWORK} 0.0.0.0`]);
+      expect(await r.stubs.history()).toEqual(["127.0.0.1:3013->3013/tcp"]);
+      const compose = await readFile(join(installDir, "docker-compose.yml"), "utf8");
+      expect(compose).toContain(`- "${BIND_PREFIX}3013:3013"`);
+      expect(compose).toContain("- swarm_data:/app/data");
+      expect(await readFile(join(installDir, "docker-compose.yml.bak"), "utf8")).toContain(
+        '- "3013:3013"',
+      );
+      expect(await readFile(join(installDir, ".env"), "utf8")).toContain(
+        "AGENT_SWARM_BIND_ADDRESS=127.0.0.1\n",
+      );
+      expect(r.out).toContain(BOUND);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "fails without starting the stack when a mapping names another host address",
+    async () => {
+      await existingInstall('"0.0.0.0:3013:3013"');
+      const r = await install();
+      expect(r.exitCode).not.toBe(0);
+      expect(r.out).toContain("publishes ports that ignore --bind: 0.0.0.0:3013:3013");
+      expect(r.out).not.toContain(BOUND);
+      expect(await r.stubs.history()).toEqual([]);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "stops the stack and fails when a running port still listens elsewhere",
+    async () => {
+      await existingInstall(`"${BIND_PREFIX}3013:3013"`);
+      await Bun.write(
+        join(installDir, "docker-compose.override.yml"),
+        'services:\n  swarm-api:\n    ports:\n      - "0.0.0.0:3014:3014"\n',
+      );
+      const r = await install();
+      expect(r.exitCode).not.toBe(0);
+      expect(r.out).toContain(
+        "ports are still published outside 127.0.0.1 (0.0.0.0:3014->3014/tcp",
+      );
+      expect(await override()).toContain(`ports:\n      - "0.0.0.0:3014:3014"\nnetworks:`);
+      expect(r.out).not.toContain(BOUND);
+      expect(await r.stubs.ports()).toEqual([]);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "the first docker compose up, inside a CLI that ignores the bind address, already binds there",
+    async () => {
+      const r = await install();
+      expect(r.exitCode).toBe(0);
+      // onboard's own `up` comes first; it must find the network default in place.
+      expect((await r.stubs.ups())[0]).toBe(`${NETWORK} 127.0.0.1`);
+      const history = await r.stubs.history();
+      expect(history.length).toBeGreaterThan(0);
+      expect(history.filter((p) => !p.startsWith("127.0.0.1:"))).toEqual([]);
+      expect(await override()).toContain(
+        `networks:\n  default:\n    driver_opts:\n      ${NETWORK_OPTION}\n`,
+      );
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "the override keeps the network default next to the public URL",
+    async () => {
+      const r = await install({ args: ["--public-url", "https://swarm.example.com"] });
+      expect(r.exitCode).toBe(0);
+      const text = await override();
+      expect(text).toContain(NETWORK_OPTION);
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
+      expect(text).toContain("- PUBLIC_MCP_BASE_URL=${PUBLIC_MCP_BASE_URL:-}");
+      expect(text.match(/^# Written by install\.sh/gm)).toHaveLength(1);
+      expect((await r.stubs.history()).filter((p) => !p.startsWith("127.0.0.1:"))).toEqual([]);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "a re-run with another address rewrites the network default",
+    async () => {
+      await existingInstall('"3013:3013"');
+      await Bun.write(
+        join(installDir, "docker-compose.override.yml"),
+        `networks:\n  default:\n    driver_opts:\n      com.docker.network.bridge.host_binding_ipv4: "10.0.0.5"\n`,
+      );
+      const r = await install();
+      expect(r.exitCode).toBe(0);
+      expect(await override()).toContain(NETWORK_OPTION);
+      expect(await override()).not.toContain("10.0.0.5");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "a fresh install refuses a network an earlier install left without the default",
+    async () => {
+      const r = await install({ before: (stubs) => stubs.network(NETWORK, "") });
+      expect(r.exitCode).not.toBe(0);
+      expect(r.out).toContain(
+        `Docker network ${NETWORK} from an earlier install exists and publishes ports on every interface`,
+      );
+      expect(await r.stubs.history()).toEqual([]);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "fails before starting anything when a compose.override.yml would hide the network default",
+    async () => {
+      await Bun.write(join(installDir, "compose.override.yml"), "services: {}\n");
+      const r = await install();
+      expect(r.exitCode).not.toBe(0);
+      expect(r.out).toContain("compose.override.yml hides docker-compose.override.yml");
+      expect(await r.stubs.history()).toEqual([]);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "a fresh install with a CLI that ignores the bind address ends on loopback",
+    async () => {
+      const r = await install();
+      expect(r.exitCode).toBe(0);
+      expect(await r.stubs.ports()).toEqual([
+        "127.0.0.1:3013->3013/tcp",
+        "127.0.0.1:3201->3000/tcp",
+      ]);
+      expect(r.out).toContain("Rewriting 2 port mapping(s)");
+      expect(r.out).toContain(BOUND);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "stops the stack when onboard fails after starting it",
+    async () => {
+      const r = await install({ env: { FAKE_ONBOARD_FAIL: "1" } });
+      expect(r.exitCode).not.toBe(0);
+      expect(await r.stubs.history()).toContain("127.0.0.1:3013->3013/tcp");
+      expect(await r.stubs.ports()).toEqual([]);
+      expect(r.out).not.toContain(BOUND);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "stops the stack when the installer is terminated after onboard starts it",
+    async () => {
+      const r = await install({ env: { FAKE_ONBOARD_FAIL: "term" } });
+      expect(r.exitCode).not.toBe(0);
+      expect(await r.stubs.history()).toContain("127.0.0.1:3013->3013/tcp");
+      expect(await r.stubs.ports()).toEqual([]);
+      expect(r.out).not.toContain(BOUND);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "stops the stack when the generated compose file names another host address",
+    async () => {
+      const r = await install({ env: { FAKE_ONBOARD_API_PORT: "0.0.0.0:3013:3013" } });
+      expect(r.exitCode).not.toBe(0);
+      expect(r.out).toContain("publishes ports that ignore --bind: 0.0.0.0:3013:3013");
+      expect(await r.stubs.history()).toContain("0.0.0.0:3013->3013/tcp");
+      expect(await r.stubs.ports()).toEqual([]);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+});

package/src/tests/install-sh-tunnel.test.ts

@@ -25,6 +25,8 @@ async function dryRun(args: string[] = [], env: Record<string, string> = {}, dot
   const base: Record<string, string | undefined> = { ...process.env };
   delete base.AGENT_SWARM_TUNNEL;
   delete base.AGENT_SWARM_PRESET;
+  delete base.AGENT_SWARM_PUBLIC_URL;
+  delete base.AGENT_SWARM_BIND_ADDRESS;
   const r = await runChild(["bash", INSTALL_SH, "--dry-run", "--dir", dir, ...args], {
     env: { ...base, ...env },
   });
@@ -123,3 +125,90 @@ describe("install.sh tunnel default", () => {
     CHILD_PROCESS_TEST_BUDGET_MS,
   );
 });
+
+async function dryRunFails(args: string[]) {
+  const r = await runChild(["bash", INSTALL_SH, "--dry-run", "--dir", dir, ...args]);
+  expect(r.exitCode).not.toBe(0);
+  return r.stdout + r.stderr;
+}
+
+describe("install.sh public URL and bind address", () => {
+  const LINK = "/setup?apiUrl=https%3A%2F%2Fswarm.example.com&apiKey=";
+
+  test(
+    "--public-url turns the tunnel off, passes the URL to the API and uses it in the link",
+    async () => {
+      const out = await dryRun(["--public-url", "https://swarm.example.com/"]);
+      expect(out).not.toContain(TUNNEL_LINE);
+      expect(out).toContain("set AGENT_SWARM_TUNNEL=0");
+      expect(out).toContain("set PUBLIC_MCP_BASE_URL=https://swarm.example.com in");
+      expect(out).toContain("write docker-compose.override.yml");
+      expect(out).toContain("up -d swarm-api agent-fs");
+      expect(out).toContain(LINK);
+      expect(out).toContain("Public API: https://swarm.example.com\n");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "an own-domain PUBLIC_MCP_BASE_URL in .env reaches the API and the link",
+    async () => {
+      const out = await dryRun([], {}, "PUBLIC_MCP_BASE_URL=https://swarm.example.com\n");
+      expect(out).not.toContain(TUNNEL_LINE);
+      expect(out).toContain("write docker-compose.override.yml");
+      expect(out).toContain(LINK);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "--no-tunnel ignores a stale tunnel URL and links to localhost",
+    async () => {
+      const out = await dryRun(
+        ["--no-tunnel"],
+        {},
+        "PUBLIC_MCP_BASE_URL=https://abc.lt.desplega.ai\n",
+      );
+      expect(out).not.toContain("write docker-compose.override.yml");
+      expect(out).toContain("/setup?apiUrl=http%3A%2F%2Flocalhost%3A3013&apiKey=");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "--bind saves the address and plans the port check without claiming it",
+    async () => {
+      const out = await dryRun(["--no-tunnel", "--bind", "127.0.0.1"]);
+      expect(out).not.toContain("Publishing ports on 127.0.0.1 only");
+      expect(out).toContain("+ check that every published port listens on 127.0.0.1");
+      expect(out).toContain("set AGENT_SWARM_BIND_ADDRESS=127.0.0.1 in");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "--public-url wins over AGENT_SWARM_TUNNEL=1",
+    async () => {
+      const out = await dryRun(["--public-url", "https://swarm.example.com"], {
+        AGENT_SWARM_TUNNEL: "1",
+      });
+      expect(out).not.toContain(TUNNEL_LINE);
+      expect(out).toContain(LINK);
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "rejects a URL without a scheme, a conflicting --tunnel, and a non-IP bind",
+    async () => {
+      expect(await dryRunFails(["--public-url", "swarm.example.com"])).toContain(
+        "must start with http:// or https://",
+      );
+      expect(
+        await dryRunFails(["--tunnel", "--public-url", "https://swarm.example.com"]),
+      ).toContain("conflict");
+      expect(await dryRunFails(["--bind", "localhost"])).toContain("needs an IP address");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+});

package/src/tests/kv-storage.test.ts

@@ -17,6 +17,7 @@ import {
   sweepExpiredKvPrefix,
   upsertKv,
 } from "../be/db";
+import { runMcpOverflowSweep } from "../be/mcp-overflow-sweep";
 
 const TEST_DB_PATH = "./test-kv-storage.sqlite";
 
@@ -105,6 +106,33 @@ describe("kv-storage helpers", () => {
     expect((await getKv(NS, "live-spill"))?.value).toBe("new");
   });
 
+  test("the MCP overflow sweep removes expired spills of every agent", async () => {
+    const now = Date.now();
+    await upsertKv({
+      namespace: "mcp:overflow:agent-c",
+      key: "expired-c",
+      value: "x",
+      valueType: "string",
+      expiresAt: now - 1,
+    });
+    await upsertKv({
+      namespace: "mcp:overflow:agent-d",
+      key: "live-d",
+      value: "x",
+      valueType: "string",
+      expiresAt: now + 10_000,
+    });
+
+    expect(await runMcpOverflowSweep(now)).toBeGreaterThanOrEqual(1);
+    // Raw read: getKv deletes an expired row itself.
+    const expired = await getDbClient().get<{ key: string }>(
+      "SELECT key FROM kv_entries WHERE namespace = ? AND key = ?",
+      ["mcp:overflow:agent-c", "expired-c"],
+    );
+    expect(expired).toBeNull();
+    expect((await getKv("mcp:overflow:agent-d", "live-d"))?.value).toBe("x");
+  });
+
   test("prefix sweep removes expired entries across per-agent overflow namespaces", async () => {
     const now = Date.now();
     for (const [namespace, key, expiresAt] of [

package/src/tests/list-endpoint-slimming.test.ts

@@ -62,6 +62,7 @@ describe("list-endpoint slimming", () => {
       heartbeatMd: "H".repeat(500),
       setupScript: "echo hi",
       avatar: { type: "lucide", icon: "rocket", color: "#8b5cf6" },
+      slackIcon: { type: "emoji", emoji: ":owl:" },
     });
 
     const slim = (await getAllAgents({ slim: true })).find((a) => a.id === agent.id);
@@ -79,11 +80,13 @@ describe("list-endpoint slimming", () => {
     // full, or the agents list would silently show the default avatar while
     // the detail page shows the custom one.
     expect(slim?.avatar).toEqual({ type: "lucide", icon: "rocket", color: "#8b5cf6" });
+    expect(slim?.slackIcon).toEqual({ type: "emoji", emoji: ":owl:" });
 
     const full = (await getAllAgents()).find((a) => a.id === agent.id);
     expect(full?.claudeMd).toBe("C".repeat(500));
     expect(full?.setupScript).toBe("echo hi");
     expect(full?.avatar).toEqual({ type: "lucide", icon: "rocket", color: "#8b5cf6" });
+    expect(full?.slackIcon).toEqual({ type: "emoji", emoji: ":owl:" });
   });
 
   test("updateAgentProfile — avatar set/reset round-trip", async () => {

package/src/tests/list-total-cache.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { createListTotalCache } from "../http/list-total-cache";
+
+function counter(values: number[]) {
+  let calls = 0;
+  return {
+    compute: async () => values[Math.min(calls++, values.length - 1)]!,
+    calls: () => calls,
+  };
+}
+
+describe("list total cache", () => {
+  test("page 1 always counts; later pages reuse its count", async () => {
+    const cache = createListTotalCache();
+    const count = counter([10, 11, 12]);
+
+    expect(await cache.get({ q: "a" }, 0, count.compute)).toBe(10);
+    expect(await cache.get({ q: "a" }, 25, count.compute)).toBe(10);
+    expect(await cache.get({ q: "a" }, 50, count.compute)).toBe(10);
+    expect(count.calls()).toBe(1);
+
+    expect(await cache.get({ q: "a" }, undefined, count.compute)).toBe(11);
+    expect(await cache.get({ q: "a" }, 25, count.compute)).toBe(11);
+    expect(count.calls()).toBe(2);
+  });
+
+  test("a cold later page counts, so total is always set", async () => {
+    const cache = createListTotalCache();
+    const count = counter([7]);
+    expect(await cache.get({ q: "b" }, 25, count.compute)).toBe(7);
+    expect(await cache.get({ q: "b" }, 50, count.compute)).toBe(7);
+    expect(count.calls()).toBe(1);
+  });
+
+  test("filter sets are keyed independently of key order", async () => {
+    const cache = createListTotalCache();
+    const count = counter([1, 2]);
+    await cache.get({ status: "open", viewer: { userId: "u", scope: "all" } }, 0, count.compute);
+    expect(
+      await cache.get({ viewer: { scope: "all", userId: "u" }, status: "open" }, 25, count.compute),
+    ).toBe(1);
+    expect(await cache.get({ status: "done" }, 25, count.compute)).toBe(2);
+    expect(count.calls()).toBe(2);
+  });
+
+  test("an entry expires after the TTL", async () => {
+    const cache = createListTotalCache(1);
+    const count = counter([1, 2]);
+    await cache.get({}, 0, count.compute);
+    await Bun.sleep(5);
+    expect(await cache.get({}, 25, count.compute)).toBe(2);
+  });
+
+  test("a failed count is not cached", async () => {
+    const cache = createListTotalCache();
+    await expect(
+      cache.get({}, 0, async () => {
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+    expect(await cache.get({}, 25, async () => 3)).toBe(3);
+  });
+});

package/src/tests/mcp-overflow-sweep.test.ts

@@ -0,0 +1,84 @@
+import { afterAll, afterEach, beforeAll, describe, expect, spyOn, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, getDbClient, initDb, upsertKv } from "../be/db";
+import { startMcpOverflowSweep, stopMcpOverflowSweep } from "../be/mcp-overflow-sweep";
+
+const TEST_DB_PATH = "./test-mcp-overflow-sweep.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"])
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => undefined);
+}
+
+// Reads the raw row: getKv deletes an expired row itself, which would hide
+// whether the sweep ran.
+async function stored(namespace: string, key: string): Promise<boolean> {
+  const row = await getDbClient().get<{ key: string }>(
+    "SELECT key FROM kv_entries WHERE namespace = ? AND key = ?",
+    [namespace, key],
+  );
+  return row !== null;
+}
+
+async function spill(namespace: string, key: string, expiresAt: number): Promise<void> {
+  await upsertKv({ namespace, key, value: "x", valueType: "string", expiresAt });
+}
+
+describe("MCP overflow sweep lifecycle", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterEach(() => stopMcpOverflowSweep());
+
+  afterAll(async () => {
+    stopMcpOverflowSweep();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  test("start twice creates one interval, stop clears it, start after stop works", () => {
+    const set = spyOn(globalThis, "setInterval");
+    const clear = spyOn(globalThis, "clearInterval");
+    try {
+      startMcpOverflowSweep(60_000);
+      startMcpOverflowSweep(60_000);
+      expect(set).toHaveBeenCalledTimes(1);
+      const first = set.mock.results[0]?.value;
+
+      stopMcpOverflowSweep();
+      expect(clear).toHaveBeenCalledTimes(1);
+      expect(clear).toHaveBeenCalledWith(first);
+      stopMcpOverflowSweep();
+      expect(clear).toHaveBeenCalledTimes(1);
+
+      startMcpOverflowSweep(60_000);
+      expect(set).toHaveBeenCalledTimes(2);
+    } finally {
+      stopMcpOverflowSweep();
+      set.mockRestore();
+      clear.mockRestore();
+    }
+  });
+
+  test("a running sweep deletes expired spills on its tick and stops after stop", async () => {
+    const now = Date.now();
+    await spill("mcp:overflow:agent-a", "expired", now - 1);
+    await spill("mcp:overflow:agent-b", "live", now + 60_000);
+
+    expect(await stored("mcp:overflow:agent-a", "expired")).toBe(true);
+
+    startMcpOverflowSweep(5);
+    for (let i = 0; i < 100 && (await stored("mcp:overflow:agent-a", "expired")); i++) {
+      await Bun.sleep(5);
+    }
+    expect(await stored("mcp:overflow:agent-a", "expired")).toBe(false);
+    expect(await stored("mcp:overflow:agent-b", "live")).toBe(true);
+
+    stopMcpOverflowSweep();
+    await spill("mcp:overflow:agent-a", "after-stop", Date.now() - 1);
+    await Bun.sleep(30);
+    expect(await stored("mcp:overflow:agent-a", "after-stop")).toBe(true);
+  });
+});

package/src/tests/onboard-compose.test.ts

@@ -363,9 +363,23 @@ describe("generateCompose", () => {
 
   test("port allocation starts at 3201 and increments", () => {
     const yaml = generateCompose(devState);
-    expect(yaml).toContain('"3201:3000"');
-    expect(yaml).toContain('"3202:3000"');
-    expect(yaml).toContain('"3203:3000"');
+    expect(yaml).toContain(':}3201:3000"');
+    expect(yaml).toContain(':}3202:3000"');
+    expect(yaml).toContain(':}3203:3000"');
+  });
+
+  test("every published port takes its host address from AGENT_SWARM_BIND_ADDRESS", () => {
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
+    const prefix = '"${AGENT_SWARM_BIND_ADDRESS:+${AGENT_SWARM_BIND_ADDRESS:-}:}';
+    const yaml = generateCompose({ ...devState, bundleAgentFs: true });
+    const published = yaml.match(/^ {6}- "[^"]*:30(?:13|00)"$/gm) ?? [];
+    // swarm-api plus three agents; agent-fs and tei publish nothing.
+    expect(published).toHaveLength(4);
+    for (const line of published) {
+      // Blank or unset keeps Compose's default (every interface) without an unset-variable warning.
+      expect(line).toContain(prefix);
+    }
+    expect(yaml).toContain(`${prefix}3013:3013"`);
   });
 
   // ── API service has healthcheck ──

package/src/tests/onboard-env.test.ts

@@ -257,6 +257,19 @@ describe("generateEnv with the agent-fs bundle flag", () => {
   });
 });
 
+describe("generateEnv bind address forwarding", () => {
+  test("writes AGENT_SWARM_BIND_ADDRESS when set", () => {
+    const env = generateEnv(makeState({}), { AGENT_SWARM_BIND_ADDRESS: "127.0.0.1" });
+    expect(env).toContain("\nAGENT_SWARM_BIND_ADDRESS=127.0.0.1\n");
+  });
+
+  test("omits it when unset or blank", () => {
+    for (const source of [{}, { AGENT_SWARM_BIND_ADDRESS: " " }]) {
+      expect(generateEnv(makeState({}), source)).not.toContain("AGENT_SWARM_BIND_ADDRESS");
+    }
+  });
+});
+
 describe("generateEnv telemetry forwarding", () => {
   test("writes ANONYMIZED_TELEMETRY and DESPLEGA_TELEMETRY_ENV when set", () => {
     const env = generateEnv(makeState({}), {

package/src/tests/onboarding.test.ts

@@ -878,7 +878,7 @@ describe("onboarding state", () => {
     process.env.COMB_ENABLED = "true";
     process.env.AGENT_FS_API_URL = "http://agent-fs.example.test";
     await put({ action: "complete", step: "files", method: "connected" });
-    delete process.env.COMB_ENABLED;
+    process.env.COMB_ENABLED = "false";
     const body = (await (await request("/api/onboarding")).json()) as { state: OnboardingState };
     expect(body.state.steps.files).toMatchObject({ status: "done", method: "connected" });
   });

package/src/tests/preload.ts

@@ -33,6 +33,7 @@ for (const key of Object.keys(process.env)) {
       "APP_URL",
       "AGENT_FS_API_URL",
       "AGENT_FS_PROXY",
+      "AGENT_FS_PUBLIC_URL",
       "AGENT_FS_LIVE_URL",
       "AGENT_FS_LINK_TARGET",
       "AGENT_FS_DEFAULT_ORG_ID",