feat(setup): setup wizard with browser-based Chat key handoff by TheodoreSpeaks · Pull Request #5911 · simstudioai/sim

TheodoreSpeaks · 2026-07-24T00:25:45Z

Summary

bun run setup — interactive first-run wizard (--quick, --mode compose|dev|k8s); bun run doctor [--fix] [--json] validates an existing install. Run-mode picker names who each mode is for: compose (self-host/evaluate), dev (contribute), k8s (rehearse a prod deploy)
CLI auth via the OAuth device-authorization flow. The CLI generates a request id + poll secret, opens /cli/auth, and polls /api/cli/auth/poll over TLS while the user approves in the browser. No loopback listener, so it works over SSH and inside containers. No key ever crosses the browser
A pairing code shown in both terminal and browser is the anti-phishing compare — the poll secret binds the key to the CLI process, but only the code tells the user the page is theirs
Approvals live in Redis (120s TTL, hashed key, single-use via verify-then-atomic-claim); poll verifies the secret before deleting, so an observer of the semi-public request id can neither mint nor cancel
Doctor understands both env layouts (compose writes a single root .env; dev writes the three per-app files) — a healthy compose install no longer reports false failures
Setup reuses an existing managed Postgres/Redis container (reads port + password back from Docker) instead of colliding on the name; k8s deploys pin the validated kube-context and pipe secrets to helm on stdin, never argv
Signup now honours callbackUrl like signin, so a new account returns to the CLI flow

Type of Change

New feature

Testing

Device-flow poll verified end-to-end against a local server + Redis (pending → approve →
consume-once; wrong-secret returns pending and does not delete the approval). Unit tests cover
the approval store and both routes; the container-reuse recovery and doctor layout were run
against a live Docker/env. bun run lint, check:api-validation:strict, check:react-query,
check:client-boundary, type-check, and the unit suites pass. The wizard's mode flows
(compose/dev/k8s) aren't exercised by automated checks.

Checklist

Code follows project style guidelines
Self-reviewed my changes
Tests added/updated and passing
No new warnings introduced
I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Adds `bun run setup` and `bun run doctor` for local installs, and replaces the wizard's paste-your-Chat-key step with a browser handoff that never puts the key in a URL.

vercel · 2026-07-24T00:25:52Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 25, 2026 7:59am

cursor · 2026-07-24T00:25:55Z

PR Summary

High Risk
Touches authentication redirects, Redis-required CLI key minting, and secret generation in setup/k8s paths—misconfiguration or approval-store bugs could block CLI login or leak keys; large new surface with limited automated coverage of wizard modes.

Overview
Introduces bun run setup (interactive wizard for compose, local dev, or k8s) and bun run sim for doctor, start/stop, logs, and reset, replacing the README’s manual Docker/env steps. Compose files now optionally load a root .env.

Adds CLI authentication without a loopback listener: the CLI opens /cli/auth, the user approves with a pairing code, and /api/cli/auth/poll mints a Chat API key after Redis-backed approval (session-only approve, verifier-gated poll, mint lock). Setup can run the same browser handoff to store COPILOT_API_KEY. Chat key CRUD is centralized in lib/copilot/server/api-keys and reused by the CLI poll path.

Auth now preserves callbackUrl across login/signup via buildAuthCrossLink, stores a single postAuthRedirectUrl for signup→verify (fixing redirect races and stale CLI destinations), and validates /cli/auth before login bounce.

Chat keys move from workspace/account nav to /account/settings/chat-keys (hosted only); the settings sidebar no longer highlights unrelated sections on that nested route.

^{Reviewed by Cursor Bugbot for commit c1f81d8. Bugbot is set up for automated code reviews on this repo. Configure here.}

greptile-apps · 2026-07-24T00:30:04Z

Greptile Summary

Adds an interactive setup and diagnostics CLI with Docker Compose, development, and Kubernetes modes.

Implements a browser-assisted CLI authentication flow backed by single-use Redis approvals.
Adds environment generation, service provisioning, lifecycle management, and installation health checks.
Preserves post-authentication destinations across login, signup, and email verification.
Adds Chat API-key management routes and account settings.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failures remain within the scope of the previous review threads.

