✗ Daemon failed to start (socket: C:\Users\rayle\.agent-browser\bilibili.sock) in windows

[raylee2012]

windows：
D:\code\ai\agent-browser\skills [0:0] $ agent-browser open https://www.baidu.com
✗ Daemon failed to start (socket: C:\Users\rayle.agent-browser\bilibili.sock)

[nicojaroszewski]

Bug Report: Daemon fails to start on Windows — Unix socket EACCES permission denied

Repository: vercel-labs/agent-browser

---

Summary

agent-browser fails to start on Windows 11 with the error Daemon failed to start (socket: C:\Users\<user>\.agent-browser\default.sock). The root cause is that Node.js net.createServer().listen() on a Unix domain socket path returns EACCES: permission denied on this Windows environment.

---

Environment

Component	Version
agent-browser	0.9.0
OS	Windows 11
Shell	Git Bash
Node.js	v24.11.1
npm	11.8.0
Playwright	1.58.1
Installation	Global (npm install -g agent-browser)
Install path	...\AppData\Roaming\npm\agent-browser

---

Steps to Reproduce

1. Install agent-browser globally on Windows:

   npm install -g agent-browser

2. Ensure Playwright browsers are installed:

   npx playwright install chromium

3. Run any agent-browser command:

   agent-browser open "https://example.com"

4. Result: Immediate failure with:

   ✗ Daemon failed to start (socket: ...\.agent-browser\default.sock)
   

---

Expected Behavior

The daemon should start successfully and navigate the browser to the specified URL.

---

Actual Behavior

The daemon fails to start every time. No browser window opens. The error message gives no further detail beyond the socket path.

---

Root Cause Analysis

To diagnose, I tested Unix domain socket creation directly in Node.js:

const net = require('net');
const path = require('path');

const sockPath = path.join(process.env.USERPROFILE, '.agent-browser', 'default.sock');
console.log('Socket path:', sockPath);
console.log('Path length:', sockPath.length);

const server = net.createServer();
server.listen(sockPath, () => {
  console.log('Socket works!');
  server.close();
});
server.on('error', (e) => {
  console.log('Socket error:', e.message);
});

Output:

Socket path: C:\Users\jaros\.agent-browser\default.sock
Path length: 42
Socket error: listen EACCES: permission denied C:\Users\jaros\.agent-browser\default.sock

Key findings:

• The .agent-browser directory exists and is writable (directory was created by agent-browser itself).
• There is no stale socket file present (directory is empty).
• The socket path is only 42 characters long (well under the ~108 char Unix socket limit).
• The EACCES error comes from the OS-level bind() call for Unix domain sockets.
• This is a known Windows limitation: Unix domain sockets (AF_UNIX) support on Windows is inconsistent across builds and configurations. While Windows 10 1803+ added partial AF_UNIX support, it doesn't work reliably in all environments, especially:
  • Git Bash / MINGW64 / MSYS2 environments
  • Certain Windows Insider/Preview builds
  • Without elevated (Administrator) permissions in some configurations

---

Attempted Workarounds (all failed)

Attempt	Result
Deleting ~/.agent-browser/ contents and retrying	Same error
Using --headed flag	Same error
Setting DEBUG=* environment variable	Same error, no additional debug output
Setting AGENT_BROWSER_LOG=debug	Same error, no additional debug output
Running from different working directories	Same error
Reinstalling Playwright browsers (npx playwright install chromium)	Same error (browsers were already installed)

Not tested (but likely to work):

• Running terminal as Administrator (escalates privileges for AF_UNIX bind)
• Using agent-browser connect <port> with a pre-launched Chrome via CDP

---

Suggested Fix

The daemon's IPC mechanism should have a fallback for Windows when Unix domain sockets fail. Common approaches:

Option 1: Named Pipes (Recommended for Windows)

Use \\.\pipe\agent-browser-default instead of a .sock file on Windows. Node.js net module supports named pipes natively on Windows:

const pipePath = process.platform === 'win32'
  ? '\\\\.\\pipe\\agent-browser-' + sessionName
  : path.join(homeDir, '.agent-browser', sessionName + '.sock');

Option 2: TCP localhost fallback

Fall back to 127.0.0.1:<port> when Unix socket creation fails:

server.listen(sockPath, () => { /* success */ });
server.on('error', (err) => {
  if (err.code === 'EACCES' || err.code === 'ENOTSUP') {
    // Fallback to TCP
    server.listen(0, '127.0.0.1', () => {
      const port = server.address().port;
      fs.writeFileSync(sockPath + '.port', String(port));
    });
  }
});

Option 3: Better error messaging (minimum)

At minimum, the error message should include the underlying OS error to help users self-diagnose:

