@desplega.ai/agent-swarm 2.7.0 → 2.7.1

package/src/be/onboarding.ts

@@ -2,7 +2,13 @@ import { telemetry } from "../telemetry";
 import { ProviderNameSchema } from "../types";
 import { getCurrentRequestUserId } from "../utils/request-auth-context";
 import { z } from "../utils/zod-openapi";
-import { getDbClient, getSwarmConfigs, getTaskById, upsertSwarmConfig } from "./db";
+import {
+  deleteSwarmConfigByKey,
+  getDbClient,
+  getSwarmConfigs,
+  getTaskById,
+  upsertSwarmConfig,
+} from "./db";
 import { validateConfigValue } from "./swarm-config-guard";
 
 const ONBOARDING_CONFIG_KEY = "onboarding_state";
@@ -14,6 +20,7 @@ export const OnboardingStepIdSchema = z.enum([
   "agents",
   "memory",
   "integrations",
+  "files",
   "first_task",
 ]);
 export type OnboardingStepId = z.infer<typeof OnboardingStepIdSchema>;
@@ -54,6 +61,19 @@ export const OnboardingMemoryPresetSchema = z.enum([
   "custom",
   "existing",
 ]);
+/**
+ * Where the embeddings endpoint runs: `local` (this server or its private
+ * network), the hosted preset whose host it calls, or `custom` (another host).
+ */
+export const OnboardingMemoryProviderSchema = z.enum([
+  "local",
+  "openai",
+  "openrouter",
+  "vercel",
+  "azure",
+  "custom",
+]);
+export type OnboardingMemoryProvider = z.infer<typeof OnboardingMemoryProviderSchema>;
 export const OnboardingIntegrationMethodSchema = z.enum([
   "slack",
   "github",
@@ -62,6 +82,8 @@ export const OnboardingIntegrationMethodSchema = z.enum([
   "linear_oauth",
   "jira_oauth",
 ]);
+/** `created`: the Files step registered a new agent-fs account. `connected`: it reused one. */
+export const OnboardingFilesMethodSchema = z.enum(["created", "connected"]);
 export const OnboardingFirstTaskMethodSchema = z.enum(["suggestion", "free_form"]);
 export const OnboardingStepMethodSchema = z.union([
   OnboardingConnectMethodSchema,
@@ -70,6 +92,7 @@ export const OnboardingStepMethodSchema = z.union([
   OnboardingAgentsMethodSchema,
   OnboardingMemoryPresetSchema,
   OnboardingIntegrationMethodSchema,
+  OnboardingFilesMethodSchema,
   OnboardingFirstTaskMethodSchema,
 ]);
 export type OnboardingStepMethod = z.infer<typeof OnboardingStepMethodSchema>;
@@ -98,6 +121,7 @@ const OnboardingMemoryStepStateSchema = onboardingStepStateSchema(OnboardingMemo
 const OnboardingIntegrationStepStateSchema = onboardingStepStateSchema(
   OnboardingIntegrationMethodSchema,
 );
+const OnboardingFilesStepStateSchema = onboardingStepStateSchema(OnboardingFilesMethodSchema);
 const OnboardingFirstTaskStepStateSchema = onboardingStepStateSchema(
   OnboardingFirstTaskMethodSchema,
 );
@@ -118,6 +142,7 @@ export const OnboardingStateSchema = z.object({
     agents: OnboardingAgentsStepStateSchema,
     memory: OnboardingMemoryStepStateSchema,
     integrations: OnboardingIntegrationStepStateSchema,
+    files: OnboardingFilesStepStateSchema,
     first_task: OnboardingFirstTaskStepStateSchema,
   }),
 });
@@ -139,6 +164,21 @@ export const OnboardingSignalsSchema = z.object({
   embeddings: z.object({
     configured: z.boolean(),
     dimensions: z.number().int().positive(),
+    /** The embedding model memory search uses. Null while it is off. */
+    model: z.string().nullable(),
+    /**
+     * The endpoint runs on this server or its private network (loopback, a
+     * private address, or a single-label host such as `tei`). False while off.
+     */
+    local: z.boolean(),
+    /** Where the endpoint runs, from its host only (never the URL). Null while off. */
+    provider: OnboardingMemoryProviderSchema.nullable(),
+    /**
+     * The local setup of the deployment environment, also while a stored
+     * hosted setup replaces it, so `/setup` can offer it again: the model of
+     * its local endpoint. Null when the environment has no local endpoint.
+     */
+    localDefault: z.object({ model: z.string() }).nullable(),
   }),
   integrations: z.object({
     slack: z.boolean(),
@@ -153,6 +193,8 @@ export const OnboardingSignalsSchema = z.object({
     workersOnline: z.number().int().nonnegative(),
   }),
   firstTask: z.object({ id: z.string(), status: z.string() }).nullable(),
+  /** The Files step applies: Comb is on, so the browser can create an agent-fs account. */
+  files: z.object({ enabled: z.boolean() }),
 });
 export type OnboardingSignals = z.infer<typeof OnboardingSignalsSchema>;
 
@@ -198,10 +240,17 @@ export const OnboardingActionSchema = z.union([
       method: OnboardingIntegrationMethodSchema,
     })
     .strict(),
+  z
+    .object({
+      action: z.literal("complete"),
+      step: z.literal("files"),
+      method: OnboardingFilesMethodSchema,
+    })
+    .strict(),
   z
     .object({
       action: z.literal("skip"),
-      step: z.enum(["name", "ai", "agents", "memory", "integrations", "first_task"]),
+      step: z.enum(["name", "ai", "agents", "memory", "integrations", "files", "first_task"]),
     })
     .strict(),
   z
@@ -243,8 +292,18 @@ export const OnboardingMemoryRequestSchema = z
     model: z.string().trim().min(1).optional(),
     apiKey: z.string().min(1).optional(),
     reuseKey: z.enum(["OPENAI_API_KEY", "OPENROUTER_API_KEY"]).optional(),
+    /**
+     * With preset `existing`: test the setup of the deployment environment,
+     * and when it works, delete the stored embeddings config so that setup
+     * applies again. A failed test changes no config.
+     */
+    restoreDefault: z.boolean().optional(),
   })
-  .strict();
+  .strict()
+  .refine((body) => !body.restoreDefault || body.preset === "existing", {
+    message: "restoreDefault needs preset existing",
+    path: ["restoreDefault"],
+  });
 export type OnboardingMemoryRequest = z.infer<typeof OnboardingMemoryRequestSchema>;
 
 export const OnboardingMemoryResponseSchema = z.object({
@@ -320,6 +379,7 @@ function freshState(now: string, autoCompleted: boolean): OnboardingState {
       agents: emptyStep(),
       memory: emptyStep(),
       integrations: emptyStep(),
+      files: emptyStep(),
       first_task: emptyStep(),
     },
   };
@@ -535,6 +595,20 @@ function deriveState(
   return changed;
 }
 
+/**
+ * The response view of the state. Without Comb the Files step cannot run, so a
+ * stored `todo` reads as `skipped`. Response only: never persisted and never a
+ * `step_skipped` event, so installs without Comb send no funnel noise and the
+ * step comes back as `todo` once Comb is turned on.
+ */
+function presentState(state: OnboardingState, signals: OnboardingSignals): OnboardingState {
+  if (signals.files.enabled || state.steps.files.status !== "todo") return state;
+  return {
+    ...state,
+    steps: { ...state.steps, files: { ...state.steps.files, status: "skipped" } },
+  };
+}
+
 export class OnboardingTaskNotFoundError extends Error {}
 
 async function applyAction(
@@ -612,7 +686,8 @@ export async function readOrUpdateOnboarding(
     const read = await client.transaction(async () => await loadAndDerive(loadSignals, []), {
       readOnly: true,
     });
-    if (!read.dirty) return { state: read.state, signals: read.signals };
+    if (!read.dirty)
+      return { state: presentState(read.state, read.signals), signals: read.signals };
   }
 
   return await client.transaction(async () => {
@@ -627,14 +702,43 @@ export async function readOrUpdateOnboarding(
     }
     if (dirty) await persistState(state);
     queueTelemetry(events);
-    return { state, signals };
+    return { state: presentState(state, signals), signals };
   });
 }
 
+/** The embeddings rows a memory probe writes or deletes. */
+export const EMBEDDING_PREFIX_KEYS = [
+  "EMBEDDING_QUERY_PREFIX",
+  "EMBEDDING_DOCUMENT_PREFIX",
+] as const;
+export const EMBEDDING_CONFIG_KEYS = [
+  "EMBEDDING_API_BASE_URL",
+  "EMBEDDING_MODEL",
+  "EMBEDDING_API_KEY",
+  ...EMBEDDING_PREFIX_KEYS,
+] as const;
+
+/**
+ * The config change of a passed memory probe:
+ * - `save`: store the tested endpoint. `prefixes` sets a task prefix to an
+ *   empty value (`""`), or deletes its stored row (`null`).
+ * - `restore`: delete the stored embeddings rows, so the deployment
+ *   environment applies again.
+ */
+export type MemoryConfigChange =
+  | {
+      kind: "save";
+      baseUrl: string;
+      model: string;
+      apiKey?: string;
+      prefixes: ReadonlyArray<{ key: (typeof EMBEDDING_PREFIX_KEYS)[number]; value: "" | null }>;
+    }
+  | { kind: "restore" };
+
 export async function updateOnboardingMemory(
   preset: OnboardingMemoryPreset,
   result: { ok: true } | { ok: false; errorClass: OnboardingErrorClass },
-  saveConfig?: { baseUrl: string; model: string; apiKey?: string },
+  change?: MemoryConfigChange,
 ): Promise<boolean> {
   return await getDbClient().transaction(async () => {
     const events: PendingTelemetry[] = [];
@@ -642,11 +746,11 @@ export async function updateOnboardingMemory(
     let dirty = loaded.dirty;
     const eventsForState = loaded.state.autoCompleted ? [] : events;
 
-    if (saveConfig) {
+    if (change?.kind === "save") {
       const configValues = [
-        ["EMBEDDING_API_BASE_URL", saveConfig.baseUrl],
-        ["EMBEDDING_MODEL", saveConfig.model],
-        ...(saveConfig.apiKey ? [["EMBEDDING_API_KEY", saveConfig.apiKey]] : []),
+        ["EMBEDDING_API_BASE_URL", change.baseUrl],
+        ["EMBEDDING_MODEL", change.model],
+        ...(change.apiKey ? [["EMBEDDING_API_KEY", change.apiKey]] : []),
       ] as const;
       for (const [key, value] of configValues) {
         const validationError = validateConfigValue(key, value);
@@ -655,17 +759,23 @@ export async function updateOnboardingMemory(
       await upsertSwarmConfig({
         scope: "global",
         key: "EMBEDDING_API_BASE_URL",
-        value: saveConfig.baseUrl,
+        value: change.baseUrl,
       });
-      await upsertSwarmConfig({ scope: "global", key: "EMBEDDING_MODEL", value: saveConfig.model });
-      if (saveConfig.apiKey) {
+      await upsertSwarmConfig({ scope: "global", key: "EMBEDDING_MODEL", value: change.model });
+      if (change.apiKey) {
         await upsertSwarmConfig({
           scope: "global",
           key: "EMBEDDING_API_KEY",
-          value: saveConfig.apiKey,
+          value: change.apiKey,
           isSecret: true,
         });
       }
+      for (const { key, value } of change.prefixes) {
+        if (value === null) await deleteSwarmConfigByKey("global", null, key);
+        else await upsertSwarmConfig({ scope: "global", key, value });
+      }
+    } else if (change?.kind === "restore") {
+      for (const key of EMBEDDING_CONFIG_KEYS) await deleteSwarmConfigByKey("global", null, key);
     }
 
     if (result.ok) {
@@ -676,7 +786,7 @@ export async function updateOnboardingMemory(
 
     if (dirty) await persistState(loaded.state);
     queueTelemetry(events);
-    return saveConfig !== undefined;
+    return change !== undefined;
   });
 }
 

package/src/be/rbac-roles.ts

@@ -38,6 +38,9 @@ export const BUILTIN_ROLES = [
       "favorite.write.own",
       "session.share",
       "session.presence",
+      "task.steer.own",
+      "comb.presence",
+      "fs.join.own",
     ],
   },
   {
@@ -46,7 +49,7 @@ export const BUILTIN_ROLES = [
     description: "Read-only: no task, approval or script writes.",
     isBuiltin: true,
     grantsAll: false,
-    verbs: ["favorite.write.own", "session.presence"],
+    verbs: ["favorite.write.own", "session.presence", "comb.presence", "fs.join.own"],
   },
 ] satisfies (BuiltinRoleDefinition & { isBuiltin: true })[];
 

package/src/be/scripts/embeddings.ts

@@ -81,7 +81,7 @@ function rowToScript(row: ScriptEmbeddingCandidateRow): ScriptRecord {
 export async function embedScript(script: ScriptRecord): Promise<void> {
   const text = scriptEmbeddingText(script);
   const provider = embeddingProvider();
-  const embedding = await provider.embed(text);
+  const embedding = await provider.embed(text, { kind: "document" });
   if (!embedding) return;
 
   if (embedding.length !== provider.dimensions) {
@@ -207,7 +207,7 @@ export async function searchScripts(args: {
   limit?: number;
 }): Promise<ScriptSearchResult[]> {
   const provider = embeddingProvider();
-  const queryEmbedding = await provider.embed(args.query);
+  const queryEmbedding = await provider.embed(args.query, { kind: "query" });
   if (!queryEmbedding) return lexicalFallback(args);
 
   const candidates = await candidateRows(args.scope, args.scopeId);

package/src/be/seed/agent-fs-provision.ts

@@ -8,6 +8,7 @@ import {
   getSwarmConfigs,
   upsertSwarmConfig,
 } from "../db";
+import { getUserGrant } from "../rbac-roles";
 import type { Seeder, SeedItem } from "./types";
 
 const KIND = "agent-fs-provision";
@@ -16,6 +17,10 @@ const PROVISION_VERSION = 1;
 const ORG_NAME = "swarm";
 const DRIVE_NAME = "shared";
 const PROVISION_HASH_KEY = "AGENT_FS_PROVISION_HASH";
+// Stored in place of the hash when invites failed transiently. upstreamHash() maps it to
+// null, so the next boot re-applies even when the org, drive and key rows already exist
+// (otherwise the adopt-current-state fallback below would mark the failed run as in sync).
+const PROVISION_RETRY_MARKER = "retry-pending";
 const API_KEY_CONFIG = "API_AGENT_FS_API_KEY";
 const LEGACY_SHARED_KEY_CONFIG = "AGENT_FS_API_KEY";
 
@@ -80,6 +85,7 @@ export const agentFsProvisionSeeder: Seeder<AgentFsSeedItem> = {
 
   async upstreamHash(): Promise<string | null> {
     const existingHash = await getConfigValue(PROVISION_HASH_KEY);
+    if (existingHash === PROVISION_RETRY_MARKER) return null;
     if (existingHash) return existingHash;
 
     const hasOrg = !!(await getConfigValue("AGENT_FS_DEFAULT_ORG_ID"));
@@ -113,16 +119,33 @@ async function provisionAgentFs(item: AgentFsSeedItem): Promise<void> {
     shared.orgId,
   );
 
+  let transientFailures = 0;
   for (const invite of item.invites) {
     const currentRole = currentRoles.get(invite.email.toLowerCase());
     if (currentRole && roleRank(currentRole) >= roleRank(invite.role)) continue;
-    await inviteToSharedOrg(item.apiUrl, shared.authHeaders, shared.orgId, invite);
+    const outcome = await inviteToSharedOrg(item.apiUrl, shared.authHeaders, shared.orgId, invite);
+    if (outcome === "transient-failure") transientFailures++;
   }
+  // "no-account" is not a failure to retry: agent-fs has no pending invites. The person's
+  // account is created later in the browser, by the /setup Files step or Comb's connect card,
+  // and both invite in the same flow. A transient failure (network, 5xx other than not-found,
+  // 401/403) must not store the hash, so the next boot re-runs the invites. The org and drive
+  // config rows were already written by ensureAgentFsSharedProvisioning above.
+  if (transientFailures > 0) {
+    await storeProvisionHash(PROVISION_RETRY_MARKER);
+    throw new Error(
+      `agent-fs invites failed for ${transientFailures} member(s); will retry on next boot`,
+    );
+  }
+
+  await storeProvisionHash(item.contentHash);
+}
 
+async function storeProvisionHash(value: string): Promise<void> {
   await upsertSwarmConfig({
     scope: "global",
     key: PROVISION_HASH_KEY,
-    value: item.contentHash,
+    value,
     isSecret: false,
     description: "Internal hash for agent-fs provisioning reconciliation",
   });
@@ -203,17 +226,31 @@ export async function ensureAgentFsSharedProvisioning(options?: {
   return { apiUrl, apiKey, orgId, driveId, authHeaders };
 }
 
+export type SharedOrgInviteResult = {
+  orgId: string;
+  invited: boolean;
+  status: "already_member" | "added" | "pending";
+  inviteId?: string;
+  expiresAt?: string;
+  acceptUrl?: string;
+};
+
 /**
  * Invite an external (non-agent) member into the shared org using the
  * API-owned bootstrap credentials. Powers `POST /api/fs/members/invite` so
  * callers holding the tenant API key (e.g. the cloud control plane's
  * Connect-to-Drive flow) never need the bootstrap key itself — it is
  * API-only and never served over HTTP.
+ *
+ * agent-fs (>= 0.18.9) adds an email that has an account directly
+ * (`status: "added"`) and answers an email without one with a pending invite
+ * (`status: "pending"`, plus `acceptUrl` when its app URL is configured).
+ * agent-fs sends no email, so the accept link is passed back to the caller.
  */
 export async function inviteEmailToSharedOrg(
   email: string,
   role: Role,
-): Promise<{ orgId: string; invited: boolean }> {
+): Promise<SharedOrgInviteResult> {
   const shared = await ensureAgentFsSharedProvisioning();
   const currentRoles = await getCurrentOrgMemberRoles(
     shared.apiUrl,
@@ -222,15 +259,31 @@ export async function inviteEmailToSharedOrg(
   );
   const currentRole = currentRoles.get(email.trim().toLowerCase());
   if (currentRole && roleRank(currentRole) >= roleRank(role)) {
-    return { orgId: shared.orgId, invited: false };
+    return { orgId: shared.orgId, invited: false, status: "already_member" };
   }
-  await agentFsRequest(shared.apiUrl, `/orgs/${encodeURIComponent(shared.orgId)}/members/invite`, {
+  const response = await agentFsRequest<{
+    status?: unknown;
+    inviteId?: unknown;
+    expiresAt?: unknown;
+    acceptUrl?: unknown;
+  }>(shared.apiUrl, `/orgs/${encodeURIComponent(shared.orgId)}/members/invite`, {
     method: "POST",
     headers: shared.authHeaders,
     body: { email: email.trim(), role },
     allowConflict: true,
   });
-  return { orgId: shared.orgId, invited: true };
+  // Older agent-fs answers a direct add with a bare `{ ok: true }`.
+  if (response.status !== "pending") {
+    return { orgId: shared.orgId, invited: true, status: "added" };
+  }
+  return {
+    orgId: shared.orgId,
+    invited: true,
+    status: "pending",
+    ...(typeof response.inviteId === "string" ? { inviteId: response.inviteId } : {}),
+    ...(typeof response.expiresAt === "string" ? { expiresAt: response.expiresAt } : {}),
+    ...(typeof response.acceptUrl === "string" ? { acceptUrl: response.acceptUrl } : {}),
+  };
 }
 
 export async function ensureAgentFsCredentialsForAgent(agentId: string): Promise<{
@@ -396,7 +449,7 @@ async function inviteToSharedOrg(
   headers: Record<string, string>,
   orgId: string,
   invite: InviteTarget,
-): Promise<void> {
+): Promise<"invited" | "no-account" | "transient-failure"> {
   try {
     await agentFsRequest(apiUrl, `/orgs/${encodeURIComponent(orgId)}/members/invite`, {
       method: "POST",
@@ -404,6 +457,7 @@ async function inviteToSharedOrg(
       body: invite,
       allowConflict: true,
     });
+    return "invited";
   } catch (error) {
     console.warn(
       scrubSecrets(
@@ -412,6 +466,12 @@ async function inviteToSharedOrg(
         }`,
       ),
     );
+    // agent-fs answers an unregistered invitee with HTTP 500 "User with email ... not found".
+    const noAccount =
+      error instanceof AgentFsRequestError &&
+      error.status === 500 &&
+      /not found/i.test(error.message);
+    return noAccount ? "no-account" : "transient-failure";
   }
 }
 
@@ -499,18 +559,19 @@ async function resolveInviteTargets(): Promise<InviteTarget[]> {
   const targets = new Map<string, InviteTarget>();
 
   for (const user of await getAllUsers()) {
-    if (!user.email) continue;
-    const role = isExplicitViewerRole(user.role) ? "viewer" : "editor";
-    targets.set(user.email.toLowerCase(), { email: user.email, role });
+    const email = user.email?.trim();
+    if (!email) continue;
+    // Only active users get a seat: invited and suspended users cannot sign in yet.
+    if ((user.status ?? "active") !== "active") continue;
+    // Follow the RBAC grant, not the free-text profile role, so an RBAC Viewer stays a viewer.
+    const grant = await getUserGrant(user.id);
+    const role: Role = grant.grantsAll || grant.verbs.has("task.fs.mutate") ? "editor" : "viewer";
+    targets.set(email.toLowerCase(), { email, role });
   }
 
   return [...targets.values()].sort((a, b) => a.email.localeCompare(b.email));
 }
 
-function isExplicitViewerRole(role: string | undefined): boolean {
-  return /\b(viewer|read[-\s]?only|guest)\b/i.test(role ?? "");
-}
-
 async function provisionHashFromCurrentState(): Promise<string> {
   return provisionHash({
     apiUrl: await resolveApiUrl(),

package/src/be/swarm-config-guard.ts

@@ -410,6 +410,8 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
       value,
       "Invalid AGENT_FS_PUBLIC_URL (must be an http(s) URL with no query string or fragment, e.g. https://agent-fs.example.com. Leave blank to use AGENT_FS_API_URL)",
     ),
+  // Where people-facing file links point. Blank keeps the automatic choice.
+  ...enumValidator("AGENT_FS_LINK_TARGET", ["dashboard", "live", ""]),
   HARNESS_PROVIDER: (value) => {
     const parsed = ProviderNameSchema.safeParse(value);
     if (parsed.success) return null;
@@ -520,6 +522,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "DB_RETENTION_DRY_RUN",
     "MODEL_AUTO_UPGRADE",
     "COMB_ENABLED",
+    "AGENT_FS_PROXY",
   ]),
   ...enumValidator("SLACK_MODE", ["socket", "http"]),
   ...enumValidator("SLACK_THREAD_STEERING", ["off", "lead", "all"]),

package/src/cli.tsx

@@ -41,6 +41,7 @@ interface ParsedArgs {
   maxConcurrentTasks: string | undefined;
   pullPolicy: string | undefined;
   containerEngine: string | undefined;
+  noAgentFs: boolean;
   open: boolean;
   showHelp: boolean;
   dbPath: string;
@@ -63,6 +64,7 @@ function parseArgs(args: string[]): ParsedArgs {
   let maxConcurrentTasks: string | undefined;
   let pullPolicy: string | undefined;
   let containerEngine: string | undefined;
+  let noAgentFs = false;
   let open = false;
   let showHelp = false;
   let dbPath = "";
@@ -122,6 +124,8 @@ function parseArgs(args: string[]): ParsedArgs {
       if (value && !value.startsWith("-")) i++;
     } else if (arg?.startsWith("--container-engine=")) {
       containerEngine = arg.slice("--container-engine=".length);
+    } else if (arg === "--no-agent-fs") {
+      noAgentFs = true;
     } else if (arg === "--open") {
       open = true;
     } else if (arg === "--help" || arg === "-h") {
@@ -149,6 +153,7 @@ function parseArgs(args: string[]): ParsedArgs {
     maxConcurrentTasks,
     pullPolicy,
     containerEngine,
+    noAgentFs,
     open,
     showHelp,
     dbPath,
@@ -185,6 +190,7 @@ const COMMAND_HELP: Record<
       "  --max-concurrent-tasks <n>  Tasks per agent (1-100; default: lead 2, worker 1)",
       "  --pull-policy <policy> Pull policy: always, missing, never (default: always)",
       "  --container-engine <engine>  auto, docker, podman (default: $AGENT_SWARM_CONTAINER_ENGINE, else auto; auto prefers Docker)",
+      "  --no-agent-fs          With --yes: skip the bundled agent-fs (files, Comb) and TEI (memory embeddings)",
       "  -h, --help             Show this help",
     ].join("\n"),
     examples: [
@@ -192,6 +198,7 @@ const COMMAND_HELP: Record<
       `  ${binName} onboard --dry-run`,
       `  ${binName} onboard --yes --preset=full`,
       `  ${binName} onboard --yes --preset=dev`,
+      `  ${binName} onboard --yes --preset=solo --no-agent-fs`,
       `  ${binName} onboard --container-engine=podman`,
       `  ANTHROPIC_API_KEY=sk-... ${binName} onboard --yes --preset=solo`,
     ].join("\n"),
@@ -693,6 +700,7 @@ function App({ args }: { args: ParsedArgs }) {
     maxConcurrentTasks,
     pullPolicy,
     containerEngine,
+    noAgentFs,
   } = args;
 
   switch (command) {
@@ -707,6 +715,7 @@ function App({ args }: { args: ParsedArgs }) {
             maxConcurrentTasks,
             pullPolicy,
             containerEngine,
+            noAgentFs,
           }}
         />
       );

package/src/comb/config.ts

@@ -2,6 +2,8 @@ import {
   getAgentFsDefaultDriveId,
   getAgentFsDefaultOrgId,
   getAgentFsLiveUrl,
+  getPublicMcpBaseUrl,
+  isAgentFsProxyEnabled,
   isCombEnabled,
 } from "../utils/constants";
 
@@ -27,9 +29,12 @@ function trimUrl(value: string | undefined): string | null {
  */
 export function getCombConfig(): CombConfig {
   const internalUrl = trimUrl(process.env.AGENT_FS_API_URL);
+  // With the proxy on, the browser reaches agent-fs through the API itself.
+  const browserDefault =
+    isAgentFsProxyEnabled() && internalUrl ? `${getPublicMcpBaseUrl()}/agentfs` : internalUrl;
   return {
     enabled: isCombEnabled(),
-    apiUrl: trimUrl(process.env.AGENT_FS_PUBLIC_URL) ?? internalUrl,
+    apiUrl: trimUrl(process.env.AGENT_FS_PUBLIC_URL) ?? browserDefault,
     liveUrl: getAgentFsLiveUrl(),
     orgId: getAgentFsDefaultOrgId() ?? null,
     driveId: getAgentFsDefaultDriveId() ?? null,

package/src/commands/onboard/agent-fs-version.ts

@@ -0,0 +1,5 @@
+/**
+ * agent-fs image tag bundled by `agent-swarm onboard --yes`.
+ * `bun run bump:agent-fs` rewrites it together with the other pins.
+ */
+export const AGENT_FS_VERSION = "0.18.9";