Skip to content

shared-dev-server.md

Latest commit

 

History

History
47 lines (30 loc) · 2.22 KB

shared-dev-server.md

File metadata and controls

47 lines (30 loc) · 2.22 KB
Raw

Shared dev server for concurrent lanes

Parallel worktrees should not all bind the default app UI port (2138). The app Vite config uses strictPort: true, so a second server on the same port fails instead of auto-incrementing. Use the shared dev-server scripts when multiple agents or lanes are active on the same VPS.

Commands

bun run --cwd packages/app dev:shared   # long-lived Vite server on this worktree's deterministic port
bun run --cwd packages/app dev:status   # list running shared dev servers from the registry
bun run --cwd packages/app dev:rebuild  # explicit Vite full-reload trigger for this worktree

bun run dev is unchanged for single-lane local development.

Port contract

dev:shared reserves a deterministic port from the worktree path and stores the reservation in ~/.eliza/dev-server-registry.json (override with ELIZA_DEV_SERVER_REGISTRY). The UI port is allocated from 2100-2999; the paired API port is uiPort + 10000. If two worktrees hash to the same port, the registry lock linear-probes to the next free port, so active lanes stay distinct.

The script exports ELIZA_UI_PORT and ELIZA_API_PORT before starting Vite, then records the Vite pid. dev:status checks both pid liveness and whether the UI port is open.

Rebuild trigger

dev:rebuild is intentionally explicit. It requires a running shared server for the current worktree, then updates packages/app/index.html mtime. Vite watches the HTML shell and broadcasts a full reload to connected clients. This gives agents a cheap, composable "refresh now" hook without each lane starting another server.

VPS workflow

  1. Pick or create the worktree for your lane.

  2. Start one long-lived server:

    bun run --cwd packages/app dev:shared

  3. In another shell, discover the URL:

    bun run --cwd packages/app dev:status

  4. Point the Cloudflare tunnel, browser, or installed PWA live-reload URL at that lane's UI port.

  5. After source/build state changes that need a visible refresh, run:

    bun run --cwd packages/app dev:rebuild

If a stale process dies, dev:status hides it by default; use bun run --cwd packages/app dev:status -- --all to inspect stopped registry entries.