run-dev-instance

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

make 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:

bun scripts/dev-ports.mjs --json

Run it in the background and wait for the port rather than a fixed sleep:

PORT=$(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:

bun 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):

lsof -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.