@desplega.ai/agent-swarm 2.6.0 → 2.7.1

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/seed-skills/index.ts

@@ -208,6 +208,12 @@ import stepRunningConfig from "../../../templates/skills/step-running/config.jso
 import stepRunningContent from "../../../templates/skills/step-running/content.md" with {
   type: "text",
 };
+import swarmDocsConfig from "../../../templates/skills/swarm-docs/config.json" with {
+  type: "text",
+};
+import swarmDocsContent from "../../../templates/skills/swarm-docs/content.md" with {
+  type: "text",
+};
 import swarmExtensionsConfig from "../../../templates/skills/swarm-extensions/config.json" with {
   type: "text",
 };
@@ -367,6 +373,7 @@ const BUILT_IN_SKILL_SOURCES = [
   { config: reviewingConfig, body: reviewingContent },
   { config: scheduledTaskResilienceConfig, body: scheduledTaskResilienceContent },
   { config: schedulingConfig, body: schedulingContent },
+  { config: swarmDocsConfig, body: swarmDocsContent },
   { config: swarmExtensionsConfig, body: swarmExtensionsContent },
   { config: scriptBuilderConfig, body: scriptBuilderContent },
   { config: scriptWorkflowsConfig, body: scriptWorkflowsContent },

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

package/src/commands/onboard/compose-generator.ts

@@ -1,3 +1,4 @@
+import { AGENT_FS_VERSION } from "./agent-fs-version.ts";
 import { composeCommandText, engineForCommands } from "./container-engine.ts";
 import { expandServices } from "./service-names.ts";
 import type { OnboardState } from "./types.ts";
@@ -71,6 +72,91 @@ const ENV_SENTRY_AUTH_TOKEN = "      - SENTRY_AUTH_TOKEN=${SENTRY_AUTH_TOKEN}";
 // biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
 const ENV_SENTRY_ORG = "      - SENTRY_ORG=${SENTRY_ORG}";
 
+// ── Bundled agent-fs + TEI (`onboard --yes`, flag `bundleAgentFs`) ──
+const APP_URL = "https://app.agent-swarm.dev";
+const AGENT_FS_INTERNAL_URL = "http://agent-fs:7433";
+const TEI_MODEL = "nomic-ai/nomic-embed-text-v1.5";
+// Compose `${PUBLIC_MCP_BASE_URL:-http://localhost:<port>}`; the caller appends `<port>}`.
+const ENV_AGENT_FS_PUBLIC_URL_PREFIX =
+  "      - AGENT_FS_PUBLIC_URL=${PUBLIC_MCP_BASE_URL:-http://localhost:";
+const TEI_IMAGE_EXPRESSION =
+  // biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
+  "${TEI_IMAGE:-ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.4}";
+
+/** The API side of the bundle: agent-fs proxy, Comb, dashboard links, TEI memory. */
+function appendBundleApiEnvironment(lines: string[]) {
+  lines.push(`      - AGENT_FS_API_URL=${AGENT_FS_INTERNAL_URL}`);
+  lines.push("      - AGENT_FS_PROXY=true");
+  lines.push("      - COMB_ENABLED=true");
+  lines.push("      - AGENT_FS_LINK_TARGET=dashboard");
+  lines.push("      - EMBEDDING_API_BASE_URL=http://tei:80/v1");
+  lines.push(`      - EMBEDDING_MODEL=${TEI_MODEL}`);
+  lines.push("      - EMBEDDING_API_KEY=local-tei");
+  // Quoted: unquoted, `KEY=search_query: ` parses as a mapping and drops the trailing space.
+  lines.push('      - "EMBEDDING_QUERY_PREFIX=search_query: "');
+  lines.push('      - "EMBEDDING_DOCUMENT_PREFIX=search_document: "');
+}
+
+function appendBundleServices(lines: string[], state: OnboardState, apiPort: number) {
+  lines.push("");
+  lines.push("  agent-fs:");
+  lines.push(`    image: "ghcr.io/desplega-ai/agent-fs:${AGENT_FS_VERSION}"`);
+  lines.push("    container_name: swarm-agent-fs");
+  lines.push(`    pull_policy: ${state.pullPolicy}`);
+  lines.push("");
+  lines.push("    environment:");
+  lines.push("      - AGENT_FS_HOME=/data");
+  lines.push("      - AGENT_FS_STORAGE_PROVIDER=local");
+  lines.push("      - AGENT_FS_LOCAL_ROOT=/data/storage");
+  lines.push("      - HOST=0.0.0.0");
+  lines.push("      - SERVER_HOST=0.0.0.0");
+  lines.push("      - PORT=7433");
+  lines.push("      - SERVER_PORT=7433");
+  lines.push("      - EMBEDDING_PROVIDER=local");
+  // The browser reaches agent-fs through the API proxy, on the tunnel URL when there is one.
+  lines.push(`${ENV_AGENT_FS_PUBLIC_URL_PREFIX}${apiPort}}/agentfs`);
+  lines.push(`      - AGENT_FS_APP_URL=${APP_URL}`);
+  lines.push("");
+  lines.push("    volumes:");
+  lines.push("      - agent_fs_data:/data");
+  lines.push("");
+  lines.push("    healthcheck:");
+  lines.push("      # The agent-fs image has no curl or wget.");
+  lines.push(
+    `      test: ["CMD-SHELL", "node -e \\"fetch('http://127.0.0.1:7433/health').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))\\""]`,
+  );
+  lines.push("      interval: 10s");
+  lines.push("      timeout: 5s");
+  lines.push("      retries: 30");
+  lines.push("      start_period: 10s");
+  lines.push("");
+  lines.push("    restart: unless-stopped");
+
+  lines.push("");
+  lines.push("  tei:");
+  lines.push(`    image: "${TEI_IMAGE_EXPRESSION}"`);
+  lines.push("    container_name: swarm-tei");
+  lines.push(`    pull_policy: ${state.pullPolicy}`);
+  // --max-batch-tokens 2048: the default warmup passed 5.4 GB and was OOM-killed on an 8 GB box.
+  // --max-client-batch-size 256: the default 32 rejects documents with more than 32 chunks.
+  lines.push(
+    `    command: ["--model-id", "${TEI_MODEL}", "--max-batch-tokens", "2048", "--max-client-batch-size", "256"]`,
+  );
+  lines.push("    mem_limit: 2g");
+  lines.push("");
+  lines.push("    volumes:");
+  lines.push("      - tei_data:/data");
+  lines.push("");
+  lines.push("    healthcheck:");
+  lines.push('      test: ["CMD-SHELL", "curl -sf http://127.0.0.1:80/health || exit 1"]');
+  lines.push("      interval: 10s");
+  lines.push("      timeout: 5s");
+  lines.push("      retries: 30");
+  lines.push("      start_period: 180s");
+  lines.push("");
+  lines.push("    restart: unless-stopped");
+}
+
 function appendProviderEnvironment(lines: string[], state: OnboardState, includeHarness: boolean) {
   if (includeHarness) lines.push(ENV_HARNESS_PROVIDER);
   switch (state.provider) {
@@ -155,7 +241,7 @@ export function generateCompose(state: OnboardState): string {
   lines.push("      - MEMORY_DEMOTION_FLOOR=${MEMORY_DEMOTION_FLOOR-1.0}");
   appendProviderEnvironment(lines, state, false);
   lines.push(`      - MCP_BASE_URL=http://localhost:${port}`);
-  lines.push("      - APP_URL=https://app.agent-swarm.dev");
+  lines.push(`      - APP_URL=${APP_URL}`);
 
   if (state.integrations.slack) {
     lines.push("      - SLACK_DISABLE=false");
@@ -168,6 +254,19 @@ export function generateCompose(state: OnboardState): string {
     lines.push("      - GITHUB_DISABLE=false");
   }
 
+  if (state.bundleAgentFs) {
+    appendBundleApiEnvironment(lines);
+    lines.push("");
+    // The boot seeder provisions agent-fs, so it must be up first. TEI only needs to
+    // start: a first boot downloads 1.1 GB of weights, and memory falls back to
+    // keyword search until it is ready.
+    lines.push("    depends_on:");
+    lines.push("      agent-fs:");
+    lines.push("        condition: service_healthy");
+    lines.push("      tei:");
+    lines.push("        condition: service_started");
+  }
+
   lines.push("");
   lines.push("    ports:");
   lines.push(`      - "${port}:3013"`);
@@ -238,14 +337,22 @@ export function generateCompose(state: OnboardState): string {
       lines.push(ENV_SENTRY_ORG);
     }
 
+    if (state.bundleAgentFs) {
+      lines.push(`      - AGENT_FS_API_URL=${AGENT_FS_INTERNAL_URL}`);
+      lines.push(`      - APP_URL=${APP_URL}`);
+      lines.push("      - AGENT_FS_LINK_TARGET=dashboard");
+    }
+
     lines.push("");
     lines.push("    ports:");
     lines.push(`      - "${port}:3000"`);
     lines.push("");
     lines.push("    volumes:");
-    lines.push("      - swarm_logs:/app/logs");
-    lines.push("      - swarm_shared:/app/shared");
-    lines.push(`      - swarm_${svc.sanitizedName}:/app/agent`);
+    // Same targets as docker-compose.example.yml: the worker logs to /logs and
+    // keeps its clones and files under /workspace.
+    lines.push("      - swarm_logs:/logs");
+    lines.push("      - swarm_shared:/workspace/shared");
+    lines.push(`      - swarm_${svc.sanitizedName}:/workspace/personal`);
     if (state.provider === "bedrock" && state.awsProfile) {
       lines.push(engine === "podman" ? AWS_PROFILE_VOLUME_SELINUX : AWS_PROFILE_VOLUME);
     }
@@ -253,6 +360,8 @@ export function generateCompose(state: OnboardState): string {
     lines.push("    restart: unless-stopped");
   }
 
+  if (state.bundleAgentFs) appendBundleServices(lines, state, port);
+
   // ── Volumes section ──
   lines.push("");
   lines.push("volumes:");
@@ -262,6 +371,10 @@ export function generateCompose(state: OnboardState): string {
   for (const svc of expanded) {
     lines.push(`  swarm_${svc.sanitizedName}:`);
   }
+  if (state.bundleAgentFs) {
+    lines.push("  agent_fs_data:");
+    lines.push("  tei_data:");
+  }
 
   return `${lines.join("\n")}\n`;
 }

package/src/commands/onboard/env-generator.ts

@@ -43,6 +43,15 @@ export function generateEnv(state: OnboardState): string {
   lines.push("MEMORY_RATERS=implicit-citation,explicit-self");
   lines.push("MEMORY_DEMOTION_FLOOR=1.0");
 
+  if (state.bundleAgentFs) {
+    lines.push("");
+    lines.push("# Bundled agent-fs (local disk) and TEI (memory embeddings); settings are in");
+    lines.push(
+      "# docker-compose.yml. Generate without them: agent-swarm onboard --yes --no-agent-fs",
+    );
+    if (state.teiImage) lines.push(`TEI_IMAGE=${state.teiImage}`);
+  }
+
   // ── Authentication ──
   lines.push("");
   lines.push("# === Authentication ===");

package/src/commands/onboard/tei-image.ts

@@ -0,0 +1,12 @@
+/** TEI image for the bundled embeddings server on arm64 hosts. */
+export const TEI_ARM64_IMAGE = "ghcr.io/huggingface/text-embeddings-inference:cpu-arm64-1.9.4";
+
+/**
+ * TEI publishes one tag per CPU architecture, so Compose `platform:` cannot
+ * pick it. `install.sh` runs onboard on the Docker host, so the host arch is
+ * the engine arch. Returns `null` for amd64 and anything else: the compose
+ * default (`cpu-1.9.4`, amd64) applies.
+ */
+export function teiImageForArch(arch: string): string | null {
+  return arch === "arm64" || arch === "aarch64" ? TEI_ARM64_IMAGE : null;
+}

package/src/commands/onboard/types.ts

@@ -95,6 +95,10 @@ export interface OnboardState {
   containerEngine: ContainerEnginePreference;
   outputDir: string;
   nonInteractive: boolean;
+  /** Bundle agent-fs (local disk) and TEI. Only `--yes` without `--no-agent-fs` sets it. */
+  bundleAgentFs: boolean;
+  /** TEI image override for the host arch; `null` keeps the compose default (amd64). */
+  teiImage: string | null;
   error: string | null;
   logs: LogLine[];
 }
@@ -114,6 +118,7 @@ export interface OnboardProps {
   maxConcurrentTasks?: string;
   pullPolicy?: string;
   containerEngine?: string;
+  noAgentFs?: boolean;
 }
 
 export type PullPolicy = "always" | "missing" | "never";
@@ -212,6 +217,8 @@ export const INITIAL_STATE: OnboardState = {
   containerEngine: "auto",
   outputDir: process.cwd(),
   nonInteractive: false,
+  bundleAgentFs: false,
+  teiImage: null,
   error: null,
   logs: [],
 };

package/src/commands/onboard.tsx

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import os from "node:os";
 import { Select } from "@inkjs/ui";
 import { Box, Text, useApp, useInput } from "ink";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -35,6 +36,7 @@ import { PostTaskStep } from "./onboard/steps/post-task.tsx";
 import { PrereqCheckStep } from "./onboard/steps/prereq-check.tsx";
 import { ReviewStep } from "./onboard/steps/review.tsx";
 import { StartStep } from "./onboard/steps/start.tsx";
+import { teiImageForArch } from "./onboard/tei-image.ts";
 import {
   getStepProgress,
   INITIAL_STATE,
@@ -61,6 +63,7 @@ export function Onboard({
   maxConcurrentTasks,
   pullPolicy,
   containerEngine,
+  noAgentFs = false,
 }: OnboardProps) {
   const { exit } = useApp();
   const [state, setState] = useState<OnboardState>(() => {
@@ -229,8 +232,15 @@ export function Onboard({
       addLog(`Integrations: ${enabled.join(", ")}`);
     }
 
+    const bundleAgentFs = !noAgentFs;
+    if (bundleAgentFs) {
+      addLog("Bundling agent-fs and TEI (local files and memory; --no-agent-fs to skip)");
+    }
+
     goToStep("generate", {
       nonInteractive: true,
+      bundleAgentFs,
+      teiImage: bundleAgentFs ? teiImageForArch(os.arch()) : null,
       deployType: "local",
       presetId: selectedPreset.id,
       services: selectedPreset.services,
@@ -250,7 +260,7 @@ export function Onboard({
       sentryToken: process.env.SENTRY_AUTH_TOKEN || "",
       sentryOrg: process.env.SENTRY_ORG || "",
     });
-  }, [yes, preset, state.step, addLog, goToStep, goToError]);
+  }, [yes, preset, noAgentFs, state.step, addLog, goToStep, goToError]);
 
   // Interactive welcome: auto-advance after detecting existing setup
   useEffect(() => {

package/src/commands/provider-credentials.ts

@@ -49,6 +49,7 @@ import {
   CREDENTIAL_POOL_VARS,
   splitCredentialPool,
 } from "../utils/credentials";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import {
   checkAnthropicApiKey,
   checkDeepSeekApiKey,
@@ -664,7 +665,7 @@ export async function validateProviderCredentials(
  * the dashboard surfaces "unreported".
  */
 export function isCredCheckDisabled(env: NodeJS.ProcessEnv): boolean {
-  return env.CRED_CHECK_DISABLE === "1";
+  return isEnvFlagEnabled("CRED_CHECK_DISABLE", false, env);
 }
 
 /**