Local development workflow

Keep localhost open while the code keeps changing.

Hronaut runs beside your editor and development server. A local coding agent can edit the app, reload the same visible tab, inspect failures, and keep isolated cookies and storage available after either the task or server restarts.

Run the local QA loop Connect your agent

Two separate services

The app and the control endpoint are not the same URL.

Website under test: http://localhost:3000
Hronaut MCP: http://127.0.0.1:47812/mcp
Use the real port printed by each process.

Same-device access

Your desktop browser can reach the server your cloud browser cannot.

A loopback address belongs to the device that opens it. Hronaut and a local coding agent run on the same computer as the development server, so the browser can open that server directly. In a hosted agent, remote VM, or container, localhost names that other environment unless you deliberately bridge it.

Local Hronaut

Direct and visible

The app remains in a real desktop window. You can watch a reload, inspect the exact failure, pause MCP, or take over the page without publishing the development server.

Hosted browser

A different loopback

A remote runtime sees its own 127.0.0.1, not yours. Tunnels can bridge that boundary, but they create a separate exposure and access-control decision.

A reproducible local QA loop

Keep one workspace; change one layer at a time.

1
Start on a fixed local port
Start the development server on loopback and note its exact printed URL. For Vite, use vite --host 127.0.0.1 --port 5173 --strictPort so a collision fails instead of silently moving the app to another origin.
2
Create a scratch workspace
Ask the agent to create a uniquely named workspace with clean scratch storage. Keep test accounts, feature flags, and service workers away from Default and from other tasks.
3
Open and observe the real page
Navigate to the exact local URL, wait for the expected UI, take a semantic snapshot, and interact with named controls. Watch the visible tab while the agent works.
4
Edit, restart, and reload in place
After code or server changes, reload the existing tab. If the server is briefly unavailable, Hronaut keeps the failed address visible and reports structured page-problem details so the agent can retry the same URL.

First local task

Give the agent an observable finish line

Create a scratch Hronaut workspace named local-check-<task>.
Open http://127.0.0.1:5173 and wait for the page heading.
Exercise the changed flow using semantic snapshots and refs.
Report the workspace ID, final URL, visible result, console errors,
and failed network requests. Do not use Default.

Replace the URL and finish condition with the values from your running app. A successful navigation alone does not prove the changed workflow.

State follows the origin

Keep scheme, hostname, and port stable when state should survive.

Browsers define an origin by its scheme, hostname, and port. http://localhost:5173, http://127.0.0.1:5173, and http://localhost:5174 are different origins, so their local storage and IndexedDB do not merge.

Survives a server restart

Profile-owned state

Cookies, local storage, IndexedDB, service workers, and cache live in the workspace's persistent Electron session rather than the development-server process. Best-effort web storage can still be evicted or cleared, and cookie expiration rules still apply.

Belongs to one page session

Session storage

Session storage is tab-specific. Do not treat it as durable after a tab or application restart recreates the page; use the same live tab while a reproduction depends on that state.

Clean reproduction

Scratch workspace

Start with no copied site data when testing onboarding, first-run behavior, or authorization failures. The workspace remains isolated from Default and every other named workspace.

Intentional reuse

Fork only known origins

Use fork-default only when the task truly needs reusable state, and limit the one-time copy to the relevant origin. It is not a live connection to Default.

Failure matrix

Match the symptom to the next diagnostic.

Symptom	First evidence	Next Hronaut action
Connection refused	Development server stopped, wrong host, or wrong port.	Read the server's printed URL, check `pageProblem`, then retry the exact address after the server is listening.
Old UI after a fix	HTTP cache or a service worker may still answer requests.	Reload ignoring cache, then inspect service-worker and Cache Storage metadata before clearing only that workspace's site data.
Login or flags disappeared	The hostname, port, workspace, cookie lifetime, or storage was changed.	Compare the exact origin and inspect bounded cookies, local storage, session storage, and storage changes.
UI loads; request fails	The browser reached the app, but an API, CORS, or application path failed.	Inspect bounded Network and Console records and reproduce one request without assuming navigation was the failure.
Only one viewport breaks	The defect depends on CSS pixels, DPR, touch, orientation, or media preferences.	Use responsive preview or tab-scoped emulation, then capture the failing element or visual diff at the same viewport.

Use the right test layer

Visible exploratory QA complements repeatable CI.

Hronaut is strongest when browser context must remain visible and available between tasks: reproducing a reported issue, preserving a development login, inspecting storage transitions, or handing a surprising state to a person. It is Chromium-only and does not replace deterministic unit, integration, or cross-browser tests.

Choose Hronaut

Long-lived investigation

Use the same named workspace while code, tasks, and the local server restart. Review console, network, storage, accessibility, performance, responsive, screenshot, and visual-comparison evidence in one visible browser.

Choose a test runner

Automated release gate

Use Playwright or another runner for isolated assertions, parallel CI, traceable retries, and required Firefox or WebKit coverage. Turn every confirmed regression into a repository test.

Local does not mean harmless

Keep the development surface on the machine.

Loopback HTTP origins such as localhost and 127.0.0.1 are potentially trustworthy so developers can use secure-context APIs locally. That convenience is not a production security guarantee. Development servers can expose source maps, test-only routes, unbuilt code, and powerful hot-reload channels.

Bind the app to loopback when Hronaut runs on the same computer. Do not use 0.0.0.0, permissive host allowlists, or a public tunnel unless the task explicitly needs network access and you have added authentication. Use test data and development accounts, keep Hronaut authentication enabled for sensitive profiles, and pause MCP for human-only secrets.

Primary sources

Browser state, loopback, and product evidence.

Hronaut agent-workspace reference — persistent partitions, scratch and forked storage, workspace ownership, page recovery, and browser tools.
MDN origin definition — the scheme, hostname, and port tuple that separates web storage.
MDN browser-storage persistence — per-origin storage, best-effort retention, and eviction boundaries.
MDN secure contexts — why HTTP loopback origins can be treated as potentially trustworthy for local development.
MDN loopback address space — loopback is accessible only on the local device.
Electron persistent sessions — persist: partitions retain browser-session data on disk.
Vite server options — loopback defaults, fixed-port behavior, wildcard binding, host allowlists, and DNS-rebinding warnings.
Playwright browser coverage — Chromium, Firefox, and WebKit automation for repeatable cross-browser gates.

One tab through many edits

Keep the reproduction visible until the regression test is green.

Create a scratch workspace, use one exact origin, preserve the failing tab, and collect the smallest useful evidence before changing code. After the fix, repeat the same flow in Hronaut and add the automated regression to the application repository.

Download Hronaut Connect your agent Troubleshoot MCP