Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

fix(auth): open the Windows browser when running under WSL (#999)

Xuan-Nam Nguyen4cfbfa72cbf8
diff --git a/cli/beacon/internal/auth/browser.go b/cli/beacon/internal/auth/browser.go
index ccb51e83..b7adb9ec 100644
--- a/cli/beacon/internal/auth/browser.go
+++ b/cli/beacon/internal/auth/browser.go
@@ -15,11 +15,42 @@ var ErrNoDisplay = errors.New("no browser can be opened on this machine")
// Variables so tests can drive the Linux branch from any OS without starting a browser.
var (
- browserGOOS = runtime.GOOS
- browserEnv = os.Getenv
- startBrowser = func(cmd *exec.Cmd) error { return cmd.Start() }
+ browserGOOS = runtime.GOOS
+ browserEnv = os.Getenv
+ startBrowser = func(cmd *exec.Cmd) error { return cmd.Start() }
+ browserLookPath = exec.LookPath
+ browserIsWSL = isWSL
)
+// isWSL reports whether Beacon is running inside Windows Subsystem for Linux. WSL sets
+// WSL_DISTRO_NAME in every shell; the kernel release is the fallback for environments that
+// scrub it (sudo, systemd units).
+func isWSL() bool {
+ if browserEnv("WSL_DISTRO_NAME") != "" || browserEnv("WSL_INTEROP") != "" {
+ return true
+ }
+ release, err := os.ReadFile("/proc/sys/kernel/osrelease")
+ if err != nil {
+ return false
+ }
+ return strings.Contains(strings.ToLower(string(release)), "microsoft")
+}
+
+// wslOpener returns the command that opens url in the Windows browser under WSL, or nil when not
+// under WSL or no Windows opener is reachable. rundll32.exe, unlike cmd.exe, keeps the & in a URL.
+func wslOpener(url string) []string {
+ if !browserIsWSL() {
+ return nil
+ }
+ if _, err := browserLookPath("wslview"); err == nil {
+ return []string{"wslview", url}
+ }
+ if _, err := browserLookPath("rundll32.exe"); err == nil {
+ return []string{"rundll32.exe", "url.dll,FileProtocolHandler", url}
+ }
+ return nil
+}
+
// CheckDisplay reports, on Linux, whether there is a display to open a browser on. It returns nil
// elsewhere, and nil when it cannot tell.
//
@@ -43,6 +74,10 @@ func CheckDisplay() error {
}
return fmt.Errorf("%w: this is an SSH session", ErrNoDisplay)
}
+ // Under WSL the browser opens on Windows, not on a Linux display.
+ if wslOpener("") != nil {
+ return nil
+ }
if display == "" && browserEnv("WAYLAND_DISPLAY") == "" {
return fmt.Errorf("%w: DISPLAY and WAYLAND_DISPLAY are not set", ErrNoDisplay)
}
@@ -67,6 +102,10 @@ func OpenBrowser(url string) error {
if err := CheckDisplay(); err != nil {
return err
}
+ if opener := wslOpener(url); opener != nil {
+ cmd = exec.Command(opener[0], opener[1:]...)
+ break
+ }
cmd = exec.Command("xdg-open", url)
default:
return fmt.Errorf("unsupported platform: %s", browserGOOS)
diff --git a/cli/beacon/internal/auth/browser_test.go b/cli/beacon/internal/auth/browser_test.go
index bac092bc..8e514bbc 100644
--- a/cli/beacon/internal/auth/browser_test.go
+++ b/cli/beacon/internal/auth/browser_test.go
@@ -12,10 +12,16 @@ import (
func fakeBrowserHost(t *testing.T, goos string, env map[string]string) *[]string {
t.Helper()
prevGOOS, prevEnv, prevStart := browserGOOS, browserEnv, startBrowser
- t.Cleanup(func() { browserGOOS, browserEnv, startBrowser = prevGOOS, prevEnv, prevStart })
+ prevLookPath, prevIsWSL := browserLookPath, browserIsWSL
+ t.Cleanup(func() {
+ browserGOOS, browserEnv, startBrowser = prevGOOS, prevEnv, prevStart
+ browserLookPath, browserIsWSL = prevLookPath, prevIsWSL
+ })
var started []string
browserGOOS = goos
browserEnv = func(key string) string { return env[key] }
+ browserIsWSL = func() bool { return false }
+ browserLookPath = func(string) (string, error) { return "", exec.ErrNotFound }
startBrowser = func(cmd *exec.Cmd) error {
started = append(started, filepath.Base(cmd.Path))
return nil
@@ -84,3 +90,72 @@ func TestOpenBrowserUsesXdgOpenOnLinux(t *testing.T) {
t.Fatalf("started %v, want xdg-open", *started)
}
}
+
+// fakeWSL makes the host look like WSL with the given Windows-side openers on PATH.
+func fakeWSL(t *testing.T, onPath ...string) {
+ t.Helper()
+ browserIsWSL = func() bool { return true }
+ browserLookPath = func(name string) (string, error) {
+ for _, p := range onPath {
+ if p == name {
+ return "/usr/bin/" + name, nil
+ }
+ }
+ return "", exec.ErrNotFound
+ }
+}
+
+// WSLg sets DISPLAY, so the display check used to pass and xdg-open was started. With no Linux
+// browser it failed after Start returned nil, and sign-in printed "Opening ... in your browser",
+// showed no URL, and waited out the timeout.
+func TestOpenBrowserUsesTheWindowsBrowserUnderWSL(t *testing.T) {
+ cases := []struct {
+ name string
+ env map[string]string
+ onPath []string
+ want string
+ }{
+ {name: "wslview installed", env: map[string]string{"DISPLAY": ":0"}, onPath: []string{"wslview", "rundll32.exe"}, want: "wslview"},
+ {name: "interop only", env: map[string]string{"DISPLAY": ":0"}, onPath: []string{"rundll32.exe"}, want: "rundll32.exe"},
+ // WSL without WSLg has no display at all; the Windows browser is still reachable.
+ {name: "no WSLg display", env: map[string]string{}, onPath: []string{"rundll32.exe"}, want: "rundll32.exe"},
+ // Interop disabled: fall back to the Linux behaviour.
+ {name: "no Windows opener", env: map[string]string{"DISPLAY": ":0"}, want: "xdg-open"},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ started := fakeBrowserHost(t, "linux", tc.env)
+ fakeWSL(t, tc.onPath...)
+ if err := OpenBrowser("https://beacon.sh/cli/auth?state=a&port=54123"); err != nil {
+ t.Fatalf("OpenBrowser = %v, want nil", err)
+ }
+ if len(*started) != 1 || (*started)[0] != tc.want {
+ t.Fatalf("started %v, want %s", *started, tc.want)
+ }
+ })
+ }
+}
+
+func TestOpenBrowserUnderWSLWithoutAnyOpenerOrDisplayReportsNoDisplay(t *testing.T) {
+ started := fakeBrowserHost(t, "linux", map[string]string{})
+ fakeWSL(t)
+ if err := OpenBrowser("https://beacon.sh"); !errors.Is(err, ErrNoDisplay) {
+ t.Fatalf("OpenBrowser = %v, want ErrNoDisplay", err)
+ }
+ if len(*started) != 0 {
+ t.Fatalf("started %v", *started)
+ }
+}
+
+// A browser opened on the Windows desktop of the machine someone is SSH'd into is just as
+// invisible to them as one opened on its X display.
+func TestOpenBrowserUnderWSLOverSSHReportsNoDisplay(t *testing.T) {
+ started := fakeBrowserHost(t, "linux", map[string]string{"SSH_CONNECTION": "10.0.0.5 51000 10.0.0.9 22"})
+ fakeWSL(t, "wslview")
+ if err := OpenBrowser("https://beacon.sh"); !errors.Is(err, ErrNoDisplay) {
+ t.Fatalf("OpenBrowser = %v, want ErrNoDisplay", err)
+ }
+ if len(*started) != 0 {
+ t.Fatalf("started %v", *started)
+ }
+}
diff --git a/docs/cli/account-auth.mdx b/docs/cli/account-auth.mdx
index 9da77247..1a35b0a1 100644
--- a/docs/cli/account-auth.mdx
+++ b/docs/cli/account-auth.mdx
@@ -50,6 +50,11 @@ Or forward the port over SSH before opening the URL: ssh -L 43121:127.0.0.1:4312
Waiting for Beacon sign-in...
```
+Under WSL, `beacon login` opens the sign-in page in your Windows browser. WSL2
+forwards `127.0.0.1` to Windows, so the redirect back to the CLI works without extra
+setup. If Windows interop is turned off, `beacon login` falls back to the Linux
+behavior above; use `--no-browser` and open the printed URL in Windows yourself.
+
### Signing in to a remote machine
Open the URL in the browser on your own computer and approve. That browser then