vercel-labs / vercel-labs/agent-browser

--headed fails on Linux: DISPLAY env var not passed to browser subprocess

Open
#369 0 comments 4 reactions 0 assignees View on GitHub

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 (--headed not 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.