Important Files Changed

Filename	Overview
scripts/setup/lifecycle.ts	Adds installation detection and lifecycle operations while pinning Kubernetes operations to the detected context and correctly reporting failed reset uninstalls.
scripts/setup/modes/k8s.ts	Implements local Kubernetes setup with validated context pinning, stdin-delivered Helm values, and safely quoted diagnostic commands.
scripts/setup/cli-auth.ts	Implements browser launch and polling for the device-style Chat key handoff.
apps/sim/lib/cli-auth/approval-store.ts	Implements expiring, verifier-bound, single-use CLI approvals in Redis.
apps/sim/app/(auth)/verify/use-verification.ts	Carries validated post-auth destinations through email verification and consumes stored redirects after use.
scripts/setup/doctor.ts	Adds diagnostics and repair support for the setup wizard’s supported environment layouts.

Sequence Diagram

sequenceDiagram
participant CLI as Setup CLI
participant Browser
participant Sim as Sim API
participant Redis
CLI->>CLI: Generate request ID and poll secret
CLI->>Browser: Open /cli/auth with request ID and challenge
Browser->>Sim: Authenticate and approve pairing
Sim->>Redis: Store approval with challenge and TTL
loop Until approved or expired
CLI->>Sim: Poll with request ID and secret
Sim->>Redis: Verify challenge and atomically claim approval
end
Sim-->>CLI: Return generated Chat API key once

_{Reviews (13): Last reviewed commit: "fix(setup,auth): manage explicitly-confi..." | Re-trigger Greptile}

The browser handoff is now the only path — the wizard waits on a spinner instead of racing a paste prompt. Consent card leads with "Connect your terminal" and moves the match-the-code disclaimer into the description.

…ed keys Review findings from #5911: - helm/kubectl now run against the validated context instead of the ambient one - helm values are piped on stdin rather than passed as --set arguments - ENCRYPTION_KEY/API_ENCRYPTION_KEY are checked for the 64-hex format the app requires, not just length, so an unusable key is replaced rather than kept - the managed Redis container's published port is read back instead of assumed

TheodoreSpeaks · 2026-07-24T00:56:04Z

@greptile

TheodoreSpeaks · 2026-07-24T00:56:05Z

@cursor review

list/generate/delete each repeated the same /api/validate-key envelope in their route. They now share callValidateKey in lib/copilot/server/api-keys.ts, which also keeps the display masking server-side so the full key can only ever leave at creation.

…ad code - PKCE verifier/state/pairing code now use generateSecureToken, generateRandomHex and generateShortId instead of hand-rolled randomBytes; the pairing loop's modulo was unbiased only because 256 % 32 == 0 - new sha256Base64Url in @sim/security/hash so both sides of the PKCE exchange derive the challenge from one implementation - isUsableSecret moved beside SECRET_KEYS so setup and doctor apply the same rule; doctor previously passed a key setup would replace - isTruthy narrowed to true/1, matching the app it claims to mirror — it accepted yes/on, so a flag could read on in doctor and off in the app - checkLive runs its five probes concurrently (~17s serial worst case) - detection overlaps the banner animation instead of queueing behind it - glyph.fail/glyph.warn at 13 sites that bypassed the constant; removed unused prompter exports, a dead ENV_PATHS re-export, and an unused export keyword

Compose writes a single root .env (what docker-compose reads via env_file) but the checks required the three per-app files, so a successful compose install was followed by doctor printing three failures and exiting 1 — and the whole coherence catalog was skipped because it keyed off apps/sim/.env existing. Layout is now derived from what's on disk and every check consults it: file and schema checks iterate the layout's targets, consistency reports skip when there's only one file to mirror, and coherence/live read the layout's primary file. The wizard's existing-config detection counts root for the same reason — a compose install used to read as unconfigured and re-run from scratch.