✗ Daemon failed to start: EACCES: permission denied on socket C:\Users\jaros\.agent-browser\default.sock
  Hint: Unix domain sockets may not work on Windows. Try: agent-browser connect <port>

---

Additional Notes

• The --debug flag and DEBUG=* environment variable produce zero additional output, making this very hard to diagnose. Adding verbose logging for daemon startup failures would greatly help.
• The issue affects all agent-browser commands since every command requires the daemon.
• The agent-browser connect <port> command (connecting to an existing Chrome via CDP) likely bypasses the daemon and would work as a workaround, but this requires users to manually launch Chrome with --remote-debugging-port.
• This is a blocker for Windows users who can't run as Administrator.

---

Related Issues / References

• Node.js docs: IPC connections on Windows — recommends \\.\pipe\ prefix for Windows IPC
• Windows AF_UNIX support limitations — Microsoft's own documentation on the feature's limitations
• Common pattern in tools like Docker, VS Code, and ESLint daemon which all use named pipes on Windows instead of Unix sockets

---

Report generated: 2026-02-07
Reporter: User running agent-browser via Claude Code CLI

[mranonymous011000001]

same issue how to fix it

[mranonymous011000001]

on windows

[HariomJangra]

Using CDP also not Fixing this Up.

PS C:\Users\Lenovo> agent-browser connect 9222
✗ Daemon failed to start (socket: C:\Users\Lenovo.agent-browser\default.sock)

[mranonymous011000001]

so @whtiehack what to do ? like switch to node one? i have tried both one both dont work for me

[whtiehack]

so @whtiehack what to do ? like switch to node one? i have tried both one both dont work for me

Sorry, what I'm experiencing is not this.

[whtiehack]

@mranonymous011000001

You can try this

[Environment]::SetEnvironmentVariable("AGENT_BROWSER_HOME", "$env:APPDATA\npm\node_modules\agent-browser", "User")

If you install by npm global

[mranonymous011000001]

okay great done, issue solved.

[PHPSJ]

@mranonymous011000001

You can try this

[Environment]::SetEnvironmentVariable("AGENT_BROWSER_HOME", "$env:APPDATA\npm\node_modules\agent-browser", "User")

If you install by npm global

还是没成功

[whtiehack]

@PHPSJ 你这个可能跟 #393 里分析的 Windows 路径问题有关，也可能是 Unix socket 权限的问题。

先试试设环境变量的时候用完整的绝对路径，别用 $env:APPDATA：

[Environment]::SetEnvironmentVariable("AGENT_BROWSER_HOME", "C:\Users\你的用户名\AppData\Roaming\npm\node_modules\agent-browser", "User")

设完重启终端再试。

还不行的话试试管理员权限运行终端，有些 Windows 环境 Unix socket 需要提权。

[ooropuloo]

I encountered the same issue on Windows. The root cause is Unix socket incompatibility in Windows environments (related: #398).

Environment:

• Windows 11
• Claude Code
• Windows Terminal
• Node.js v23.8.0
• agent-browser@0.9.1

Error output (when running from Claude Code's default bash shell):

Bash(sleep 3 && agent-browser --cdp 9222 snapshot -i 2>&1)
  Error: Exit code 1
  ✗ Daemon failed to start (socket: C:\Users\Public\.agent-browser\default.sock)

Even with --cdp flag, it still attempts to create a Unix socket and fails under Git Bash/MSYS environment.

Workaround: Use PowerShell + CDP mode

1. Launch Chrome with a dedicated user-data-dir:

   Start-Process 'C:\Program Files\Google\Chrome\Application\chrome.exe' -ArgumentList '--remote-debugging-port=9222','--user-data-dir=C:\temp\chrome-cdp-profile'

2. Connect via CDP:

   powershell -Command "& 'C:\nvm4w\nodejs\agent-browser.cmd' --cdp 9222 open '<url>'"
   powershell -Command "& 'C:\nvm4w\nodejs\agent-browser.cmd' --cdp 9222 screenshot '<path>'"
   powershell -Command "& 'C:\nvm4w\nodejs\agent-browser.cmd' --cdp 9222 snapshot -i"

Important notes:

• Commands must be executed via powershell -Command. Running under Git Bash/MSYS will fail due to Unix socket issues.
• If Chrome is already running, --remote-debugging-port will be silently ignored. Either close existing instances or use a separate --user-data-dir.
• Since this connects to a real Chrome browser, it won't be blocked by Google reCAPTCHA.

I also added this as a Claude Code instruction in claude.md so the agent automatically uses CDP mode on Windows.

[superchangme]

 xxx  agent-browser open example.com --headed
✗ Daemon failed to start (socket: C:\Users\xxx.agent-browser\default.sock)

when will you fix it? thank you!

====
etc: i use nvm