Plan: make the dashboard work from a forwarded / proxied workspace URL

Goal

Make agent-browser dashboard work when the UI is opened through a forwarded HTTPS workspace URL (for example, a Coder app URL) without requiring the browser to reach raw localhost ports. Preserve existing local http://localhost:4848 behavior, keep the session stream servers loopback-only, and fix the dashboard in a way that is robust for any same-origin reverse-proxy deployment.

Context and verified evidence

• The frontend currently hardcodes dashboard API calls to http://localhost:4848 in packages/dashboard/src/lib/exec.ts.
• packages/dashboard/src/store/sessions.ts only uses relative /api/sessions when window.location.origin literally contains :4848; otherwise it falls back to http://localhost:4848/api/sessions.
• packages/dashboard/src/store/sessions.ts polls tabs from http://localhost:${s.port}/api/tabs.
• packages/dashboard/src/store/stream.ts opens the live stream with new WebSocket(ws://localhost:${port}).
• The standalone dashboard server in cli/src/native/stream.rs currently exposes static files plus /api/sessions, /api/exec, and /api/kill; it does not proxy per-session /api/tabs or WebSocket traffic.
• The per-session stream server in cli/src/native/stream.rs serves /api/tabs, /api/status, /api/command, and the WebSocket stream, and its is_allowed_origin() check only allows loopback/file origins today.

Proposed design

Core decision

Move the dashboard to a single-origin browser model:

1. The browser talks only to the dashboard origin:
   • /api/sessions
   • /api/exec
   • /api/kill
   • /api/session/<port>/tabs
   • ws(s)://<dashboard-origin>/api/session/<port>/stream
2. The dashboard server proxies session-specific HTTP and WebSocket traffic to 127.0.0.1:<session-port>.
3. Session stream servers remain loopback-only and keep their stricter origin policy because browsers no longer connect to them directly.

This removes all browser-side localhost assumptions and avoids widening the per-session WebSocket trust boundary.

Workstreams

1) Backend: add same-origin proxy routes on the dashboard server

Primary file: cli/src/native/stream.rs

Add explicit dashboard-only proxy routes inside handle_dashboard_connection() for session traffic:

• GET /api/session/<port>/tabs
• GET /api/session/<port>/status (optional but cheap to add while route parsing exists)
• WS /api/session/<port>/stream

Implementation notes:

• Add a small route parser/helper instead of stringly-typed path slicing all over the handler.
• Validate that <port> parses as a u16, is non-zero, and belongs to a currently active session before proxying.
• Reuse discover_sessions() data or add a small helper that returns a validated active-port set/map.
• For HTTP proxying, connect to 127.0.0.1:<port> and relay the minimal request needed (initially GET /api/tabs and optionally GET /api/status).
• For WebSocket proxying, accept a browser WebSocket on the dashboard server, open an upstream WebSocket to ws://127.0.0.1:<port>, and pump frames/messages in both directions.
• Keep the per-session is_allowed_origin() behavior intact; the dashboard proxy should connect server-to-server, so the browser never hits the per-session WS endpoint directly.

Defensive programming requirements:

• Add assertions / explicit validation around parsed ports and route shape.
• Reject stale or unknown ports with a clear 404/400 JSON response rather than forwarding blindly.
• Document any assumptions in helper comments near the route parser / proxy entrypoints.

Quality gate after this workstream

• Add focused Rust unit tests for route parsing and active-port validation in cli/src/native/stream.rs.
• Add at least one test for rejecting malformed or inactive ports.
• Manually verify a local GET /api/session/<port>/tabs response before changing the frontend.

2) Frontend: remove functional localhost usage and centralize route building

Primary files:

• packages/dashboard/src/lib/exec.ts
• packages/dashboard/src/store/sessions.ts
• packages/dashboard/src/store/stream.ts
• packages/dashboard/src/components/viewport.tsx
• new helper, e.g. packages/dashboard/src/lib/dashboard-routes.ts

Refactor the frontend so functional traffic always targets the current dashboard origin:

• Create a small shared helper module for route construction instead of repeating URL logic inline.
• Convert dashboard API calls to relative paths:
  • /api/sessions
  • /api/exec
  • /api/kill
