fix(setup,compose): bundle Redis, fix socket reconnect, and harden the setup wizard (#5964)

* feat(compose,setup): bundle Redis, always configure it, fix lifecycle detection

Compose shipped no redis service at all — REDIS_URL was ${REDIS_URL:-} in both app and realtime, so every self-hosted stack ran without it. Storage silently falls back to PostgreSQL, but the pub/sub channels (live Chat task-status, table events) have no fallback, so live updates never arrived.

- compose (prod + local): add a redis:7-alpine service with a healthcheck, default REDIS_URL to redis://redis:6379, and make app/realtime depend on it being healthy. Not published to the host — only the containers need it, and binding 6379 would collide with a local Redis. An external REDIS_URL in root .env still overrides. Deliberately not written into root .env: doctor pings REDIS_URL from the host, and a compose-internal hostname would fail that probe the same way DATABASE_URL would.
- dev mode: configure Redis in quick too. Quick uses a new non-interactive ensureRedis (adopt whatever answers, else start the managed container, warn only if Docker is unavailable); custom keeps the ladder, with corrected copy — the old prompt claimed Redis was only for multi-replica.
- lifecycle: detect compose stacks via 'docker compose ls' instead of probing '-f <file> ps' in the working directory. Compose derives the project name from the directory it was started in, so the old probe found a stack only when run from the checkout that launched it (a globally linked sim never could) and listed the same stack once per candidate file. compose ls reports the real project and its config file, so one stack yields one install from anywhere; non-Sim projects are filtered by compose filename. Every compose op now runs in that stack's directory.
- lifecycle: distinguish 'Docker unreachable' from 'nothing installed'. With the daemon down, status reported containers as 'absent' and suggested re-running setup; it now says Docker is down and marks state unknown.

* fix(setup): don't start managed Postgres with a password the volume will ignore

POSTGRES_PASSWORD only applies when initdb runs on an empty data directory. The sim-postgres-data volume outlives its container (sim down keeps it, docker rm keeps it, and the wizard's own recreate path keeps it), and inspectManagedContainer recovers the password from the *container*, not the volume — so once the container is gone the password is unrecoverable.

Setup then generated a fresh password and ran against the initialized volume. Postgres kept its original password and rejected every connection with 'password authentication failed for user postgres', which surfaced as a misleading 'container did not become healthy'.

Detect an already-bootstrapped volume (PG_VERSION present) before choosing a password, and ask: supply the existing password, or delete the volume and start fresh (double-confirmed, since that destroys data). Refusing both fails with the exact docker volume rm command instead of looping.

* improvement(setup): default to Docker Compose and sharpen the run-mode copy

Compose was listed first but only preselected when Docker happened to be running — with Docker stopped the cursor sat on 'Local dev', steering people toward a source checkout when they wanted to run Sim. Compose mode calls ensureDocker(true), which offers to start Docker Desktop, so a stopped daemon is no reason to change the default.

Also tightens the hints to say what each mode is for: run bundled Sim (fastest way to start), work on Sim itself, test a production-style k8s deploy.

* fix(compose): point the browser socket at :3002 so it stops reconnecting

The stack publishes the app on 3000 and realtime on 3002 with no reverse proxy between them, but NEXT_PUBLIC_SOCKET_URL defaulted to empty — which tells the browser client to use the page origin. :3000/socket.io answers 308 (a Next redirect), not a Socket.IO handshake, so the client failed and retried forever. Default it to http://localhost:3002; a proxied deployment overrides it (or sets it empty to use the page origin).

Also give COPILOT_API_KEY and SIM_AGENT_API_URL empty defaults so every compose command stops printing 'variable is not set' warnings. The app already falls back to the prod copilot backend when SIM_AGENT_API_URL is blank.

* feat(setup): pass SIM_AGENT_API_URL through, and warn on a half-set mothership

Sim devs testing against a non-prod mothership export SIM_CLI_AUTH_ORIGIN so the Chat key is minted there, but nothing carried the matching backend URL into the install — the app kept defaulting to prod copilot, which rejects a staging key with 'Invalid API key'.

Persist SIM_AGENT_API_URL when it is exported, so later docker compose up / dev runs stay on that backend instead of reverting to prod once the shell is gone:

  SIM_CLI_AUTH_ORIGIN=https://www.staging.sim.ai \
  SIM_AGENT_API_URL=https://www.staging.copilot.sim.ai \
  bun run setup

Setting only the auth origin is the trap, so that combination warns. Neither set is the self-hoster default and stays silent — no prompts, no flags.

* fix(setup): survive a vanished port owner, and stop flagging our own containers

Two failures from one compose re-run:

- 'Kill it for me' crashed setup with 'kill() failed: ESRCH: No such process'. The owner list is an lsof snapshot, so the process can exit before the signal lands — which is the outcome we wanted, not an error. ESRCH now counts as freed, EPERM warns that it must be stopped by hand, and anything else warns; the loop re-probes either way instead of aborting a setup that had already written .env.

- Compose mode demanded 3000/3002 be free even when this stack was the one holding them, so re-running setup against a running install reported its own realtime container as a blocker and offered to kill Docker's listener. 'docker compose up -d' reconciles its own containers, so skip the check when the project already has some. A foreign process is still caught, and a foreign container still surfaces as a bind error from compose.

* fix(csp,setup): permit the socket origin the client actually uses; encode DSN passwords

Review round on #5964:

- The socket reconnect was a CSP bug, not a URL bug. getSocketUrl() already falls back to localhost:3002 for a localhost page, but generateRuntimeCSP gated that same fallback on isDev — and compose runs NODE_ENV=production, so connect-src omitted ws://localhost:3002 and the browser blocked the handshake. Key the fallback on the app URL being localhost instead, mirroring getSocketUrl. Revert the compose NEXT_PUBLIC_SOCKET_URL default: an explicit value suppresses the page-origin fallback that reverse-proxied self-hosts depend on, and ':-' treats empty as unset so the documented escape hatch could not work either. LOCALHOST_HOSTNAMES is duplicated locally because csp.ts is loaded by next.config.ts before @/ aliases resolve.
- Percent-encode the password when building the Postgres DSN. A user-supplied password containing @ : / # does not merely re-parse to the wrong host — it fails to parse as a URL at all, so a correct password surfaced as a connection failure.
- Tell 'Postgres rejected this password' apart from 'Postgres never started'. On the keep-the-volume path a wrong password left a healthy server and the old generic 'container did not become healthy' error, which is the confusion this change set exists to remove.

Adds a CSP regression test for the unset-socket-URL production case; verified it fails against the previous condition.

* improvement(setup): make k8s mode end somewhere usable, and show install progress

Two things made k8s mode the least satisfying path.

The services are ClusterIP, so a successful install left nothing on :3000 — 'Sim is ready' was true about the cluster and useless to the user, who had to notice and run a port-forward by hand. Compose opens a browser and dev offers to start the server; k8s now offers the forward the same way and runs it in the foreground so Ctrl-C ends it. Realtime gets its own forward (kubectl takes one resource per invocation) or the editor socket fails; it is a child in the same process group, so the terminal's Ctrl-C reaches it, and it is killed explicitly when the app forward exits.

'helm --wait' then blocked for minutes with a single static spinner, so a slow image pull looked identical to a wedged install. Run helm asynchronously and poll the cluster, so the spinner reports '3/3 pods ready · 1 starting'. CronJob-owned pods are excluded: the chart schedules a lot of them (36 on a running cluster here) and they finish as Completed, which would swamp the count and make readiness jitter for reasons unrelated to the install. Restarting pods are surfaced too — a cold cluster restarts realtime while Postgres comes up, and a silent spinner made that look like nothing was happening.

* fix(setup): identify Sim compose projects by content, not filename

Cursor (High): composeInstalls treated any project whose config basename was docker-compose.prod.yml or docker-compose.local.yml as a Sim install. Those names are common, and sim reset runs 'compose down -v' — so a stranger's stack could have had its volumes destroyed.

I introduced that reach. The previous ROOT-scoped '-f' probe was implicitly safe because it could only ever see the project in this checkout; switching to a global 'compose ls' to find stacks started elsewhere means projects must be identified by content instead. Read the config file Docker recorded and require a Sim marker (the published app image, or the app Dockerfile this repo builds), so both the prod and local variants match while an unrelated file with the same name does not. An unreadable or since-deleted file is left unmanaged rather than assumed ours.

Verified against a decoy nginx compose file using our exact filename: ignored, while both real Sim compose files still match.

* fix(setup): scope the compose port skip to published ports; print both k8s forwards

Review round on #5964:

- ensureComposePortsFree skipped conflict handling whenever the project had any container running, so leftover db/redis (which publish neither app port) waved through a foreign process on :3000 — it then surfaced as a raw compose bind error instead of the prompt. Read the host ports the project actually publishes and skip only those; the remaining ports still get the full check. Reading from the containers rather than the file matters because what counts is what is bound right now.
- The post-install note and the skip path documented only the app forward, while offerPortForward runs two. Skipping the prompt or copying the printed command left the editor's socket dead — the exact failure this change set exists to fix. Both commands now come from one forwardCommands() helper, so what is printed and what is run cannot drift.

* fix(setup): one source for the k8s forwards, and surface a dead realtime forward

Third round on the same theme, so fix it at the root rather than at another call site.

- lifecycle's k8sReachHints (used by sim start/restart) still restated an app-only forward, recreating the dead editor socket the setup path had just been fixed for. forwardCommands is now exported and consumed there, so every place that tells a user how to reach a ClusterIP release derives it from one definition.
- The realtime forward was spawned with stdio ignored and never checked, so a busy :3002 or a missing service killed it silently while the app forward kept running — indistinguishable from success until the editor won't connect. Keep its stderr, warn on an exit we did not ask for, and stay quiet on the intentional kill.

* fix(setup): pin the compose project on every lifecycle op

composeInstalls records the real project name from 'compose ls' and status and the destructive confirms print it, but every op ran 'compose -f <file>' with only cwd set — so Compose re-derived the project from that directory. The derived name is frequently not the recorded one: a directory is lowercased and stripped of dots (Sim.Demo_Test derives simdemo_test), and an explicit -p or COMPOSE_PROJECT_NAME at creation diverges outright. stop/down/reset could therefore act on a different project than the one named in the confirm, and reset runs 'down -v'.

Route every op through composeArgs(), which pins '-p <recorded project>'. cwd stays, since the file's own relative paths still resolve against it. Verified with a stack started as -p pinned-name from a directory deriving simdemo_test: the old form found 0 of its containers, the pinned form finds them.

* fix(setup): warn on both halves of a mothership mismatch

mothershipOverride warned only when SIM_CLI_AUTH_ORIGIN was set without SIM_AGENT_API_URL, while its own copy said to set both or neither. The reverse is the same failure mirrored: with only SIM_AGENT_API_URL set, the Chat key is still minted against the default prod auth origin and then validated against the override, which rejects it — silently, which is exactly what this helper exists to prevent.

Warn on either asymmetry, and read the default origin from one constant shared with the handoff so the message can't claim an origin the code no longer uses.

* fix(setup): warn about a half-set mothership before minting the key

mothershipOverride ran two steps after promptCopilotKey, so a half-set override minted a key against one environment, stored it, and only then warned that the other environment would reject it. Worse on a re-run: promptCopilotKey offers to keep an existing COPILOT_API_KEY and defaults to yes, so the bad key survives.

Move the override ahead of the key prompt in both compose and dev, so the warning arrives while it can still change the outcome — the user can abort and set the missing half before anything is minted. Nothing in the override depends on the key, so the order is free.

Author: TheodoreSpeaks

apps/sim/lib/core/security/csp-socket-fallback.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @vitest-environment node
+ *
+ * The bundled docker-compose stack runs NODE_ENV=production, serves the app from
+ * localhost, and leaves NEXT_PUBLIC_SOCKET_URL unset. getSocketUrl() falls back
+ * to localhost:3002 for a localhost page regardless of NODE_ENV, so the CSP has
+ * to permit that origin or the browser blocks the handshake and Socket.IO
+ * retries forever. Its own file because vi.mock is hoisted per-module and the
+ * sibling suite needs NEXT_PUBLIC_SOCKET_URL set.
+ */
+import { createEnvMock } from '@sim/testing'
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/lib/core/config/env', () =>
+  createEnvMock({
+    NEXT_PUBLIC_APP_URL: 'http://localhost:3000',
+    NEXT_PUBLIC_SOCKET_URL: undefined,
+  })
+)
+
+vi.mock('@/lib/core/config/env-flags', () => ({
+  isDev: false,
+  isHosted: false,
+  isReactGrabEnabled: false,
+}))
+
+import { generateRuntimeCSP } from './csp'
+
+describe('generateRuntimeCSP — socket fallback on a localhost origin', () => {
+  it('permits the default socket origin when NEXT_PUBLIC_SOCKET_URL is unset', () => {
+    const csp = generateRuntimeCSP()
+
+    expect(csp).toContain('http://localhost:3002')
+    expect(csp).toContain('ws://localhost:3002')
+  })
+
+  it('keeps the socket sources inside connect-src', () => {
+    const connectSrc = generateRuntimeCSP()
+      .split(';')
+      .map((directive) => directive.trim())
+      .find((directive) => directive.startsWith('connect-src'))
+
+    expect(connectSrc).toBeDefined()
+    expect(connectSrc).toContain('ws://localhost:3002')
+  })
+})

apps/sim/lib/core/security/csp.ts

@@ -16,6 +16,23 @@ function toWebSocketUrl(httpUrl: string): string {
   return httpUrl.replace('http://', 'ws://').replace('https://', 'wss://')
 }
 
+/**
+ * Kept in sync with LOCALHOST_HOSTNAMES in ../utils/urls by hand: this module is
+ * loaded by next.config.ts before `@/` aliases resolve, so it cannot import from
+ * there (see the note above).
+ */
+const LOCALHOST_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]', '::1'])
+
+/** Mirrors getSocketUrl's localhost check — those origins fall back to DEFAULT_SOCKET_URL. */
+function isLocalhostUrl(url: string): boolean {
+  if (!url) return false
+  try {
+    return LOCALHOST_HOSTNAMES.has(new URL(url).hostname)
+  } catch {
+    return false
+  }
+}
+
 function getHostnameFromUrl(url: string | undefined): string[] {
   if (!url) return []
   try {
@@ -208,7 +225,15 @@ export function buildCSPString(directives: CSPDirectives): string {
 export function generateRuntimeCSP(): string {
   const appUrl = getEnv('NEXT_PUBLIC_APP_URL') || ''
 
-  const socketUrl = getEnv('NEXT_PUBLIC_SOCKET_URL') || (isDev ? DEFAULT_SOCKET_URL : '')
+  // Must permit whatever getSocketUrl() actually connects to, or the browser
+  // blocks the handshake and Socket.IO retries forever. That helper falls back
+  // to DEFAULT_SOCKET_URL whenever the page is served from localhost — which
+  // includes a production build (docker compose sets NODE_ENV=production), so
+  // keying this on isDev alone left the bundled stack with a CSP that forbade
+  // its own realtime port. A non-localhost origin still resolves to the page
+  // origin, which appUrl already covers, so nothing is loosened there.
+  const socketUrl =
+    getEnv('NEXT_PUBLIC_SOCKET_URL') || (isDev || isLocalhostUrl(appUrl) ? DEFAULT_SOCKET_URL : '')
   const socketWsUrl = socketUrl ? toWebSocketUrl(socketUrl) : ''
   const ollamaUrl = getEnv('OLLAMA_URL') || (isDev ? DEFAULT_OLLAMA_URL : '')
 

docker-compose.local.yml

@@ -21,15 +21,17 @@ services:
       - ENCRYPTION_KEY=${ENCRYPTION_KEY:-dev-encryption-key-at-least-32-chars}
       - API_ENCRYPTION_KEY=${API_ENCRYPTION_KEY:-}
       - INTERNAL_API_SECRET=${INTERNAL_API_SECRET:-dev-internal-api-secret-min-32-chars}
-      - REDIS_URL=${REDIS_URL:-}
-      - COPILOT_API_KEY=${COPILOT_API_KEY}
-      - SIM_AGENT_API_URL=${SIM_AGENT_API_URL}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      - COPILOT_API_KEY=${COPILOT_API_KEY:-}
+      - SIM_AGENT_API_URL=${SIM_AGENT_API_URL:-}
       - OLLAMA_URL=${OLLAMA_URL:-http://localhost:11434}
       - SOCKET_SERVER_URL=${SOCKET_SERVER_URL:-http://realtime:3002}
       - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-}
     depends_on:
       db:
         condition: service_healthy
+      redis:
+        condition: service_healthy
       migrations:
         condition: service_completed_successfully
       realtime:
@@ -55,10 +57,12 @@ services:
       - BETTER_AUTH_URL=${BETTER_AUTH_URL:-http://localhost:3000}
       - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET:-dev-secret-at-least-32-characters-long}
       - INTERNAL_API_SECRET=${INTERNAL_API_SECRET:-dev-internal-api-secret-min-32-chars}
-      - REDIS_URL=${REDIS_URL:-}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
     depends_on:
       db:
         condition: service_healthy
+      redis:
+        condition: service_healthy
     restart: unless-stopped
     ports:
       - '3002:3002'
@@ -86,6 +90,20 @@ services:
     command: ['bun', 'run', 'db:migrate']
     restart: 'no'
 
+  # Backs pub/sub (live Chat task-status and table events) and the shared caches.
+  # The app falls back to PostgreSQL for storage when REDIS_URL is unset, but the
+  # pub/sub channels have no fallback — without Redis, live status never streams.
+  # Not published to the host: only the app and realtime containers need it, and
+  # binding 6379 would collide with a Redis already running locally.
+  redis:
+    image: redis:7-alpine
+    restart: always
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
   db:
     image: pgvector/pgvector:pg17
     restart: always

docker-compose.prod.yml

@@ -30,20 +30,23 @@ services:
       - ENCRYPTION_KEY=${ENCRYPTION_KEY}
       - API_ENCRYPTION_KEY=${API_ENCRYPTION_KEY:-}
       - INTERNAL_API_SECRET=${INTERNAL_API_SECRET}
-      - REDIS_URL=${REDIS_URL:-}
-      - COPILOT_API_KEY=${COPILOT_API_KEY}
-      - SIM_AGENT_API_URL=${SIM_AGENT_API_URL}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
+      - COPILOT_API_KEY=${COPILOT_API_KEY:-}
+      - SIM_AGENT_API_URL=${SIM_AGENT_API_URL:-}
       - OLLAMA_URL=${OLLAMA_URL:-http://localhost:11434}
       - SOCKET_SERVER_URL=${SOCKET_SERVER_URL:-http://realtime:3002}
-      # NEXT_PUBLIC_SOCKET_URL is read by the browser. Leaving it unset lets the
-      # client default to the page's own origin (assumes the reverse proxy routes
-      # /socket.io). Set it explicitly only when the realtime service is on a
-      # different host:port from the app (e.g. wss://socket.example.com).
+      # NEXT_PUBLIC_SOCKET_URL is read by the browser. Leave it unset for this
+      # stack: the client already falls back to localhost:3002 for a localhost
+      # page, and a proxied deployment needs the page-origin fallback that an
+      # explicit value would suppress. Set it only when realtime is on a
+      # different host:port (e.g. wss://socket.example.com).
       - NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL:-}
       - ADMISSION_GATE_MAX_INFLIGHT=${ADMISSION_GATE_MAX_INFLIGHT:-500}
     depends_on:
       db:
         condition: service_healthy
+      redis:
+        condition: service_healthy
       migrations:
         condition: service_completed_successfully
       realtime:
@@ -74,10 +77,12 @@ services:
       - BETTER_AUTH_URL=${BETTER_AUTH_URL:-http://localhost:3000}
       - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
       - INTERNAL_API_SECRET=${INTERNAL_API_SECRET}
-      - REDIS_URL=${REDIS_URL:-}
+      - REDIS_URL=${REDIS_URL:-redis://redis:6379}
     depends_on:
       db:
         condition: service_healthy
+      redis:
+        condition: service_healthy
     healthcheck:
       test: ['CMD', 'curl', '-fsS', 'http://127.0.0.1:3002/health']
       interval: 90s
@@ -96,6 +101,20 @@ services:
     command: ['bun', 'run', 'db:migrate']
     restart: 'no'
 
+  # Backs pub/sub (live Chat task-status and table events) and the shared caches.
+  # The app falls back to PostgreSQL for storage when REDIS_URL is unset, but the
+  # pub/sub channels have no fallback — without Redis, live status never streams.
+  # Not published to the host: only the app and realtime containers need it, and
+  # binding 6379 would collide with a Redis already running locally.
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
   db:
     image: pgvector/pgvector:pg17
     restart: unless-stopped

scripts/setup/db.ts

@@ -9,6 +9,18 @@ import { glyph, theme } from './theme.ts'
 
 const DEFAULT_DSN = 'postgresql://postgres:postgres@localhost:5432/simstudio'
 
+/** Postgres' wire message when the password is wrong — a live server, not a dead one. */
+const AUTH_FAILURE = /password authentication failed/i
+
+/**
+ * Percent-encodes the password so characters that are structural in a URL
+ * (`@`, `:`, `/`, `#`, `?`) can't re-parse the DSN into a different host — which
+ * would fail a password that is actually correct.
+ */
+function buildDsn(password: string, hostPort: string | number): string {
+  return `postgresql://postgres:${encodeURIComponent(password)}@localhost:${hostPort}/simstudio`
+}
+
 export function docker(args: string[]): void {
   const result = spawnSync('docker', args, { encoding: 'utf8' })
   if (result.status !== 0) {
@@ -63,7 +75,9 @@ function inspectManagedContainer(): ManagedContainer | null {
 
   return {
     running: running === 'true',
-    dsn: `postgresql://postgres:${password}@localhost:${hostPort}/simstudio`,
+    // Read back from the container env verbatim, so it may be a password the
+    // user supplied for an existing volume — encode it like any other.
+    dsn: buildDsn(password, hostPort),
   }
 }
 
@@ -122,6 +136,81 @@ async function promptExternalDsn(): Promise<string> {
   }
 }
 
+const DB_VOLUME = 'sim-postgres-data'
+
+/** True once initdb has run in the volume — PG_VERSION only exists after bootstrap. */
+function volumeInitialized(): boolean {
+  if (spawnSync('docker', ['volume', 'inspect', DB_VOLUME], { stdio: 'ignore' }).status !== 0) {
+    return false
+  }
+  // Read the marker from inside the volume; the image is already local, so this
+  // costs nothing extra and beats assuming "volume exists" means "bootstrapped"
+  // (a failed first run leaves an empty volume behind).
+  return (
+    spawnSync(
+      'docker',
+      [
+        'run',
+        '--rm',
+        '-v',
+        `${DB_VOLUME}:/pgdata`,
+        '--entrypoint',
+        'test',
+        'pgvector/pgvector:pg17',
+        '-f',
+        '/pgdata/PG_VERSION',
+      ],
+      { stdio: 'ignore' }
+    ).status === 0
+  )
+}
+
+/**
+ * The volume already holds a cluster whose password we cannot read back. Either
+ * the user supplies it, or the data goes — silently generating a new password
+ * would produce a container that never authenticates.
+ */
+async function resolveExistingVolume(): Promise<string> {
+  p.log.warn(
+    `The ${DB_VOLUME} volume already contains a database, but its password is not recoverable — Postgres ignores POSTGRES_PASSWORD on an existing data directory.`
+  )
+  const choice = await p.select({
+    message: 'How should the wizard proceed?',
+    options: [
+      {
+        value: 'password',
+        label: 'Keep the data — I have its password',
+        hint: 'from a previous .env, or your notes',
+      },
+      {
+        value: 'wipe',
+        label: 'Delete the old data and start fresh',
+        hint: `removes the ${DB_VOLUME} volume — this cannot be undone`,
+      },
+    ],
+    initialValue: 'password',
+  })
+  if (choice === 'password') {
+    return p.password({
+      message: `Password for the existing ${DB_VOLUME} database`,
+      validate: (value) => (value ? undefined : 'required'),
+    })
+  }
+  const sure = await p.confirm({
+    message: theme.error(`Permanently delete the ${DB_VOLUME} volume and all its data?`),
+    initialValue: false,
+  })
+  if (!sure) {
+    throw new SetupError('kept the existing database volume, so setup cannot continue.', [
+      're-run and supply the password, or remove it yourself:',
+      theme.command(`docker volume rm ${DB_VOLUME}`),
+    ])
+  }
+  docker(['volume', 'rm', DB_VOLUME])
+  p.log.step(`Removed ${DB_VOLUME}`)
+  return generateSecret().slice(0, 24)
+}
+
 /**
  * Provisions the managed container, reconciling with one that already exists
  * rather than colliding on the name. Recreating is always an explicit choice —
@@ -142,15 +231,27 @@ async function startManagedContainer(detection: Detection): Promise<string> {
       throw new SetupError(`the existing ${DB_CONTAINER} container is not usable.`, [
         `inspect: ${theme.command(`docker logs ${DB_CONTAINER}`)}`,
         `remove it: ${theme.command(`docker rm -f ${DB_CONTAINER}`)}`,
-        `start clean: ${theme.command('docker volume rm sim-postgres-data')} drops its data too`,
+        `start clean: ${theme.command(`docker volume rm ${DB_VOLUME}`)} drops its data too`,
       ])
     }
     docker(['rm', '-f', DB_CONTAINER])
   }
 
-  const password = generateSecret().slice(0, 24)
   const hostPort = detection.postgresPortOpen ? 5433 : 5432
-  const dsn = `postgresql://postgres:${password}@localhost:${hostPort}/simstudio`
+  // POSTGRES_PASSWORD only applies when initdb runs on an empty data directory.
+  // The volume outlives the container (sim down keeps it, so does `docker rm`),
+  // so once the container is gone the password it was created with is
+  // unrecoverable — inspectManagedContainer reads it from the container, not the
+  // volume. Running with a freshly generated password against an initialized
+  // volume starts a healthy Postgres that rejects every connection with
+  // "password authentication failed", which surfaces as a bogus "container did
+  // not become healthy". Ask instead of guessing.
+  const password = volumeInitialized()
+    ? await resolveExistingVolume()
+    : generateSecret().slice(0, 24)
+  // A user-supplied password can contain @ : / # — raw interpolation would
+  // re-parse the DSN into a different host and fail a password that is correct.
+  const dsn = buildDsn(password, hostPort)
   docker([
     'run',
     '-d',
@@ -159,7 +260,7 @@ async function startManagedContainer(detection: Detection): Promise<string> {
     '--label',
     'managed-by=sim-setup',
     '-v',
-    'sim-postgres-data:/var/lib/postgresql/data',
+    `${DB_VOLUME}:/var/lib/postgresql/data`,
     '-e',
     `POSTGRES_PASSWORD=${password}`,
     '-e',
@@ -170,9 +271,31 @@ async function startManagedContainer(detection: Detection): Promise<string> {
   ])
   const spin = p.spinner()
   spin.start(`Starting ${DB_CONTAINER} container on :${hostPort}…`)
-  const healthy = await waitFor(async () => (await pgProbe(dsn)).ok, 45_000, 1500)
+  let lastError = ''
+  const healthy = await waitFor(
+    async () => {
+      const probe = await pgProbe(dsn)
+      if (!probe.ok) lastError = probe.error ?? ''
+      return probe.ok
+    },
+    45_000,
+    1500
+  )
   if (!healthy) {
     spin.stop(`${glyph.fail} container did not become healthy`)
+    // Postgres running and refusing the password is a different failure from
+    // Postgres never starting, and it is the likely one on the keep-the-volume
+    // path. Reporting it as "did not become healthy" is the exact confusion
+    // this whole change set exists to remove.
+    if (AUTH_FAILURE.test(lastError)) {
+      throw new SetupError(
+        `Postgres started, but rejected that password for the existing ${DB_VOLUME} volume.`,
+        [
+          're-run and enter the password the volume was created with',
+          `or discard the old data: ${theme.command(`docker rm -f ${DB_CONTAINER} && docker volume rm ${DB_VOLUME}`)}`,
+        ]
+      )
+    }
     const logs = spawnSync('docker', ['logs', '--tail', '20', DB_CONTAINER], { encoding: 'utf8' })
     throw new SetupError(
       `the Postgres container failed to start. Last logs:\n${logs.stdout}${logs.stderr}`,