passthrough-www-browser

Relay URLs opened inside the workstation to your laptop's real browser — for OAuth and device-code logins.

A CLI inside the workstation wants to open a browser: claude login, gh auth login, gcloud auth login, az login. The workstation is headless, so nothing happens. This devtool bridges that gap.

devtools:
  - name: passthrough-www-browser

The version field is not used by this recipe.

Opt-in, always

This arms an outbound side channel from the workstation to your machine, so it is never installed on a stock workstation. It exists only when a config asks for it.

What it does

Nothing is downloaded. “Installing” means:

  • a www-browser command is placed on the PATH,
  • BROWSER=www-browser is exported for every login shell,
  • the desktop URL handler and x-www-browser alternative are pointed at it.

When something in the workstation runs www-browser <url>, the URL is recorded. Your daemon tails that record over the workstation’s connection and appends each URL to ~/.ringleader/browser-opens.log.

The host half

Recording alone does not open anything. Turn on urlForward on the workstation’s LocalBinding template:

defaultLocalBinding:
  enabled: true
  urlForward:
    enabled: true      # tail the workstation's URLs into ~/.ringleader/browser-opens.log
    open: true         # …and launch each one in your real browser

With open: true, running claude login over rl shell pops the consent page on your laptop.

Example

The complete pairing — workstation half and host half:

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: browser-passthrough
  namespace: local
spec:
  selector:
    matchLabels:
      tier: dev
  priority: 150
  devtools:
    - name: passthrough-www-browser
  defaultLocalBinding:
    enabled: true
    autoForward:
      forwardAll: true
    urlForward:
      enabled: true
      open: true

Layering this as a separate, higher-priority config keeps your base config free of the side channel: apply it when you need to log in, remove it when you don’t.

Notes

  • Only https URLs are relayed; every line is re-validated on your machine before anything is launched.
  • If several of your devices are connected to the same workstation, each one receives the URL.
  • Works on Debian, Ubuntu, and Alpine.