How to use the Run Dozzle Dev Instance agent skill

What the skill makes the agent do

Dozzle is a log viewer for Docker containers. When a change needs checking by hand, such as clicking through the UI, taking screenshots, or driving the page with Chrome or Playwright, the agent needs a running instance to point at. This skill tells the agent how to start one.

The skill assigns the instance a port derived from the current checkout's path. If that port is taken, it moves forward until it finds a free one. Each worktree therefore keeps the same URL, and several worktrees can run at once without clashing. The skill also states that the agent should never assume the default port 3100 is its own, and should never stop an instance it did not start.

Install the skill

Option one: download the ZIP from this page and unzip it into ~/.claude/skills/ to make the skill available in all your projects. To limit it to one project, unzip it into that project's .claude/skills/ folder instead.

Option two: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

Ask for it with a natural request

You do not need to type the skill name. The skill's description tells the agent when to use it, so ask for what you need in ordinary words. The skill is meant for requests where Dozzle must be running in a browser to test a change by hand.

Examples of requests that match its purpose: asking the agent to start Dozzle and check that a new button works in the browser, to take screenshots of a UI change, or to drive the page with Chrome or Playwright and report console errors.

• Check my UI change in the browser and tell me if the layout breaks.
• Start a Dozzle dev instance and take screenshots of the container list.
• Use Playwright to click through the settings page and report any console errors.

Start and wait for the server

The skill starts the dev server with make dev-auto, which runs air and vite with hot reload. The command prints the URL before anything else, in this form: the Dozzle port, then the vite and agent ports in brackets. To find the URL without starting anything, the agent can run the port script with the json flag.

For a one-off check of code that is already written, the skill suggests a production build instead, which has no vite part. The agent waits for the port to respond rather than sleeping for a fixed time.

• Hot reload suits active iteration on a change.
• A production build is steadier for a single check.

Drive the page and watch for errors

For a visible session where you want to watch, the skill uses the Chrome extension. For anything scripted or repeatable, it uses Playwright from node_modules with browsers already cached. The skill notes that Playwright is also the only way to simulate a broken clipboard, a missing API, or an offline stream.

The agent should watch the browser console for errors throughout the test, not only at the end.

Stop only the server you started

The skill says to kill only the process the agent started, either the background task or the process listening on its own port. Other ports are left alone. If a port the agent wanted is taken by another worktree, the agent should not free it, because the port script has already moved to the next free one.

Overrides and other ports

The variables DOZZLE_PORT, VITE_PORT and AGENT_PORT override the ports for make dev, make dev-auto, bun run preview and bun run agent:dev. Plain make dev still uses 3100, 5173 and 7007, which are the ports a person starting the server by hand expects. The Go server finds the Vite address through viteDevURL() in internal/web/index.go, so setting VITE_PORT is enough.