codeburn/docs/web.md
Marcel Roozekrans 7f88c25489
feat(web): --allowed-host for an authenticating reverse proxy (#1789)
codeburn web only answers to loopback Host and Origin values, which makes it unreachable behind a reverse proxy even when that proxy authenticates (oauth2-proxy, Authelia, Traefik with Keycloak). A repeatable --allowed-host flag adds exact hostnames to the guard, matched case-insensitively and without the port, against both Host and Origin. Without the flag nothing changes.

The guard lives in two exported helpers, isAllowedHost and isAllowedOrigin, with unit tests for the loopback default, exact matching (dash.example.org.evil.example and evil-dash.example.org are refused), Origin limited to http and https, and null refused, plus server tests for a proxied Host and allowed and refused Origins. docs/web.md gains a section on running behind a reverse proxy.

The --host flag from the original proposal is dropped. The dashboard has no authentication, so a non-loopback bind would give any LAN client that sends Host: localhost every route, the share and pairing POSTs included. The bind stays on 127.0.0.1; a proxy on the same machine forwards to it and its Host and Origin pass the guard. Access control is the proxy's job and the docs say so.

Authored by @MarcelRoozekrans. Reviewed and tested locally against real data; the maintainer commit on top removes --host.
2026-11-02 17:17:06 +01:00

2.3 KiB

Browser dashboard

codeburn web                    # opens http://localhost:4747 in your browser
codeburn web -p 30days          # start on a different period
codeburn web --port 8080        # pick a port (falls back to a free one if taken)
codeburn web --no-open          # start the server without opening a browser

A local web dashboard with the same task, model, tool, and project breakdowns as the TUI, rendered with charts. The usage graph follows the selected period with 15-minute, hourly, or daily buckets and can switch between per-session and per-model lines. Everything is read from disk on your machine and the server binds to localhost; nothing is uploaded.

Behind a reverse proxy

The dashboard has no login of its own, and the local view shows project names, paths and session detail. So it listens only on 127.0.0.1 and refuses any request whose Host or Origin is not a loopback name. That stops DNS rebinding and cross-site requests.

To reach it from another machine, put it behind a reverse proxy that authenticates on the same machine, such as oauth2-proxy, Authelia or your SSO's forward auth, and name the hostname the proxy serves it under:

codeburn web --no-open --port 4747 --allowed-host usage.example.org
  • --allowed-host is repeatable. It is matched exactly and case-insensitively, without the port, against both Host and Origin. Everything else still gets a 403.
  • The dashboard has no authentication, and --allowed-host adds none. It only lets the proxy's Host and Origin through the loopback guard, so access control is the proxy's job: anyone the proxy lets in gets the full dashboard, sharing and pairing controls included.

Combine usage across your devices

See one total across your laptop, desktop, and work machine on the same network. On each other device, share its usage:

codeburn share --pair           # opens a pairing window and prints a PIN

Then add it once from your main device (the PIN authorizes the pairing):

codeburn devices add            # find nearby devices and pair, or: add <host> --pin <pin>
codeburn devices                # combined totals by machine
codeburn devices rm <name>      # forget a device

Pairing is PIN-authorized and stays on your local network. You can also discover and pair devices straight from the browser dashboard.