Skip to main content

yarn dev:ephemeral

yarn dev:ephemeral starts Open Saasframe development mode on a free local port with a dedicated ephemeral PostgreSQL container, prints the runtime URLs, and opens the same splash status screen used by the regular dev flow so startup progress stays visible until the app is reachable.

The command performs these steps automatically:

  1. Validates Node.js 24.x (fails early with fix instructions when incompatible).
  2. Creates apps/saasframe/.env from apps/saasframe/.env.example only when missing.
  3. Runs yarn install.
  4. Runs yarn build:packages to ensure CLI generators are up to date.
  5. Runs yarn generate to prepare .saasframe/generated files.
  6. Starts a disposable PostgreSQL container and resolves a unique DATABASE_URL.
  7. Runs yarn initialize -- --reinstall against that ephemeral database.
  8. Selects a random free app port in the 5000-65535 range.
  9. Starts the app runtime with PORT=<selected-port> and ephemeral DATABASE_URL, forwarding status into the splash screen.
  10. Waits for readiness and records the running instance in .ai/dev-ephemeral-envs.json.

Usage​

yarn dev:ephemeral

Runtime Output​

When setup finishes, the command prints:

  • Ephemeral URL: http://127.0.0.1:<port>
  • Backend URL: http://127.0.0.1:<port>/backend
  • Ephemeral PostgreSQL URL: postgresql://...@127.0.0.1:<port>/<db>
  • Opened browser at http://127.0.0.1:<port>/backend

Use that URL for browser testing or MCP tooling.

If auto-open is enabled, the browser opens the local splash status page first. Once runtime warmup finishes, use the ready actions there or navigate directly to the printed backend URL.

Dev Instance Registry​

yarn dev:ephemeral writes active instances to .ai/dev-ephemeral-envs.json.

  • Every launch validates existing entries and removes stale/non-responsive instances.
  • New instances are added with pid, app port, base URL, backend URL, PostgreSQL container ID, DB port, DB URL, worktree cwd, and timestamp.
  • Entries are removed automatically when the related dev process exits.

Parallel Instances​

Run the command from multiple worktrees to keep isolated app processes on different ports:

# In worktree A
yarn dev:ephemeral

# In worktree B
yarn dev:ephemeral

Each process auto-selects its own free port.

Optional Environment​

VariableDescription
DEV_EPHEMERAL_PREFERRED_PORTOptional fixed port override. Must be in 5000-65535; otherwise it is ignored and a random free port is used.
DEV_EPHEMERAL_POSTGRES_IMAGEOptional Docker image for ephemeral PostgreSQL. Default: postgres:16.
DEV_EPHEMERAL_POSTGRES_USEROptional PostgreSQL user for ephemeral DB. Default: postgres.
DEV_EPHEMERAL_POSTGRES_PASSWORDOptional PostgreSQL password for ephemeral DB. Default: postgres.

Verbose Mode​

yarn dev:ephemeral:verbose

This keeps the app runtime in raw passthrough mode while still using the splash screen for the ephemeral setup stages.

Classic Mode​

yarn dev:ephemeral:classic

This disables the splash screen entirely and keeps the full ephemeral startup flow in raw passthrough mode for backward-compatible terminal output.