feat(stack): prepare slim resources on demand

apps/cli/src/next/commands/branches/switch/switch.handler.ts

@@ -147,7 +147,7 @@ export const switchBranch = Effect.fn("branches.switch")(function* (opts: {
     // `pull` does not exist yet.
     const launchConfig =
       stackCheck.value.launch === undefined
-        ? toStartStackConfig([], "auto")
+        ? toStartStackConfig([], undefined)
         : withServiceVersions(
             toStartStackConfig(
               stackCheck.value.launch.excludedServices?.filter(

apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts

@@ -55,7 +55,7 @@ const startFullStack = Effect.fnUntraced(function* (opts: FunctionsDevStackOptio
   const serviceVersionContext = yield* resolveServiceVersionContext([], undefined);
   const loadedProjectConfig = yield* loadProjectConfig(projectHome.projectRoot);
   const stackConfig = withServiceVersions(
-    toStartStackConfig([], "auto"),
+    toStartStackConfig([], undefined),
     serviceVersionContext.runtimeVersions,
   );
   const stackLayer = yield* daemonLayer({
@@ -65,7 +65,6 @@ const startFullStack = Effect.fnUntraced(function* (opts: FunctionsDevStackOptio
     name: opts.stack,
     edgeRuntime: opts.edgeRuntime,
     launch: {
-      mode: "auto",
       versions: serviceVersionContext.pinnedBaseline,
       excludedServices: [],
     },

apps/cli/src/next/commands/start/service-version-overrides.unit.test.ts

@@ -11,14 +11,14 @@ import {
 } from "../../config/service-version-resolution.ts";
 
 describe("service version overrides", () => {
-  test("parses and normalizes repeated flag overrides", async () => {
+  test("parses repeated flag overrides as exact image tags", async () => {
     await expect(
       Effect.runPromise(
         parseServiceVersionOverrides(["postgrest=v14.5", "mailpit=1.30.2", "auth=2.180.0"]),
       ),
     ).resolves.toEqual({
-      postgrest: "14.5",
-      mailpit: "v1.30.2",
+      postgrest: "v14.5",
+      mailpit: "1.30.2",
       auth: "2.180.0",
     });
   });
@@ -27,8 +27,8 @@ describe("service version overrides", () => {
     const candidateBaseline = {
       ...DEFAULT_VERSIONS,
       postgres: "17.6.1.090",
-      postgrest: "14.5",
-      auth: "2.187.0",
+      postgrest: "v14.5",
+      auth: "v2.187.0",
     };
 
     const layer = Layer.mergeAll(
@@ -68,12 +68,12 @@ describe("service version overrides", () => {
       runtimeVersions: {
         ...candidateBaseline,
         postgres: "17.4.1.045",
-        auth: "2.170.0",
+        auth: "v2.170.0",
         storage: "1.40.0",
       },
       activeOverrides: [
         { service: "postgres", version: "17.4.1.045", source: "flag" },
-        { service: "auth", version: "2.170.0", source: "flag" },
+        { service: "auth", version: "v2.170.0", source: "flag" },
         { service: "storage", version: "1.40.0", source: "local" },
       ],
       availableUpdates: [],

apps/cli/src/next/commands/start/start.command.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer, Context } from "effect";
+import { Effect, Layer, Context, Option } from "effect";
 import { loadProjectConfig } from "@supabase/config";
 import {
   DEFAULT_MANAGED_STACK_NAME,
@@ -79,9 +79,10 @@ export const serviceVersionFlag = Flag.string("service-version").pipe(
 
 const modeFlag = Flag.choice("mode", startModes).pipe(
   Flag.withDescription(
-    'Stack startup mode. "auto" prefers native binaries and falls back to Docker, "native" requires native-compatible services, and "docker" forces Docker for all services.',
+    'Stack startup mode. "native" requires native-compatible services and "docker" requires a usable Docker or Podman runtime.',
   ),
-  Flag.withDefault("auto" as StartMode),
+  Flag.optional,
+  Flag.map(Option.getOrUndefined),
 );
 
 interface StartVersionStateShape {
@@ -124,7 +125,7 @@ export type StartFlags = CliCommand.Command.Config.Infer<typeof flags>;
 export const startCommand = Command.make("start", flags).pipe(
   Command.withDescription(
     "Start the local Supabase development stack.\n\n" +
-      "Starts the full local Supabase stack. Use --mode auto (default) to prefer native binaries and fall back to Docker, --mode native to require native-compatible services, or --mode docker to force Docker-backed startup.\n\n" +
+      "Starts the full local Supabase stack. By default, a usable Docker or Podman runtime selects Docker mode; otherwise the stack uses native mode. Use --mode to require one explicitly.\n\n" +
       "Named CLI stacks persist managed runtime state under the Supabase home directory. Use --exclude to skip optional services. Use --detach to run in the background.",
   ),
   Command.withShortDescription("Start local Supabase stack"),
@@ -219,7 +220,7 @@ export const startCommand = Command.make("start", flags).pipe(
               portDocument: portIntents,
             });
       const launch = {
-        mode: flags.mode,
+        ...(flags.mode === undefined ? {} : { mode: flags.mode }),
         versions: serviceVersionContext.pinnedBaseline,
         excludedServices: flags.exclude,
         ...(existingSummary?.lastNotifiedUpdateFingerprint === undefined
@@ -242,12 +243,15 @@ export const startCommand = Command.make("start", flags).pipe(
         cwd: runtimeInfo.cwd,
         name: flags.stack,
       });
+      if (summary.launch === undefined) {
+        return yield* Effect.die("Managed stack started without persisted launch settings");
+      }
 
       return {
         stackLayer,
         startVersionState: StartVersionState.of({
           launch: {
-            mode: flags.mode,
+            mode: summary.launch.mode,
             versions: serviceVersionContext.pinnedBaseline,
             excludedServices: flags.exclude,
           },

apps/cli/src/next/commands/start/start.handler.ts

@@ -50,7 +50,6 @@ export const start = Effect.fnUntraced(function* (flags: StartFlags) {
         yield* updateManagedLaunch({
           ...lifecycleInput,
           launch: {
-            mode: launch.mode,
             versions: launch.versions,
             excludedServices: launch.excludedServices,
             lastNotifiedUpdateFingerprint: serviceVersionContext.updateFingerprint,
@@ -68,7 +67,7 @@ export const start = Effect.fnUntraced(function* (flags: StartFlags) {
       }
 
       yield* analytics.capture("cli_stack_started", {
-        mode: flags.mode,
+        mode: launch.mode,
         detach: flags.detach,
         stack: flags.stack,
       });

apps/cli/src/next/commands/start/start.integration.test.ts

@@ -80,7 +80,7 @@ describe("start handler", () => {
               );
               return start({
                 stack: fixture.stackName,
-                mode: "auto",
+                mode: "docker",
                 exclude: [],
                 serviceVersion: [],
                 detach: false,

apps/cli/src/next/commands/status/status.handler.ts

@@ -43,7 +43,7 @@ const resolveConfiguredSummary = Effect.fnUntraced(function* (input: {
   return yield* resolveStackSummary({
     ...input,
     portDocument: managedPortIntents(
-      toStartStackConfig(excluded, current.launch?.mode ?? "auto"),
+      toStartStackConfig(excluded, current.launch?.mode),
       loaded ?? undefined,
     ),
   });

apps/cli/src/next/commands/update/update.handler.ts

@@ -103,19 +103,14 @@ export const update = Effect.fnUntraced(function* (flags: UpdateFlags) {
   );
 
   if (Option.isSome(existingSummary)) {
-    const persistedLaunch = existingSummary.value.launch ?? {
-      mode: "auto" as const,
-      excludedServices: [] as const,
-    };
     yield* updateManagedLaunch({
       cacheRoot: cliConfig.supabaseHome,
       cwd: runtimeInfo.cwd,
       workspacePath: projectHome.projectRoot,
       stackName: flags.stack,
       launch: {
-        mode: persistedLaunch.mode,
         versions: serviceVersionContext.candidateBaseline,
-        excludedServices: persistedLaunch.excludedServices,
+        excludedServices: existingSummary.value.launch?.excludedServices ?? [],
         ...(existingSummary.value.lastNotifiedUpdateFingerprint === undefined
           ? {}
           : {

apps/cli/src/next/config/stack-config.ts

@@ -17,17 +17,16 @@ export const excludedStackServices = [
 export type ExcludedStackService = (typeof excludedStackServices)[number];
 export const isExcludedStackService = (value: string): value is ExcludedStackService =>
   excludedStackServices.some((candidate) => candidate === value);
-export const startModes = ["native", "auto", "docker"] as const;
+export const startModes = ["native", "docker"] as const;
 export type StartMode = (typeof startModes)[number];
 
 export function toStartStackConfig(
   exclude: ReadonlyArray<ExcludedStackService>,
-  mode: StartMode,
+  mode?: StartMode,
 ): StackConfig {
   const excluded = new Set(exclude);
   return {
-    mode,
-    startupMode: "lazy",
+    ...(mode === undefined ? {} : { mode }),
     realtime: excluded.has("realtime") ? false : {},
     storage: excluded.has("storage") ? false : {},
     imgproxy: excluded.has("imgproxy") || excluded.has("storage") ? false : {},

apps/cli/src/next/config/stack-config.unit.test.ts

@@ -2,28 +2,29 @@ import { describe, expect, it } from "vitest";
 import { toStartStackConfig, withServiceVersions } from "./stack-config.ts";
 
 describe("toStartStackConfig", () => {
-  it("uses lazy service startup with the requested runtime mode", () => {
-    expect(toStartStackConfig([], "auto")).toMatchObject({
-      mode: "auto",
-      startupMode: "lazy",
+  it("leaves mode unset so the stack package can select the usable runtime", () => {
+    expect(toStartStackConfig([], undefined)).not.toHaveProperty("mode");
+  });
+
+  it("uses the requested runtime mode and catalog service defaults", () => {
+    expect(toStartStackConfig([], "docker")).toMatchObject({
+      mode: "docker",
     });
     expect(toStartStackConfig([], "docker")).toMatchObject({
       mode: "docker",
-      startupMode: "lazy",
     });
     expect(toStartStackConfig([], "native")).toMatchObject({
       mode: "native",
-      startupMode: "lazy",
     });
   });
 
   it("dedupes excluded services when building stack config", () => {
-    expect(toStartStackConfig(["auth", "auth"], "auto")).toMatchObject({
-      mode: "auto",
+    expect(toStartStackConfig(["auth", "auth"], "docker")).toMatchObject({
+      mode: "docker",
       auth: false,
     });
-    expect(toStartStackConfig(["auth", "postgrest"], "auto")).toMatchObject({
-      mode: "auto",
+    expect(toStartStackConfig(["auth", "postgrest"], "docker")).toMatchObject({
+      mode: "docker",
       auth: false,
       postgrest: false,
     });
@@ -33,7 +34,7 @@ describe("toStartStackConfig", () => {
 describe("withServiceVersions", () => {
   it("injects linked service versions without re-enabling excluded services", () => {
     expect(
-      withServiceVersions(toStartStackConfig([], "auto"), {
+      withServiceVersions(toStartStackConfig([], "docker"), {
         postgres: "17.6.1.090",
         postgrest: "14.5",
         auth: "2.187.0",
@@ -49,7 +50,7 @@ describe("withServiceVersions", () => {
     });
 
     expect(
-      withServiceVersions(toStartStackConfig(["auth", "storage"], "auto"), {
+      withServiceVersions(toStartStackConfig(["auth", "storage"], "docker"), {
         postgres: "17.6.1.090",
         auth: "2.187.0",
         storage: "1.39.2",

apps/cli/tests/helpers/running-stack.ts

@@ -24,7 +24,12 @@ import { CliConfig } from "../../src/next/config/cli-config.service.ts";
 import { ProjectHome } from "../../src/next/config/project-home.service.ts";
 import { RuntimeInfo } from "../../src/shared/runtime/runtime-info.service.ts";
 
-const launch = { mode: "auto" as const, versions: { postgres: "17.6.1" }, excludedServices: [] };
+const launch = {
+  mode: "docker" as const,
+  containerRuntime: "docker" as const,
+  versions: { postgres: "17.6.1" },
+  excludedServices: [],
+};
 const portDocument: ManagedPortIntentDocument = {
   activeFields: ["apiPort", "dbPort"],
   document: {},

packages/process-compose/tests/helpers/mocks.ts

@@ -17,10 +17,10 @@ const isOneShotSupervisor = (args: ReadonlyArray<string>): boolean => {
       typeof config === "object" &&
       config !== null &&
       "command" in config &&
-      config.command === "bash" &&
       "args" in config &&
       Array.isArray(config.args) &&
-      config.args[0] === "-c"
+      ((config.command === "bash" && config.args[0] === "-c") ||
+        ((config.command === "docker" || config.command === "podman") && config.args[0] === "exec"))
     );
   } catch {
     return false;

packages/stack/README.md

@@ -15,7 +15,9 @@ console.log((await stack.getInfo()).url);
 
 `createStack` resolves configuration, reserves ports, and builds a scoped
 handle. `stack.start()` starts services; disposing the handle stops them and
-releases its lease.
+releases its lease. When `mode` is omitted, creation uses Docker mode with a
+usable Docker or Podman service and otherwise selects native mode. An explicit
+mode never falls back to the other one.
 
 ## Managed stack
 
@@ -47,7 +49,7 @@ const runtime =
     projectDir: projectRoot,
     name: "default",
     portIntents,
-    launch: { mode: "auto", versions: {}, excludedServices: [] },
+    launch: { mode: "docker", versions: {}, excludedServices: [] },
   });
 ```
 
@@ -56,5 +58,10 @@ const runtime =
 `stopDaemon` and the discovery helpers delegate to the managed lifecycle
 facade. No CLI metadata file or PID polling is involved.
 
+After a managed supervisor claims a stack, its persisted Docker, Podman, or
+native selection remains pinned even if startup later fails. Retry after
+restoring or starting that runtime; delete and recreate the stack to choose a
+different execution mode. Deletion removes the stack's managed data.
+
 For the end-to-end lifecycle, identity, ports, service execution, transport,
 compiled-Bun re-entry, and testing boundary, see [How `@supabase/stack` works](docs/architecture.md).

packages/stack/docs/architecture.md

@@ -79,8 +79,11 @@ prepares/builds a scoped runtime and handle. It does **not** start service
 processes. Asset preparation and process-compose graph construction happen
 when the handle is first started or a service is activated.
 
-`stack.start()` starts services according to the configured startup mode and
-waits for the selected readiness policy. The handle also exposes status, logs,
+`stack.start()` prepares and starts Postgres plus the services whose resource
+policy is `eager`, then waits for the selected readiness policy. Services whose
+policy is `lazy` remain dormant until a proxy request or explicit service
+operation activates them; activation prepares the service and its required
+dependencies before starting it. The handle also exposes status, logs,
 per-service operations, and graceful `stop()`/`dispose()` methods. Its scope
 owns service processes and releases the lease when disposed. A direct stack
 never reads or writes managed documents and never coordinates with a sibling
@@ -222,15 +225,27 @@ status, service operations, logs, graceful stop, and launch-update routes;
 
 ## Service execution and `ApiProxy`
 
-`StackPreparation` resolves each enabled service to a verified native binary or
-a Docker image. `mode: "native"` uses the supported native services and rejects
-Docker-only services; `mode: "docker"` resolves every service to an image;
-`mode: "auto"` prefers native artifacts and falls back to Docker. The
-`StackBuilder` turns those resolutions into one process-compose graph, so a
-stack can run native and Docker-backed services together. Docker resources are
-namespaced with the managed stack id; when native Postgres is combined with
-Docker services, the graph supplies the platform-specific host address so the
-containers can reach it.
+`StackPreparation` plans resources without materializing them, then prepares
+only the requested services and their required dependency closure. Concurrent
+requests for the same resource share one installation or pull. Native assets
+come from the pinned slim-services release contract and are checksum- and
+manifest-verified before atomic publication. Docker assets use one canonical
+`ghcr.io/supabase/cli/<service>:<version>` reference; a locally cached image is
+reused and a missing image is pulled without registry fallback. Stack creation
+selects exactly one execution mode: a usable Docker daemon is preferred, then a
+usable Podman service; if neither responds, the stack uses native mode. An
+explicit `mode: "native"` rejects Docker-only services, while explicit `mode:
+"docker"` requires a usable container runtime. Preparation never falls back to
+the other mode after that choice. Once a managed supervisor claims and persists
+that selection, it remains pinned even when startup later fails during image
+pull, native download, graph build, or readiness. Retries restore or start the
+persisted runtime and reuse the same mode; selecting another mode requires
+deleting and recreating the stack, which removes its managed data.
+
+The `StackBuilder` turns planned resolutions into one process-compose graph,
+without eagerly materializing every graph resource. Container resources are
+namespaced with the managed stack id and every pull, launch, health check, and
+cleanup uses the selected Docker or Podman executable.
 
 `ApiProxy` listens on the configured public `apiPort` and routes Supabase API
 paths (`/auth`, `/rest`, `/functions`, `/realtime`, `/storage`, `/pg`,