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 has no browser, so nothing happens. This devtool sends those pages to the browser on your laptop instead.

It has two halves, and you need both. On the workstation, the devtool:

devtools:
  - name: passthrough-www-browser

On your laptop, urlForward on the workstation’s LocalBinding template, which is what actually opens each page:

defaultLocalBinding:
  enabled: true
  urlForward:
    enabled: true      # receive the workstation's URLs
    open: true         # and open each one in your real browser

With both in place, running claude login over rl shell opens the consent page on your laptop. The version field is not used by this recipe.

Opt-in, always

This is an outbound 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 that a www-browser command is placed on the PATH, BROWSER=www-browser is exported for every login shell, and 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, and your daemon reads that record over the workstation’s connection and appends each URL to ~/.ringleader/browser-opens.log. Without urlForward, that is where it stops.

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.