Run a Dozzle instance for testing
Several worktrees are usually checked out at once and more than one of them may already be serving. Never assume 3100 is yours — it almost certainly belongs to another worktree, and killing it kills someone else's session.
Start one
bashmake dev-auto # backgrounded; see below
It prints the URL before anything else:
▸ dozzle dev on http://localhost:3356 (vite 5502, agent 7136)
The ports come from scripts/dev-ports.mjs, hashed from this checkout's path and then
walked forward until free, so this worktree always gets the same URL and two
worktrees never land on the same one. To know the URL without starting anything:
bashbun scripts/dev-ports.mjs --json
Run it in the background and wait for the port rather than a fixed sleep:
bashPORT=$(bun scripts/dev-ports.mjs --json | grep -o '"DOZZLE_PORT": [0-9]*' | grep -o '[0-9]*') # start make dev-auto with run_in_background, then: until curl -sf -o /dev/null http://localhost:$PORT/; do sleep 1; done
make dev-auto is air + vite with hot reload, which is what you want while iterating
on a change. For a one-shot check of already-written code, a production build is steadier
and has no vite half:
bashbun run build && LIVE_FS=true go run . --level info --addr localhost:$PORT
Overriding
DOZZLE_PORT, VITE_PORT and AGENT_PORT override any of the three, for make dev,
make dev-auto, bun run preview and bun run agent:dev alike. Plain make dev still uses
3100/5173/7007, which is what a human starting one by hand expects, and is deliberately
outside the auto-assigned ranges.
The Go server tells the dev page where Vite lives (viteDevURL() in
internal/web/index.go, read by public/index.html), so VITE_PORT is all that needs
setting — there is no hardcoded 5173 left.
While testing
- Containers to look at: whatever is running locally (
docker ps). No need to start any. - Drive it with the Chrome extension (
mcp__claude-in-chrome__*) when the user wants to watch, or with Playwright (node_modules/playwright, browsers already cached) for anything scripted or repeatable. Playwright is also the only way to fake a broken clipboard, a missing API, or an offline stream. - Watch the console for errors the whole way through, not just at the end.
Stop it
Kill only the process you started (the background task, or the PID on your port):
bashlsof -tiTCP:$PORT -sTCP:LISTEN
Leave every other port alone. If a port you wanted is taken by another worktree, the script has already moved past it — do not free it.