• Convert per-session tab polling to /api/session/<port>/tabs.
• Convert the stream connection to ws:/wss: based on window.location.protocol, pointing at /api/session/<port>/stream on window.location.host.
• Update the viewport/status label so it shows the same-origin stream endpoint, not ws://localhost:<port>.

Recommended helper surface:

getDashboardApiPath(path: string): string
getSessionTabsPath(port: number): string
getSessionStreamUrl(port: number): string

Keep the helper intentionally dumb and explicit; do not reintroduce environment guessing or host/port rewriting.

Active-session selection cleanup (small but worthwhile)

packages/dashboard/src/store/sessions.ts currently defaults the active port to 9223, which causes early connection attempts to an arbitrary port before session discovery completes.

Fix this as part of the refactor by making the initial active port invalid/empty until either:

• ?port=<n> is provided, or
• the first discovered session is selected.

Minimal implementation options:

• use 0 as the sentinel and guard useStreamSync() when port <= 0, or
• make the atom nullable if the type churn is acceptable.

This keeps the browser from making noisy / misleading connection attempts during startup.

Quality gate after this workstream

• pnpm --dir packages/dashboard build
• Search the functional frontend code for remaining http://localhost: / ws://localhost: callsites and remove them unless they are non-functional examples/tests.
• Smoke-test the dashboard locally before moving on to docs.

3) Security and compatibility hardening

Primary file: cli/src/native/stream.rs

Because the dashboard can now be opened through a forwarded origin, do not expand trust by broadening the per-session origin whitelist. The proxy route design avoids that need.

Hardening tasks:

• Reassess the current permissive dashboard CORS behavior (Access-Control-Allow-Origin: *). Same-origin usage means the dashboard does not need permissive cross-origin browser access for normal operation.
• At minimum, do not make CORS/origin behavior more permissive while adding the proxy routes.
• Prefer port validation against active sessions over blind localhost forwarding.
• If the route surface grows, factor JSON response helpers to keep error handling consistent.

Quality gate after this workstream

• Verify that a forwarded dashboard session works without widening is_allowed_origin().
• Verify that invalid ports cannot be proxied.

4) Documentation and help text updates

Because this changes user-visible dashboard behavior, update all required docs/help surfaces called out in AGENTS.md.

Files to update

• cli/src/output.rs
• README.md
• skills/agent-browser/SKILL.md
• docs/src/app/observe/page.mdx
• docs/src/app/commands/page.mdx (if the dashboard behavior text/examples need matching updates)
• inline doc comments near the new proxy helpers / route builders

Doc changes should explain:

• the dashboard now works from the local URL or a forwarded workspace URL
• the browser talks only to the dashboard origin
• session ports remain internal implementation details
• agent-browser dashboard install still installs the static assets, but dogfooding local changes requires serving the locally built dashboard bundle instead of the released zip

Quality gate after this workstream

• Review help text and docs for any remaining claim that the UI must directly call localhost:<session-port>.

Acceptance criteria

The change is done when all of the following are true:

1. Opening the dashboard at http://localhost:4848 still works for local use.
2. Opening the dashboard through the forwarded workspace URL loads without mixed-content or CORS failures.
3. The frontend no longer makes functional requests from the browser to http://localhost:* or ws://localhost:*.
4. Session discovery, session creation, session kill, and exec-driven UI actions work through same-origin dashboard endpoints.
5. The live viewport connects through a same-origin ws:/wss: dashboard route and remains interactive.
6. Session tab lists still populate for all visible sessions.
7. Invalid or stale session ports are rejected by the dashboard proxy instead of being blindly forwarded.
8. Documentation/help text reflects the new deployment model.

Dogfooding / self-verification plan

Environment setup

1. Build the dashboard assets from the workspace copy of the repo:
   • pnpm build:dashboard
2. Install the local built assets into the dashboard serve location used by the CLI during testing (do not rely on dashboard install, which fetches the released bundle).
3. Build and run the CLI from the workspace checkout:
   • cargo build --manifest-path cli/Cargo.toml
   • start the dashboard from the built CLI on port 4848
4. Start at least one browser session from the same checkout so the dashboard has a live stream source.
5. If available, install Portless as a global external tool (do not add it to this repo and do not make the fix depend on it).

Portless-assisted rehearsal (recommended local preflight)

