Codeman/docs/web-tabs.md

Web Tabs (dashboards as Codeman tabs)

Open any dashboard you run, Grafana, Uptime Kuma, Portainer, a status page on port 4000, as a tab beside your Claude/Codex/Gemini sessions. Codeman becomes one mission control instead of Codeman plus a pile of browser tabs.

Using it

1. Click the chevron next to Run to expand the dropdown.
2. Under Web / URL, pick Add dashboard...
3. Give it a name and a URL, optionally hit Test, then Save.

The dashboard opens as a tab immediately, and appears in the Run dropdown from then on. Web tabs sit in the same strip as session tabs, continue the same Alt+1..9 numbering, and carry a globe icon so they never read as a running agent.

Closing a tab (the x) only closes it. The saved dashboard stays in the dropdown. To delete it for good, use the x on its dropdown row (the tab's own x is close, not delete). Each dropdown row also has a gear for editing, so a saved URL can be changed or removed without opening it first.

Switching tabs does not reload a dashboard. Frames stay alive in the background, so a dashboard that took a while to authenticate is still there when you come back. Past six live frames the least-recently-viewed one is dropped to bound memory (CODEMAN_MAX_LIVE_WEBVIEW_FRAMES).

Why dashboards are proxied

A plain <iframe src="http://your-box:4000"> does not work in the setup Codeman actually ships in, for three separate reasons:

Blocker	What happens
Mixed content	Production serves HTTPS (behind tailscale serve). Browsers hard-block http:// iframes on an HTTPS page, with no override, and none at all on iOS Safari.
Framing refusal	Grafana, Portainer, Home Assistant and many others send X-Frame-Options: DENY or frame-ancestors 'none'.
Codeman's CSP	default-src 'self' means frame-src falls back to 'self', so a cross-origin iframe is blocked before it starts.

Serving the dashboard through Codeman's own origin dissolves all three. So by default a web tab loads /webview/<capability>/ on Codeman, and Codeman relays to the dashboard: stripping the framing refusal, rewriting redirects, cookies and root-absolute URLs, and relaying WebSockets so live panels actually update.

A useful consequence: the dashboard is fetched from the Codeman server, so a tailnet-only or localhost-only dashboard works from any device that can reach Codeman, including a phone that is not on the tailnet.

direct mode (a plain cross-origin iframe) still exists and is cheaper, but it only works for an HTTPS dashboard that permits framing. The Test button probes from the server and tells you which mode applies.

The sandbox, and when to turn it off

Because a proxied dashboard is served from Codeman's own address, it is same-origin with Codeman as far as the browser is concerned. Left unchecked, its JavaScript could read the Codeman page and call the API that spawns agents.

So the iframe is sandboxed without allow-same-origin by default. The page runs in an opaque origin: it cannot touch Codeman, and it gets no cookies or localStorage of its own.

Unchecking Open sandboxed grants allow-same-origin. Do that only for a dashboard you fully trust, and only if you need it, which in practice means a dashboard with its own login that stores a session in a cookie or localStorage.

Even in trusted mode, Codeman never forwards its own credentials upstream: the Authorization header and the codeman_session cookie are stripped on the way out, so CODEMAN_PASSWORD cannot leak into a dashboard.

How the proxy authenticates

A sandboxed iframe is opaque-origin, so every request it makes is cross-site: the SameSite=lax session cookie is not sent, and writes and WebSocket upgrades arrive with Origin: null. Cookie auth cannot work.

Instead, opening a dashboard mints a capability: 192 bits of entropy in the URL path, held in memory only, with a rolling 12-hour TTL, bound to the user who minted it, and granting exactly one thing, relaying bytes to that one saved URL. Editing or deleting a dashboard revokes it, and a server restart invalidates every outstanding capability (tabs re-mint transparently on next click).

Limits and env vars

Variable	Default	Meaning
CODEMAN_MAX_WEBVIEWS	50	Saved dashboards per owner
CODEMAN_MAX_LIVE_WEBVIEW_FRAMES	6	Iframes kept mounted at once
CODEMAN_WEBVIEW_CAPABILITY_TTL_MS	12h	Rolling capability lifetime
CODEMAN_WEBVIEW_TIMEOUT_MS	30000	Upstream request timeout
CODEMAN_WEBVIEW_PROBE_TIMEOUT_MS	8000	Timeout for the Test button
CODEMAN_MAX_WEBVIEW_HTML_BYTES	8MB	Largest HTML document rewritten
CODEMAN_MAX_WEBVIEW_SOCKETS	8	Concurrent proxied WebSockets per dashboard

Saved dashboards live in ~/.codeman/webviews.json. Which tabs you have open is per-device (localStorage), since that is workspace layout rather than config.

How a dashboard's own API calls keep working

Worth knowing, because it is where this feature does its least obvious work. Three layers cooperate so a dashboard talking to its own backend just works:

1. <base href> handles relative URLs in the markup.
2. Attribute rewriting handles root-absolute src/href/action in the page the proxy serves.
3. A small injected script rebases URLs built at runtime, which the first two cannot see: fetch('/api/data') and new WebSocket('/live'), but equally card.innerHTML = '<img src="/api/hero">' and img.src = '/api/slide'. That second group is why images are covered too. A dashboard that renders its thumbnails from script would otherwise show all its data and none of its pictures, because <base> does not apply to root-absolute URLs and the attribute rewriting only ever saw the initial document.

On top of that, the proxy answers those requests with CORS headers. That sounds wrong for same-host requests, but a sandboxed iframe has an opaque origin, so the browser treats every one of its fetch/XHR calls as cross-origin even though the URL is on Codeman itself. Without those headers, a dashboard renders perfectly and then every API call fails, which looks like the dashboard being broken.

Known limits

• Exotic loaders. The three layers above cover normal fetch/XHR/WebSocket/ EventSource, normal markup, and the DOM sinks a page uses to build markup at runtime. Something that constructs requests by an unusual route can still slip through. Symptom: the page renders but a panel stays empty. The known remaining gap is a root-absolute url(/img.png) inside a stylesheet the page injects at runtime; one under /api has no fallback and will 404.
• Root-absolute location navigation. A dashboard that navigates itself with location.href = '/login' escapes the prefix, because Location.href is unforgeable and cannot be patched the way the other sinks are. A relative location.href = 'login' is fine (<base> covers it).
• Cross-origin redirects are not followed. If a dashboard bounces to a different host (an external SSO provider, say), the proxy hands the redirect back unchanged rather than relaying it, because relaying would make this an open proxy. Use Open in new tab for those.
• Login-protected dashboards need trusted mode, since a sandboxed frame has no cookie jar. A server-side per-dashboard cookie jar would lift this and is the natural next step if it becomes annoying.
• Not a security boundary. The proxy reaches whatever the Codeman server can reach. That is not an escalation for someone who already commands --dangerously-skip-permissions agents, but in multi-user mode it does mean a non-admin user's dashboard is fetched from the server's network position.

Where the code lives

Concern	File
Pure rewrite helpers	src/web/webview-proxy.ts
Routes + proxy + sockets	src/web/routes/webview-routes.ts
Capability tokens	src/webview-capabilities.ts
Persistence	src/webview-store.ts
Limits	src/config/webview-limits.ts
Frontend	src/web/public/webview-tabs.js
Auth exemption	src/web/middleware/auth.ts