docs(agent-instructions): broaden dev-server host/origin guidance #30

Closed

lz wants to merge 1 commit from fix/agent-instructions-dev-server-hosts into main

lz commented

2026-05-26 21:55:45 +02:00

Owner

Addresses the post-merge comment on #22.

Summary

The bundled default CLAUDE.md previously mentioned only Vite's Blocked request. This host is not allowed. failure mode. With the preview proxy in #21, the same class of failure manifests across most modern dev servers (Next.js HMR socket rejected as cross-origin, CRA's webpack-dev-server, etc.) — and the operator's hostname can be anything from localhost to a custom DNS like devops.lan, never 127.0.0.1.

Replaces the narrow Vite paragraph with a #### Dev-server host/origin checks subsection that:

Explains the principle (operator's browser → operator's hostname → dev-server host/origin allowlist must include it).
Tells agents to configure BEFORE starting the dev server.
Lists explicit recipes for Vite (server.allowedHosts: true, server.hmr.host), SvelteKit/Astro/Nuxt/Remix (Vite-based), Next.js ≥ 15.2 (allowedDevOrigins top-level), CRA/webpack-dev-server (WDS_SOCKET_HOST / allowedHosts: 'all').
Falls back to "ask the operator" for cases where a wildcard isn't supported (Next.js).

Scope

Documentation-only — no behavior change. DEFAULT_HASH is recomputed from file content at runtime, so no constant to bump. Existing agent-instructions tests still pass (19/19).

Not done here (open follow-up)

The PR #22 comment asked for the proxy hostname to be injected into CLAUDE.md, not just documented. This change reduces but doesn't fully eliminate the discovery round-trip — Next.js still requires the exact hostname. Closing the gap would mean an operator_hostname instance setting + seed-time placeholder substitution. Left for a follow-up if desired.

Test plan

pnpm --dir nexus exec vitest run src/lib/server/agent-instructions/ → 19/19 pass
Smoke: spawn a fresh Nexus instance, confirm the new section appears in the seeded ~/.claude/CLAUDE.md and in /settings?tab=agent-instructions.

Addresses the post-merge comment on #22. ## Summary The bundled default `CLAUDE.md` previously mentioned only Vite's `Blocked request. This host is not allowed.` failure mode. With the preview proxy in #21, the same class of failure manifests across most modern dev servers (Next.js HMR socket rejected as cross-origin, CRA's webpack-dev-server, etc.) — and the operator's hostname can be anything from `localhost` to a custom DNS like `devops.lan`, never `127.0.0.1`. Replaces the narrow Vite paragraph with a `#### Dev-server host/origin checks` subsection that: - Explains the principle (operator's browser → operator's hostname → dev-server host/origin allowlist must include it). - Tells agents to configure BEFORE starting the dev server. - Lists explicit recipes for Vite (`server.allowedHosts: true`, `server.hmr.host`), SvelteKit/Astro/Nuxt/Remix (Vite-based), Next.js ≥ 15.2 (`allowedDevOrigins` top-level), CRA/webpack-dev-server (`WDS_SOCKET_HOST` / `allowedHosts: 'all'`). - Falls back to "ask the operator" for cases where a wildcard isn't supported (Next.js). ## Scope Documentation-only — no behavior change. `DEFAULT_HASH` is recomputed from file content at runtime, so no constant to bump. Existing `agent-instructions` tests still pass (19/19). ## Not done here (open follow-up) The PR #22 comment asked for the proxy hostname to be **injected** into CLAUDE.md, not just documented. This change reduces but doesn't fully eliminate the discovery round-trip — Next.js still requires the exact hostname. Closing the gap would mean an `operator_hostname` instance setting + seed-time placeholder substitution. Left for a follow-up if desired. ## Test plan - [x] `pnpm --dir nexus exec vitest run src/lib/server/agent-instructions/` → 19/19 pass - [ ] Smoke: spawn a fresh Nexus instance, confirm the new section appears in the seeded `~/.claude/CLAUDE.md` and in `/settings?tab=agent-instructions`.

lz added 1 commit

2026-05-26 21:55:45 +02:00

docs(agent-instructions): broaden dev-server host/origin guidance

ci / nexus (pull_request) Successful in 2m17s

Details

ci / images (./nexus, agent-nexus) (pull_request) Successful in 3m48s

Details

ci / images (./worker, nexus-worker) (pull_request) Successful in 1m8s

Details

5ed6d11056

Replace the narrow Vite-only paragraph with a Dev-server host/origin
checks subsection that explains the principle (operator's browser
carries the operator's hostname, not 127.0.0.1) and lists recipes for
Vite, SvelteKit/Astro/Nuxt/Remix, Next.js >=15.2, and CRA/webpack-dev-server.

Addresses the feedback on PR #22: pre-warn agents about
allowedDevOrigins / allowedHosts / WDS_SOCKET_HOST so dev-server origin
checks can be configured before the first browser request fails.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

lz commented

2026-05-28 23:08:13 +02:00

Author

Owner

Closing as already merged — the change has landed via PR #21.

This PR's only commit (5ed6d11) was also the first commit of what became the feat/artifacts branch (PR #21). When that PR was rebased before merging, this commit was carried through with the same patch but re-authored as Luca Zanussi <dev@luca.zanus.si> and with the Co-Authored-By trailer stripped. It landed on main as commit 297eff4.

git diff main..fix/agent-instructions-dev-server-hosts is empty (git rebase main from this branch reports warning: skipped previously applied commit 5ed6d11), so there's nothing left to merge here.

The Dev-server host/origin checks section is live on main in nexus/static/default-CLAUDE.md. Closing.

Closing as already merged — the change has landed via PR #21. This PR's only commit (`5ed6d11`) was also the first commit of what became the `feat/artifacts` branch (PR #21). When that PR was rebased before merging, this commit was carried through with the same patch but re-authored as `Luca Zanussi <dev@luca.zanus.si>` and with the `Co-Authored-By` trailer stripped. It landed on `main` as commit [`297eff4`](https://x.lck.sh/lz/agent-nexus/commit/297eff4). `git diff main..fix/agent-instructions-dev-server-hosts` is empty (`git rebase main` from this branch reports `warning: skipped previously applied commit 5ed6d11`), so there's nothing left to merge here. The `Dev-server host/origin checks` section is live on `main` in [`nexus/static/default-CLAUDE.md`](nexus/static/default-CLAUDE.md). Closing.

lz closed this pull request

2026-05-28 23:08:32 +02:00