-
Notifications
You must be signed in to change notification settings - Fork 16.3k
feat(browse): add GSTACK_HEADED_NOGPU opt-in for headed mode on virtual displays (Xvnc/Xvfb)#1915
feat(browse): add GSTACK_HEADED_NOGPU opt-in for headed mode on virtual displays (Xvnc/Xvfb) #1915auroracapital wants to merge 1 commit into
Conversation
On headless virtual displays (Xvnc/Xvfb on EC2/Linux), Playwright's bundled Chromium crashes at GPU process init (SIGTRAP) when headed mode is requested. This renders headed browse completely unusable on remote Linux servers. Add GSTACK_HEADED_NOGPU=1 env opt-in that appends --disable-gpu, --disable-gpu-compositing, --disable-software-rasterizer, and --disable-dev-shm-usage to launch args so the GPU process is bypassed entirely. This keeps headed mode alive on VNC-backed displays without affecting users on real displays who don't set the flag.
Merging to main in this repository is managed by Trunk.
- To merge this pull request, check the box to the left or comment
/trunk mergebelow.
After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here
auroracapital
commented
Jun 9, 2026
/trunk merge
An error occurred while submitting your PR to the queue: Only users that are a part of this repo's Trunk organization or have write permissions to the repo can submit a PR to the queue
jbetala7
commented
Jun 11, 2026
Directionally useful for VNC-backed boxes. Two notes:
1. Coverage gap on the handoff path. The NOGPU flags are only added to the launchArgs array in launchHeaded() (~L439). The headless→headed handoff relaunch builds its own launchArgs = ['--hide-crash-restore-bubble'] (~L1559) and never gets them, so a /browse session that starts headless and is later promoted to headed on a Xvnc/Xvfb display would still SIGTRAP — the exact crash this PR targets. Adding the same GSTACK_HEADED_NOGPU block to that second launchArgs would close the path.
2. --disable-dev-shm-usage isn't a GPU flag — it controls /dev/shm usage, not GPU init. Fine to keep (it's a common headless-stability flag), but it widens the opt-in beyond what the env var name advertises; a one-line note in the comment/docs would help.
Coordination: #1933 adds a general GSTACK_CHROMIUM_ARGS passthrough that could express these GPU flags directly, and both it and #1968 touch this same launch path — flagging for merge-order / possible consolidation.
Problem
On headless Linux servers using virtual displays (Xvnc, Xvfb), Playwright's bundled Chromium crashes with SIGTRAP during GPU process initialization when headed mode is requested. This makes
/browse --headedcompletely non-functional on remote Linux dev boxes.Root cause: virtual display drivers (Xvnc, Xvfb) have no real GPU. Chromium's GPU process init path raises SIGTRAP when it can't initialize hardware acceleration, crashing the browser before the page loads.
Solution
Add an opt-in env var
GSTACK_HEADED_NOGPU=1that appends GPU-disabling Chromium flags at launch:--disable-gpu--disable-gpu-compositing--disable-software-rasterizer--disable-dev-shm-usageThis bypasses the GPU process entirely, keeping headed mode alive on VNC-backed virtual displays.
Usage
Or export it for a session:
export GSTACK_HEADED_NOGPU=1 browse --headed ...Safety
Context
This came up while using gstack
/browse --headedon an EC2 dev box with a VNC display for interactive browser automation. The fix unblocks headed mode for the growing number of users running Claude Code on remote Linux servers.