ctrlrelay 0.13.0__tar.gz → 0.15.0__tar.gz

{ctrlrelay-0.13.0 → ctrlrelay-0.15.0}/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-31
+
+The dev and task agents no longer inherit the usual GitHub credentials;
+ctrlrelay does the pushing, PR opening and commenting itself
+after the agent exits. One new
+database table is added automatically and the new config values have
+defaults, so **no config edit is required** to upgrade.
+
+### Changed
+
+- Dev and task agents run with inherited `GH_*` and `GITHUB_*` variables
+  and gh's login removed from their environment, git credential helpers and
+  git's SSH disabled, and the D-Bus and runtime-dir variables pointed away
+  from the desktop keyring. After the agent exits the
+  relay pushes the run branch from a relay-private git dir to an explicit
+  GitHub URL, opens the PR from the DONE checkpoint (or reuses an open PR on the run
+  branch), pushes fix rounds,
+  fetches failed CI logs and posts task reports. It refuses to push the
+  default branch and only overwrites a remote branch whose head it recorded
+  pushing. secops keeps GitHub access (#235, closes #219)
+- Status page: the phase bar shows the furthest phase seen in the recent
+  transcript and pipeline events, CI waits are
+  shown as waiting rather than reading, and the PR is linked (#239, closes
+  #238)
+
+### Added
+
+- Optional `agent.sandbox: bwrap` with `agent.sandbox_hide_paths` to run the
+  dev and task agents under bubblewrap with credential paths hidden. Off by
+  default (#235)
+- A `relay_pushes` table recording the heads ctrlrelay pushed (#235)
+- Status page: a live counter and dot, server health, GitHub links, and the
+  list of skipped issues (#233, closes #232)
+
+### Known limits
+
+- The agent still runs as the same OS user. Without the bwrap sandbox it
+  can read credential files on disk; with it, only the paths in
+  `agent.sandbox_hide_paths` are hidden. It can still run ssh directly, reach
+  the Linux keyring by resetting the D-Bus address, or read a token kept
+  under some other variable name, and the macOS keychain is not covered. Running the agent as a separate user
+  is tracked in #236
+
+## [0.14.0] - 2026-10-31
+
+A read-only status page. `state.db` switches to WAL mode and gains an
+`events` table; both happen automatically. The page is off until you start
+it. **No config edit is required** to upgrade.
+
+### Added
+
+- `ctrlrelay web start|stop|status` and a `ctrlrelay-web` systemd unit: a
+  read-only page plus `/api/status` and `/api/events` JSON showing what each
+  agent is doing (phase and last command), the waiting line, questions that
+  need you, today's counts, and a feed of dispatches, PRs, CI, reviews,
+  merges, messages and alerts. New `web:` config block (defaults
+  `127.0.0.1:8787`, 7 days). Requests for other host names are refused; add
+  LAN names to `web.allowed_hosts` (#217, closes #209)
+- An `events` table, written best-effort by the daemon on a separate
+  connection with a 0.25s lock wait, so a slow or failed write never affects
+  the work it records (#217)
+
+### Changed
+
+- `state.db` uses WAL mode so the page can read while the daemon writes. If
+  the switch cannot get the lock at startup it is deferred to the next start
+  instead of failing (#217)
+
 ## [0.13.0] - 2026-10-30
 
 New database columns and one new config value. All of them are added
@@ -1771,7 +1839,9 @@ pipeline).
   per-phase implementation plans (Phase 0 through Phase 4).
 - `docs/Claude_Code_Project_Guide.md` — project development guide.
 
-[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.13.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.4...v0.13.0
 [0.12.4]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.2...v0.12.4
 [0.12.3]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.2...v0.12.3

{ctrlrelay-0.13.0 → ctrlrelay-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.13.0
+Version: 0.15.0
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/

{ctrlrelay-0.13.0 → ctrlrelay-0.15.0}/config/orchestrator.yaml.example

@@ -88,6 +88,20 @@ dashboard:
   url: "https://ctrlrelay-dashboard.example.com"
   auth_token_env: "CTRLRELAY_DASHBOARD_TOKEN"
 
+# Read-only status page: `ctrlrelay web start`. Loopback by default; set
+# host to this machine's LAN address to open it from the home network.
+# It has no login: never expose it to the internet.
+web:
+  host: "127.0.0.1"
+  port: 8787
+  history_days: 7
+  refresh_seconds: 5
+  github_check_seconds: 60
+  stale_after_minutes: 15
+  # Extra names you open the page by from another machine (the Host
+  # header); loopback, web.host and this machine's hostname are allowed.
+  allowed_hosts: []
+
 # Scheduled jobs run in-process by the poller daemon. Cron expressions are
 # standard 5-field (minute hour dom month dow) and evaluate in the `timezone`
 # set above. Change `secops_cron` to e.g. "0 6 * * 1" for weekly (Mondays).

{ctrlrelay-0.13.0 → ctrlrelay-0.15.0}/docs/architecture.md

@@ -70,6 +70,14 @@ is the only place ctrlrelay calls out to Claude Code.
 - **Environment additions:** `CTRLRELAY_SESSION_ID` and `CTRLRELAY_STATE_FILE`
   are the only contract between dispatcher and child. Anything else the agent
   needs (issue body, PR rules, etc.) goes into the prompt.
+- **Credentials (#219):** every spawn says whether it gets GitHub access
+  (`spawn_session(..., github_access=...)`, no default). dev and task spawn
+  without it: GitHub tokens, `gh`'s login, git credential helpers, SSH and
+  the desktop keyring are cut off (`core/agent_env.py`), and ctrlrelay
+  pushes the branch, opens the PR or posts the report itself afterwards
+  (`core/publish.py`, `WorktreeManager.push_run_branch`). secops still
+  spawns with access. See
+  [What the agent can reach](configuration.md#what-the-agent-can-reach-219).
 - **Result:** `SessionResult(session_id, exit_code, state, stdout, stderr,
   agent_session_id)`. `session_id` is our composite orchestrator id;
   `agent_session_id` is Claude's own UUID, parsed from the JSON stdout and

{ctrlrelay-0.13.0 → ctrlrelay-0.15.0}/docs/configuration.md

@@ -26,6 +26,7 @@ paths:        { ... }
 claude:       { ... }
 transport:    { ... }
 dashboard:    { ... }
+web:          { ... }
 repos:        [ ... ]
 ```
 
@@ -38,6 +39,7 @@ repos:        [ ... ]
 | `claude` | object | no | (defaults) | See [claude](#claude). |
 | `transport` | object | **yes** | — | See [transport](#transport). |
 | `dashboard` | object | no | (defaults) | See [dashboard](#dashboard). |
+| `web` | object | no | (defaults) | The read-only status page. See [web](#web). |
 | `repos` | list | no | `[]` | See [repos](#repos). |
 | `schedules` | object | no | (defaults) | See [schedules](#schedules). |
 | `personalization` | object | no | unset | Cross-machine sync of Claude state. See [personalization](#personalization) and [Personalization sync]({{ '/personalization/' | relative_url }}). |
@@ -86,7 +88,78 @@ claude:
 
 ctrlrelay always invokes claude with `--dangerously-skip-permissions` so the
 agent does not pause on tool-permission prompts in headless runs. This is
-intentional — the orchestrator runs unattended.
+intentional — the orchestrator runs unattended. The CLI's other unattended
+modes either need every shell command allow-listed or filter by command text,
+which a wrapper script walks past, so they are not used as a guard. The guard
+is the next section: the agent holds no GitHub credentials.
+
+### What the agent can reach (#219)
+
+The dev and task agents run **without GitHub access**. ctrlrelay starts them
+with:
+
+- every `GH_*` and `GITHUB_*` variable removed (`GH_TOKEN`, `GITHUB_TOKEN`,
+  `GH_ENTERPRISE_TOKEN`, ...), and every inherited `CTRLRELAY_*` variable
+  (the chat bot tokens) except the two the checkpoint needs;
+- `GH_CONFIG_DIR` pointed at a fresh empty directory, so `gh` finds no login;
+- `DBUS_SESSION_BUS_ADDRESS` pointed at nothing, so `gh` and other libsecret
+  clients cannot fall back to the desktop keyring;
+- `credential.helper` reset to empty (through `GIT_CONFIG_COUNT`),
+  `GIT_SSH_COMMAND=false` and `SSH_AUTH_SOCK` removed, so git cannot
+  authenticate over HTTPS or SSH, including through an `insteadOf` rewrite;
+- `GIT_TERMINAL_PROMPT=0`, so nothing waits on a prompt.
+
+Everything else is inherited unchanged, so the model CLI and the project's
+toolchain behave as before. ctrlrelay then does the GitHub side itself, with
+its own credentials, after the agent exits:
+
+- **dev:** the agent commits on the run's branch and writes a PR title and
+  description in its DONE checkpoint. ctrlrelay pushes the branch and opens
+  the pull request. After a CI or conflict fix round it pushes again, and it
+  fetches the failed-job logs the agent used to read with `gh run view`.
+- **task:** the agent writes its report in its DONE checkpoint and ctrlrelay
+  posts it as the issue comment.
+- **secops** still runs **with** the operator's GitHub access. Its agent
+  reads Dependabot alerts and pull requests and merges what the policy
+  allows during the run. Moving it would mean ctrlrelay doing those reads
+  up front and the merges afterwards from a decision the agent returns.
+
+Pushes are refused, and logged as `publish.push.refused`, for `main`,
+`master`, the repository's default branch (read from the GitHub API, not
+from the local clone) and any branch that is not the run's own. The push
+goes to `https://github.com/<owner>/<repo>.git` (never `origin`) from a
+private git dir with hooks off and only ctrlrelay's own git config, pushes the
+commit it checked rather than the ref name, and uses `--force-with-lease`
+against the head this session last pushed (recorded in the state DB). An
+open PR found for the branch is reused only if its head repo is this repo and
+its base is the default branch. Text the agent wrote is posted with `@`-mentions and
+issue-closing keywords disabled and its length capped (20,000 characters);
+the PR's own `Closes #N` is added by ctrlrelay.
+
+**What this guarantees.** No GitHub credential is handed to the agent through
+its environment. ctrlrelay chooses the push URL, the branch and the PR base.
+`main`, `master`, the default branch and any branch other than the run's own
+are refused, and a branch that already exists on GitHub is only pushed over if
+its head is one ctrlrelay recorded pushing. Agent-written text is sanitized.
+An agent that only uses its normal tooling (git, gh, ssh as configured) cannot
+push. The push itself runs from a fresh relay-owned git dir under
+`~/.ctrlrelay/push/`, reads the clone's branch heads from its ref files, and
+never reads the clone's config, which every worktree shares.
+
+**What it does not guarantee.** The agent still runs as your user. A
+deliberately hostile agent can read `~/.config/gh/hosts.yml`, `~/.ssh` and
+anything else in your home directory and use them by hand; it can write
+anywhere your user can, including your dotfiles and ctrlrelay's install; and
+it can write to `~/.ctrlrelay/push/`, the bare clone's object store and any
+`objects/info/alternates` chain it adds there, racing a push. On macOS the
+login keychain is reachable whatever the environment says. Closing that needs
+a separate user or a read-only home (#236). The next setting hides the
+credential paths; it does not stop the writes.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `sandbox` | `"none"` or `"bwrap"` | `"none"` | `"bwrap"` runs the dev and task agents under bubblewrap with `sandbox_hide_paths` replaced by empty mounts. Linux only; needs `bwrap` installed and unprivileged user namespaces allowed (on Ubuntu 24.04+ an AppArmor profile for `bwrap`). ctrlrelay refuses to start if it is set and `bwrap` is missing. |
+| `sandbox_hide_paths` | list of strings | `~/.ssh`, `~/.config/gh`, `~/.git-credentials`, `~/.config/git/credentials`, `~/.netrc`, `~/.local/share/keyrings`, `$XDG_RUNTIME_DIR/bus` | Paths hidden under `sandbox: bwrap`. A directory becomes an empty tmpfs, a file or socket becomes `/dev/null`, a missing path is skipped. |
 
 ## transport
 
@@ -205,6 +278,36 @@ dashboard:
 The dashboard is optional. Leaving `url` empty (the default) is the supported
 no-op configuration.
 
+## web
+
+The read-only status page served by `ctrlrelay web start` (see
+[Operations: status page]({{ '/operations/' | relative_url }}#status-page)). Every key is optional;
+without a `web:` block the defaults below apply.
+
+```yaml
+web:
+  host: "127.0.0.1"
+  port: 8787
+  history_days: 7
+  refresh_seconds: 5
+  github_check_seconds: 60
+  stale_after_minutes: 15
+  allowed_hosts: []          # e.g. ["mybox", "mybox.lan"]
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `host` | string | `"127.0.0.1"` | Address to listen on, exactly. Loopback by default so a fresh install is never reachable from other machines. Set it to this machine's LAN address to open the page from the home network. `0.0.0.0` listens on every interface and is warned about at startup. |
+| `port` | int (1-65535) | `8787` | Port to listen on. |
+| `history_days` | int (>= 1) | `7` | Days of feed the page shows, and what `/api/events` returns without `?since=`. |
+| `refresh_seconds` | int (>= 1) | `5` | How often the page asks `/api/status` again. |
+| `github_check_seconds` | int (>= 15) | `60` | How often the waiting line asks GitHub (one search, plus one query per `include_labels` label). |
+| `stale_after_minutes` | int (>= 1) | `15` | A running card is marked "looks stuck" after this long with no new agent step, unless ctrlrelay itself has a CI wait or review open for it. |
+| `allowed_hosts` | list of strings | `[]` | Extra names the page may be opened by. A request is served only when its `Host` header is `localhost`, `127.0.0.1`, `[::1]`, `host` (unless it is `0.0.0.0`/`::`), this machine's hostname, the hostname plus `.local`, or one of these, alone or followed by `:port`. Anything else, or no `Host`, gets `421`. Matching ignores case and a trailing dot. This stops a web page on another site from pointing its own name at this server (DNS rebinding) and reading it. |
+
+The page has no login and shows repository names, issue titles and the
+questions agents asked. **Never expose it to the internet.**
+
 ## repos
 
 A list of repositories the orchestrator manages.
@@ -253,7 +356,7 @@ and ask the operator), or `never` (skip).
 | `exclude_labels` | `["manual", "operator", "instruction"]` | Issue labels that tell the poller "this isn't for the agent". See [exclude_labels](#reposautomationexclude_labels) below. |
 | `include_labels` | `[]` | Issue labels that opt an issue **into** the dev pipeline regardless of who is (or isn't) assigned. See [include_labels](#reposautomationinclude_labels) below. |
 | `require_labels` | `[]` | Issue labels that gate the plain-assignment trigger: when set, assignment alone is no longer enough — the issue must also carry one of these labels. See [require_labels](#reposautomationrequire_labels) below. |
-| `ci_wait_timeout_seconds` | `600` | Hard cap, in seconds, on the single `ctrlrelay ci wait` call the dev pipeline prompt tells Claude to run before signaling DONE. See [ci_wait_timeout_seconds](#reposautomationci_wait_timeout_seconds) below. |
+| `ci_wait_timeout_seconds` | `600` | Unused since #219 (the agent no longer waits on CI; ctrlrelay does). Still accepted so existing configs load. See [ci_wait_timeout_seconds](#reposautomationci_wait_timeout_seconds) below. |
 
 The current secops and dev pipelines read these settings to bias their prompts
 to Claude — they're not enforced by hard-coded checks.
@@ -400,7 +503,12 @@ repos:
 
 ### repos[].automation.ci_wait_timeout_seconds
 
-The dev pipeline prompt tells Claude to run `ctrlrelay ci wait --pr <PR>
+**Not used by the dev pipeline since #219.** The agent no longer has GitHub
+access, so it no longer waits on CI: ctrlrelay pushes the branch after the
+agent exits and its own PR verifier waits on CI. The key is still accepted so
+existing configs load. What follows describes the earlier behaviour.
+
+The dev pipeline prompt told Claude to run `ctrlrelay ci wait --pr <PR>
 --repo <repo> --timeout <N>` before signaling DONE — a single blocking call
 that polls GitHub every 15s until CI finishes, fails, or the timeout hits.
 No tokens get generated while it's blocked; on a repo with a slow CI suite,

{ctrlrelay-0.13.0 → ctrlrelay-0.15.0}/docs/feedback-loop.md

@@ -151,9 +151,12 @@ Step-by-step:
 15–17. **Loop until terminal.** If the resumed session blocks again, steps
     8–14 repeat (capped at `DEFAULT_MAX_BLOCKED_ROUNDS`, currently 5). On
     `DONE`/`FAILED`, the loop exits.
-18. **PR verification.** If the dev pipeline got `DONE` with a `pr_url`, it
-    verifies the PR is mergeable and CI is green. If not, it asks Claude to
-    fix and re-verifies (up to `DEFAULT_MAX_FIX_ATTEMPTS`, currently 3).
+18. **Publish and verify.** On `DONE` the agent has only committed; it has
+    no GitHub access (#219). ctrlrelay pushes the run's branch, opens the PR
+    from the title and description in the checkpoint, then verifies the PR
+    is mergeable and CI is green. If not, it resumes the agent with the
+    failed-job logs, pushes the fix itself and re-verifies (up to
+    `DEFAULT_MAX_FIX_ATTEMPTS`, currently 3).
 19. **Operator notified.** The poller pushes a final `✅ PR ready: <url>` (or
     `❌ Failed: …`) message via the bridge.
 

{ctrlrelay-0.13.0 → ctrlrelay-0.15.0}/docs/operations.md

@@ -21,6 +21,7 @@ ctrlrelay generates platform-appropriate service unit files for you with
 |---|---|---|
 | Bridge | `ctrlrelay bridge start` | Delivers BLOCKED questions to Telegram and routes answers back. |
 | Poller | `ctrlrelay poller start --interval 300` | Watches GitHub for newly assigned issues and runs the dev pipeline. |
+| Status page (optional) | `ctrlrelay web start` | Read-only page and JSON API of what ctrlrelay is doing. See [Status page](#status-page). |
 
 Both should restart on failure and on login.
 
@@ -234,6 +235,97 @@ systemctl --user status ctrlrelay-poller
 journalctl --user -u ctrlrelay-poller -f
 ```
 
+## Status page
+
+`ctrlrelay web start` serves a read-only page and JSON API showing what each
+agent is doing (phase, current activity, last command), what is waiting and
+why, the questions that need an answer, and a feed of what ctrlrelay did and
+said. It is a third process next to the bridge and the poller, so a slow or
+broken page can never stall them.
+
+On a running card, **phase** (the bar) is the furthest step the session has
+reached, from the agent's transcript plus ctrlrelay's own CI, review and PR
+events, so it never moves back. **Current activity** is the most recent step:
+an open CI wait or review if it started after the agent's latest step, else
+that step. It can be earlier than the bar, for example a read after the PR
+or a fix round after review. The card links the PR once ctrlrelay has
+recorded its number.
+
+It is **read-only**: it opens `state.db` read-only, reads the tail of each
+agent's transcript, and asks GitHub (through the `gh` login ctrlrelay already
+uses) for the waiting line once a minute. It writes nothing but its PID file
+(`web.pid`, next to `state.db`), and serves `GET` only; any other method is
+`405`. It has **no login** and shows repository names, issue titles and the
+questions agents asked, so **never expose it to the internet**. Keep it on
+loopback or on the home network.
+
+| Path | What |
+|---|---|
+| `/` | The page. Refreshes itself every `web.refresh_seconds`. |
+| `/api/status` | Everything on the page, as JSON (the contract is in `src/ctrlrelay/web/status.py`). A section that could not be read is `null` and `errors` says why; `[]` means "read, and empty". The feed holds at most the newest `feed_limit` (200) events: `feed_total` is how many the history window holds (`null` if unreadable) and `feed_truncated` is `true` when some were left out, in which case the page says "showing newest N of M". |
+| `/api/events?since=<epoch seconds>` | The feed, newest first, at most `limit` (200) events. Without `since`, the last `web.history_days` days. Carries the same `feed_total` and `feed_truncated`, plus the `limit` used. |
+
+The page header shows how long ago it last heard from the server ("updated
+12s ago", ticking every second) and a dot that is green while the last good
+answer is at most two refresh intervals old and red otherwise. Elapsed times
+on cards tick between polls too.
+
+Fields added in #232 (all in `/api/status`):
+
+| Field | What |
+|---|---|
+| `url` | On every `running`, `needs_you`, `waiting.items`, `skipped` and `feed` item (and on `/api/events` events): a link to the GitHub issue, or for a feed event that names a PR by number, the PR. Built only as `https://github.com/<owner>/<repo>/issues/<n>` or `/pull/<n>`, from a repo matching `owner/name` and an integer; `null` otherwise (a secops run with no issue, a restart). A `pr_url` an agent reported is never used. |
+| `skipped` | Every open issue assigned to you that the poller will **not** pick up and is not running, from the same search as the waiting line (no extra GitHub calls): `repo`, `issue_number`, `title`, `url`, `updated`/`updated_ts` and `reason`, one of `repo not in config`, `excluded label <label>`, `already handled once (won't retry)`, `missing required label <label>` (several joined with "or": any one admits it), `assigned by someone else`. `null` until GitHub has answered once; `waiting.status` and `waiting.last_good_ts` say how current it is. The page shows it collapsed, with a count. |
+| `server` | This machine's health, read on each request: `load_1m`, `load_5m`, `load_15m`, `cpu_count`, `memory` (`total_bytes`, `available_bytes`, `available_pct`, `low`), `disks` (one each for `home` and `worktrees`: `name`, `path`, `total_bytes`, `free_bytes`, `free_pct`, `low`), `uptime_s`, and `unavailable` (why any number is `null`; memory and uptime are `null` off Linux). `low` is true below 10% free and the page marks it. The whole section is `null`, with a line in `errors`, only if reading it failed outright. |
+
+Try it on loopback first (the default `web.host` is `127.0.0.1`, port `8787`):
+
+```bash
+ctrlrelay web start
+ctrlrelay web status
+curl -s http://127.0.0.1:8787/api/status | python3 -m json.tool | head -40
+curl -s "http://127.0.0.1:8787/api/events?since=$(( $(date +%s) - 3600 ))"
+ctrlrelay web stop
+```
+
+To open it from another machine on the home network, set `web.host` in
+`orchestrator.yaml` to this machine's LAN address (see
+[web]({{ '/configuration/' | relative_url }}#web)), then run it under
+systemd. `ctrlrelay install systemd` renders `ctrlrelay-web.service` with the
+other two units. It refuses to overwrite units that already exist, so on a
+host where the bridge and poller are installed, render into a scratch
+directory and copy only the web unit:
+
+```bash
+ctrlrelay install systemd --workdir ~/Projects/ctrlrelay --target-dir ~/ctrlrelay-units
+cp ~/ctrlrelay-units/ctrlrelay-web.service ~/.config/systemd/user/
+rm -r ~/ctrlrelay-units   # the other two carry the chat token
+systemctl --user daemon-reload
+systemctl --user enable --now ctrlrelay-web.service
+journalctl --user -u ctrlrelay-web -n 20
+tail -n 20 ~/.ctrlrelay/logs/web.log
+```
+
+The first line in `web.log` is a `web.started` event naming the address it
+bound. If `web.host` is `0.0.0.0` it also logs a warning: that listens on
+every interface, which is rarely what you want.
+
+The page answers only to names it knows: `localhost`, `127.0.0.1`, `[::1]`,
+`web.host`, and this machine's own hostname (plus `.local`). A request whose
+`Host` header carries any other name gets `421 misdirected request`, and the
+refused name is logged once as `web.misdirected_host`. So if you open it from
+another machine by a name that is none of those, for example a DNS name your
+router hands out, add that name to `web.allowed_hosts` and restart the unit:
+
+```yaml
+web:
+  host: "192.168.1.20"
+  allowed_hosts: ["mybox.lan"]
+```
+
+`grep misdirected_host ~/.ctrlrelay/logs/web.log` shows any name that was
+refused, which is the quickest way to find the one to add.
+
 ## Scheduled jobs
 
 The poller daemon also hosts an in-process cron (APScheduler). The jobs run
@@ -300,6 +392,7 @@ Tail them:
 tail -f ~/.ctrlrelay/logs/poller.log
 tail -f ~/.ctrlrelay/logs/bridge.log
 tail -f ~/.ctrlrelay/logs/poller.error.log
+tail -f ~/.ctrlrelay/logs/web.log      # if the status page is installed
 ```
 
 The poller prints one line per detected issue and one line per pipeline outcome.