4.0.3: install.sh crashes on headless Linux — hardcodes --mode gui with no display detection

[zeddy303]

Environment

• PAI Version: v4.0.3
• OS: Linux x86_64 (headless server, no X11/Wayland)
• Bun: v1.3.8
• Git: 2.47.3

Description

Running install.sh on a headless Linux server (no display server) crashes immediately after the prerequisite checks
pass. The script hardcodes --mode gui which launches Electron, but Electron requires X11 or Wayland.

This affects all headless environments: servers, SSH sessions, containers, CI/CD, WSL without display forwarding.

Steps to Reproduce

1. SSH into a headless Linux server
2. Run ./install.sh from the PAI v4.0.3 release

Expected Behavior

The installer detects the headless environment and falls back to the CLI wizard (--mode cli), which main.ts already
supports.

Actual Behavior

ℹ Platform: Linux (x86_64)
✓ curl found
✓ Git found: git version 2.47.3
✓ Bun found: v1.3.8
✓ Claude Code found
ℹ Launching installer...

Starting PAI Installer GUI...

pai-installer@4.0.3 start
electron .

[2569344:0305/022508.591188:ERROR:ozone_platform_x11.cc(246)] Missing X server or $DISPLAY
[2569344:0305/022508.591253:ERROR:env_config_provider.cc(29)] The platform failed to initialize. Exiting.

Electron segfaults (SIGSEGV). Installation fails completely.

Root Cause

install.sh line 156:
exec bun run "$INSTALLER_DIR/main.ts" --mode gui

This unconditionally forces GUI mode. Meanwhile, main.ts already supports three modes (cli, web, gui) — the bootstrap
script just never uses anything other than gui.

Suggested Fix

Replace line 156 in install.sh with display detection:

Detect display availability — default to CLI, upgrade to GUI if display present

if [[ -n "${DISPLAY:-}" ]] || [[ -n "${WAYLAND_DISPLAY:-}" ]]; then
INSTALL_MODE="gui"
else
info "No display detected — using CLI installer"
INSTALL_MODE="cli"
fi

exec bun run "$INSTALLER_DIR/main.ts" --mode "$INSTALL_MODE"

This keeps GUI as the default on desktops while making headless environments work out of the box.

Workaround

Skip install.sh and invoke main.ts directly:

bun run /path/to/PAI-Install/main.ts --mode cli

[zeddy303]

Fix submitted in #914.

One additional finding: the v4.0.2 changelog mentions a headless CLI fix, but that fix also has a bug. Both v4.0.2 and v4.0.3 use set -euo pipefail, and the detection references bare $DISPLAY/$WAYLAND_DISPLAY — which causes set -u to throw an unbound variable error on headless servers before the if-statement even evaluates. The PR uses ${VAR:-} guards to handle this correctly.

[Drizzt321]

@zeddy303 I also found that you can just sync around ~/.claude with following being ignored:

// Machine-local per-session caches — regenerate at session start, no sync value
MEMORY/STATE/model-cache.txt
MEMORY/STATE/session-name-cache.sh
MEMORY/STATE/events.jsonl

And then to invoke just need to make sure the bun is installed and on your .bashrc or other shell rc file:

# bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

And then the PAI alias

# PAI alias
alias pai='bun /home/drizzt/.claude/PAI/Tools/pai.ts'

And that just worked. Does require the installer to run on a machine with GUI, specifically X11 or X11/Wayland compat tools.

[zeddy303]

@zeddy303 I also found that you can just sync around ~/.claude with following being ignored:

// Machine-local per-session caches — regenerate at session start, no sync value
MEMORY/STATE/model-cache.txt
MEMORY/STATE/session-name-cache.sh
MEMORY/STATE/events.jsonl

And then to invoke just need to make sure the bun is installed and on your .bashrc or other shell rc file:

# bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

And then the PAI alias

# PAI alias
alias pai='bun /home/drizzt/.claude/PAI/Tools/pai.ts'

And that just worked. Does require the installer to run on a machine with GUI, specifically X11 or X11/Wayland compat tools.

The issue is I have PAI on a remote headless server, and so there isn't a gui.

[Drizzt321]

@zeddy303 but can you install on a system that DOES have GUI capabilities? And then just copy/sync the files over, and set the alias?