…tener The CLI no longer binds a local port. It generates a request id + poll secret, opens /cli/auth, and polls /api/cli/auth/poll over TLS while the user approves in the browser — so the flow works over SSH and inside containers, where the browser and terminal don't share a machine. - approve stores the approval keyed by request id (session-authed, userId from the session only); poll verifies the secret before an atomic claim, so an observer of the semi-public request id can neither mint nor cancel it - pairing code stays as the anti-phishing compare; no key ever crosses the browser; done page just confirms - removes the loopback listener, /token exchange, buildCliHandoffUrl, and validateCliCallbackUrl (+ its tests) — nothing hands a key to a URL anymore

…olliding A running sim-postgres fell through to `docker run --name sim-postgres` and died on the name conflict; a stopped one failed with "no DATABASE_URL to reach it" because the generated password only lived in the env files a fresh clone lacks. Both facts are recoverable from Docker: the ladder now reads the published port and password back via `docker inspect` and reuses the container (starting it if stopped). A container that won't answer prompts before recreating, and never drops the data volume silently.

Each run mode now names who it's for — compose for self-hosting/evaluating, dev for contributing to Sim, k8s for rehearsing a production deploy — with the live detection state (Docker/kube/VM) appended.

# Conflicts: # package.json # scripts/check-api-validation-contracts.ts

TheodoreSpeaks · 2026-07-24T18:50:03Z

@greptile

TheodoreSpeaks · 2026-07-24T18:50:04Z

@cursor review

TheodoreSpeaks · 2026-07-25T01:16:28Z

@greptile

TheodoreSpeaks · 2026-07-25T01:16:29Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit a25efdc. Configure here.}

…try-After The poll route used the default public-IP bucket (10 burst, 5/min) but the CLI polls every 2s (30/min), so it 429'd within ~20s — worse behind a slow dev cold-compile. Give the endpoint a bucket matched to its cadence (60 burst, 60/min); it's not a brute-force surface (unknown request id returns pending, minting needs the 256-bit verifier). Also make the CLI honor Retry-After and back off on 429 so a shared-NAT per-IP limit degrades gracefully instead of hammering.

Local dev auto-start spawned bun run dev:full with no port check, so it silently started a server that couldn't bind when 3000/3002 were already taken (e.g. another worktree's dev server). Extract compose's port-conflict resolver into a shared ensurePortsFree(ports) and run it before the dev start too — kill/recheck/leave, same as compose. Leaving the ports skips the auto-start with guidance instead of failing; compose still treats it as fatal.

A kubeconfig context can outlive its cluster — a kind cluster gets deleted or its Docker container stops (Docker/machine restart), but the context entry remains, pointing at a dead API-server port. The wizard checked the context looked local and handed it to helm, which failed with 'cluster unreachable'. Add a clusterReachable() liveness probe: only offer the current context when it actually answers; if a local context is dead, fall through to the kind path. There, if kind still knows 'sim' but it's stopped, start its node containers and wait for the API; if it's gone, create fresh. Either way the user gets a working cluster instead of a cryptic helm failure.

…ent) The chart's appVersion was "0.6.73", but CI publishes GHCR tags with a v prefix (its release-commit regex captures v0.7.45). Since sim.image defaults every image tag to Chart.AppVersion, a default helm install requested ghcr.io/simstudioai/{simstudio,realtime,migrations}:0.6.73 — a tag that has never existed — so app and realtime sat in ImagePullBackOff and helm --wait failed with 'progress deadline exceeded'. Any self-hoster installing with default values hit this, not just the setup wizard. Set appVersion to v0.7.45 (latest release on main; all three images verified present on ghcr) and bump the chart version to 1.1.1. Verified with helm lint, helm template (all images render as v0.7.45), and a live helm upgrade on a kind cluster where the new pods pull successfully while the old 0.6.73 pods remain in ImagePullBackOff.

…ed, current)" This reverts commit 28b6047.

Staging moved the baseline to 975; this branch's two CLI-auth routes (approve, poll) make 977. The clean merge absorbed the earlier +2 adjustment.

TheodoreSpeaks · 2026-07-25T07:32:31Z

@greptile

