Summary

After running setup archon on a fresh Windows 11 machine, bun run dev brings up the Vite web UI at http://localhost:5173/ but every API call fails with ECONNREFUSED. UI shows red "Failed to load conversations / Failed to load projects". Root cause is a silent port-default mismatch that only triggers when .env is absent.

Environment

• OS: Windows 11 Pro 10.0.26200
• Shell: MINGW64 (Git Bash) and PowerShell both reproduce
• Archon: v0.3.6, source build (Build: source (bun)) — installed via setup archon wizard from a local clone of coleam00/Archon
• Runtime: Bun 1.3.x
• Data dir: %USERPROFILE%\.archon\archon.db (SQLite)

Reproduction

1. Clone coleam00/Archon, run setup archon (completes cleanly).
2. setup archon does not copy .env.example → .env.
3. Start dev: cd <Archon repo> && bun run dev.
4. Open http://localhost:5173/chat.

Observed

• Web UI renders header + sidebar.
• Red banners: Failed to load conversations, Failed to load projects.
• Vite log spam: [vite] http proxy error: /api/conversations — AggregateError [ECONNREFUSED].
• Nothing is listening on :3090.
• @archon/server started successfully, bound to :3000 (matches PORT=3000 in .env.example).

Root cause

Two defaults in play when .env is missing:

• packages/server/src/index.ts: server defaults to PORT=3000 (unset → fallback in code; matches .env.example line 122).
• packages/web/vite.config.ts:

  const apiPort = env.PORT ?? '3090';

  With no .env, env.PORT is undefined → Vite proxies /api/* to http://localhost:3090. Server is on :3000. Silent mismatch.

Neither side surfaces the mismatch; only visible symptom is the API errors in the UI.

Possible fixes

1. Setup wizard copies .env.example → .env if absent — matches the existing Hint: Copy .env.example to .env and configure your credentials. line already printed by the server on startup.
2. Align Vite fallback to match the server default: const apiPort = env.PORT ?? '3000';.
3. Dev-mode health check — on bun run dev, Vite probes the proxied API port post-startup and warns loudly if nothing responds.

#1 is probably best — also puts GH_TOKEN, WEBHOOK_SECRET, etc. in one place instead of requiring users to discover they need to create .env manually.

Workaround

cp <Archon repo>/.env.example <Archon repo>/.env
# restart bun run dev