vercel-labs / vercel-labs/agent-browser
--headed fails on Linux: DISPLAY env var not passed to browser subprocess
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 42.9k
- Forks
- 2.9k
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 45
Description
Description
When using --headed mode on Linux with a virtual display (Xvnc, Xvfb), the browser fails to launch because the DISPLAY environment variable is not forwarded to the Chromium subprocess.
Steps to Reproduce
# Start virtual display
Xvnc :99 -geometry 1280x720 -depth 24 &
DISPLAY=:99 openbox &
# This fails
DISPLAY=:99 agent-browser open --headed https://example.com
Expected: Browser launches on display :99
Actual: Error "Missing X server or $DISPLAY"
✗ browserType.launch: Target page, context or browser has been closed
╔══════════════════════════════════════════════════════════════════════╗
║ Looks like you launched a headed browser without having a XServer ║
║ running. Set either 'headless: true' or use 'xvfb-run'. ║
╚══════════════════════════════════════════════════════════════════════╝
[pid][err] Missing X server or $DISPLAY
[pid][err] The platform failed to initialize. Exiting.
Root Cause
In dist/browser.js, Playwright's launch() is called without the env option:
// Line ~927
this.browser = await launcher.launch({
headless: options.headless ?? true,
executablePath: options.executablePath,
args: options.args,
});
Without env, Playwright doesn't forward environment variables (including DISPLAY) to the browser subprocess.
Suggested Fix
Pass the environment to browser subprocess:
this.browser = await launcher.launch({
headless: options.headless ?? true,
executablePath: options.executablePath,
args: options.args,
env: { ...process.env },
});
Same change needed for launchPersistentContext() calls (~lines 897, 913).
Workaround
Launch Chrome manually with DISPLAY set and connect via CDP:
DISPLAY=:99 chrome --remote-debugging-port=9222 --no-sandbox &
agent-browser --cdp 9222 open https://example.com
Environment
- OS: Ubuntu 24.04
- agent-browser: v0.8.x (compiled binary)
- Display: TigerVNC (Xvnc) on
:99 - Node.js: v24
Related Issues
- #155 (
--headednot working in WSL/Ubuntu) - #150 (no browser popup in headed mode)
Use Case
AI agents running in cloud VMs need headed mode for visual debugging via VNC/noVNC.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Inspect the browser launch calls in dist/browser.js around lines 897, 913, and 927, starting with the reported missing DISPLAY error. Verify the headed Linux reproduction with DISPLAY=:99 and check that the persistent-context and regular launch paths pass the environment through. Done means the browser starts on the requested virtual display without requiring the CDP workaround.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, linux
- Domain
- cli, devtools
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100