TheodoreSpeaks · 2026-07-25T07:32:32Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 108f777. Configure here.}

…pages /account/settings/chat-keys is a real page but deliberately not a nav item, so the sidebar's parseSettingsPathSection fell through to defaultSection ('general') and highlighted General — the page read as though it lived inside General. Resolve the sidebar's active item with a null default so an unmatched nested route highlights nothing, and widen SettingsSidebar's activeSection to string | null. The section feeding the title/description provider keeps its default (pages override title/description anyway), and /account/settings/billing/credit-usage still correctly highlights Billing.

…y on reset, clear stale post-auth redirect - lifecycle: detection is now factual — a sim-dev release either exists on the current context or it doesn't. Gating on locality stranded a release the user explicitly confirmed during setup (status/start/stop/down/reset all claimed no k8s install). Locality is recorded instead and surfaced through describeInstall, which every destructive confirm renders, so acting on a non-local cluster is named and defaulted to no rather than silently blocked or silently allowed. - lifecycle: reset no longer discards helm uninstall's exit status. Env files are archived by that point, so claiming 'Reset complete' while the release still runs is the worst outcome — it now throws with retry/inspect commands. - auth: signup clears POST_AUTH_REDIRECT_STORAGE_KEY when it has no callbackUrl, and the verification-disabled path consumes it, so a stale CLI/invite destination can't leak into a later flow in the same tab.

TheodoreSpeaks · 2026-07-25T07:53:51Z

@greptile

TheodoreSpeaks · 2026-07-25T07:53:52Z

@cursor review

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c1f81d8. Configure here.}

feat(setup): setup wizard with browser-based Chat key handoff
9a9132e
Adds `bun run setup` and `bun run doctor` for local installs, and replaces the wizard's paste-your-Chat-key step with a browser handoff that never puts the key in a URL.

TheodoreSpeaks requested a review from a team as a code owner July 24, 2026 00:25

cursorBot reviewed Jul 24, 2026
View reviewed changes

Comment threadscripts/setup/redis.ts
Comment threadscripts/setup/cli-auth.ts

greptile-appsBot reviewed Jul 24, 2026
View reviewed changes

Comment threadscripts/setup/modes/k8s.ts Outdated
Comment threadscripts/setup/steps.ts Outdated
Comment threadscripts/setup/modes/k8s.ts Outdated

vercelBotdeployed to Preview July 24, 2026 00:30 View deployment

cursorBot reviewed Jul 24, 2026
View reviewed changes

Comment threadapps/sim/app/(auth)/verify/use-verification.ts

vercelBotdeployed to Preview July 24, 2026 00:54 View deployment

cursorBot reviewed Jul 24, 2026
View reviewed changes

Comment threadscripts/setup/checks.ts
Comment threadscripts/setup/checks.ts
Comment threadapps/sim/app/(auth)/login/login-form.tsx

vercelBotdeployed to Preview July 24, 2026 01:00 View deployment

TheodoreSpeaks added 3 commits July 23, 2026 19:55

vercelBotdeployed to Preview July 24, 2026 03:03 View deployment

TheodoreSpeaks added 3 commits July 24, 2026 11:42

improvement(setup): audience-first run-mode hints
9db7998
Each run mode now names who it's for — compose for self-hosting/evaluating, dev for contributing to Sim, k8s for rehearsing a production deploy — with the live detection state (Docker/kube/VM) appended.

cursorBot reviewed Jul 24, 2026
View reviewed changes

Comment threadapps/sim/app/api/cli/auth/poll/route.ts

vercelBotdeployed to Preview July 24, 2026 18:48 View deployment

Merge remote-tracking branch 'origin/staging' into feat/cli-auth-key
e00b02d
# Conflicts: # package.json # scripts/check-api-validation-contracts.ts

greptile-appsBot reviewed Jul 24, 2026
View reviewed changes

Comment threadscripts/setup/modes/k8s.ts Outdated
Comment threadscripts/setup/steps.ts

cursorBot reviewed Jul 24, 2026
View reviewed changes

Comment threadscripts/setup/redis.ts