Use Portless as a local rehearsal layer before the real workspace test. The goal is to open the dashboard through a named host-based URL instead of localhost:4848, so we can catch the exact class of bugs that assume raw port URLs.

Suggested flow:

1. Start the Portless proxy with HTTPS enabled.
2. Register a static alias for the real dashboard server port (4848) under a stable name such as dashboard.
3. Open the dashboard via the resulting Portless URL instead of http://localhost:4848.
4. Run the same smoke checks as the forwarded-workspace scenario.

Example command sequence:

portless proxy start --https
portless alias dashboard 4848
portless list

Use the named Portless URL shown by portless list for the rehearsal run.

What this rehearsal should catch:

• mixed-content failures from any lingering http://localhost:* fetches
• secure-page WebSocket failures from any lingering ws://localhost:* usage
• frontend assumptions that the visible origin must literally include :4848

Important guardrail:

• If the implementation still requires exposing or aliasing per-session ports through Portless, the design is still wrong. Only the standalone dashboard origin should need exposure; session ports must stay behind same-origin dashboard proxy routes.

What Portless does not replace:

• final dogfooding in the real forwarded workspace URL
• proxy/header/cookie quirks specific to the actual workspace platform

Dogfood scenarios

Scenario A: local regression check

• Open the dashboard at http://localhost:4848
• Verify sessions appear, the viewport connects, tabs populate, and one interactive action works (for example: create tab, switch tab, or close tab)

Scenario B: Portless host-based URL rehearsal

• Open the dashboard through the Portless HTTPS host-based URL rather than a raw localhost port URL
• Verify DevTools shows same-origin /api/... requests and a same-origin wss: stream URL
• Verify there are no mixed-content, CORS, or localhost connection errors
• Verify the viewport streams, session selection works, and at least one action path using exec.ts succeeds

Scenario C: forwarded workspace URL (primary target)

• Open the forwarded HTTPS URL for the dashboard port in the workspace environment
• Verify the page loads cleanly
• Verify DevTools shows same-origin /api/... requests and a same-origin ws:/wss: stream URL
• Verify there are no mixed-content, CORS, or localhost connection errors
• Verify the viewport streams, session selection works, and at least one action path using exec.ts succeeds

Scenario D: invalid-port handling

• Attempt to hit a proxy route with a non-existent / stale port
• Verify the dashboard returns a clean error and does not hang or forward blindly

Required review artifacts

Capture and attach all of the following during dogfooding:

• Screenshot: dashboard loaded via the Portless host-based URL with a connected session visible
• Screenshot: dashboard loaded via the forwarded workspace URL with a connected session visible
• Screenshot: browser DevTools Network/Console showing same-origin API + WebSocket traffic and no mixed-content errors
• Video recording: end-to-end flow through the Portless URL (open dashboard, session appears, viewport connects, one interactive action succeeds)
• Video recording: end-to-end flow in the forwarded workspace environment (open dashboard, session appears, viewport connects, one interactive action succeeds)
• Optional extra screenshot/video for local localhost:4848 regression proof

Validation commands

Run these before declaring success:

• pnpm --dir packages/dashboard build
• cargo test --manifest-path cli/Cargo.toml
• any targeted test command added for the new proxy helpers/routes

Risks and watchouts

• WebSocket relay is the highest-risk change. Keep the first version narrow: just proxy the existing stream channel; do not redesign the message format.
• Local asset confusion: agent-browser dashboard install pulls the released dashboard bundle, so manual testing can accidentally exercise stale assets unless the locally built bundle is installed into the serve directory.
• Session-port direct browsing: if the team still cares about opening the dashboard directly on a session stream port, explicitly regression-test that path or consciously document it as secondary behavior. The primary fix should optimize for the standalone dashboard origin.
• Security drift: avoid “just allow more origins” as the fix. The proxy design is better because it preserves loopback-only trust around the per-session servers.

Recommended implementation order

1. Add backend route parsing + validated HTTP proxy for tabs/status.
2. Add backend WebSocket proxy for the stream path.
3. Refactor frontend to a shared same-origin route helper and remove functional localhost usage.
4. Clean up initial active-port selection so the UI does not guess 9223.
5. Update docs/help text.
6. Dogfood in both local and forwarded workspace environments with screenshots + video.