How to Install PAI with the Electron GUI: A Complete Guide

To install PAI with the Electron GUI, run the install.sh bootstrap script from the danielmiessler/Personal_AI_Infrastructure repository, which automatically launches the graphical installer on port 1337.

PAI (Personal AI Infrastructure) provides a visual installation experience through its Electron-based GUI wrapper. This guide walks through the complete process of installing PAI with the Electron GUI, referencing the actual source code implementation in the Releases/v3.0/.claude/PAI-Install/ directory.

Prerequisites and System Requirements

Before you install PAI with the Electron GUI, ensure your system meets the following requirements:

• curl and git must be installed
• Bun runtime (automatically installed by the bootstrap script if missing)
• npm (required for Electron dependency installation)
• macOS, Linux, or Windows operating system

The bootstrap script in install.sh handles dependency verification and automatically downloads Bun from https://bun.sh if it is not present on your system.

Step-by-Step Installation Process

Step 1: Bootstrap with install.sh

The installation begins with the Bash bootstrap script located at Releases/v3.0/.claude/PAI-Install/install.sh. This script performs initial system checks and hands off execution to the TypeScript entry point.

# Clone the repository

git clone https://github.com/danielmiessler/Personal_AI_Infrastructure.git
cd Personal_AI_Infrastructure/Releases/v3.0

# Run the installer (GUI mode is default)

./PAI-Install/install.sh

Step 2: Mode Selection in main.ts

The TypeScript entry point main.ts parses the --mode argument to determine which installation interface to launch. The three available modes are cli, web, and gui. When you install PAI with the Electron GUI, the script automatically selects gui mode by default.

In main.ts, the mode dispatch logic prepares the Electron wrapper located in the electron/ directory when gui mode is detected.

Step 3: Electron Dependency Installation

If the Electron package lock file (electron/node_modules/.package-lock.json) does not exist, the installer automatically runs npm install inside the electron/ folder. This pulls in Electron ^34.0.0 and its dependencies.

This step occurs automatically in main.ts (lines 35-48) without requiring manual intervention.

Step 4: macOS Quarantine Cleanup

On macOS systems, the installer clears extended attributes to prevent the "app is damaged" Gatekeeper warning. The script executes xattr -cr on the Electron application bundle automatically (handled in main.ts lines 50-57).

Step 5: Launching the Electron GUI

The final step spawns npm start inside the electron/ directory. The start script defined in electron/package.json executes electron ., which launches the Electron wrapper (electron/main.js).

The Electron process performs the following actions:

1. Starts the Bun-based installer server (bun run main.ts --mode web) on http://127.0.0.1:1337
2. Waits for the server to become reachable via TCP polling (lines 38-62 in main.js)
3. Opens a frameless BrowserWindow pointing to the local URL (lines 95-115 in main.js)
4. Handles cleanup by killing the Bun server process when the window closes (lines 36-44 in main.js)

Understanding the Electron Wrapper Architecture

The Bun Web Server Backend

When you install PAI with the Electron GUI, the graphical interface is actually a wrapper around the same Bun-based web server used in web mode. The Electron wrapper (electron/main.js) spawns the server process and loads the wizard UI at http://127.0.0.1:1337 inside a native window.

This architecture ensures consistency across installation modes while providing the enhanced user experience of a native application.

Audio Autoplay and Cross-Platform Benefits

The Electron GUI disables Chromium's autoplay policy by appending the command-line switch app.commandLine.appendSwitch("autoplay-policy", "no-user-gesture-required"). This enables voice prompts and audio feedback to work immediately without user interaction.

Additional benefits of choosing to install PAI with the Electron GUI include:

• Visual wizard interface – Step-by-step guidance through configuration
• Automatic dependency handling – Missing Electron modules are installed automatically
• macOS Gatekeeper compatibility – Quarantine flags are cleared automatically
• Cross-platform consistency – Identical experience on macOS, Linux, and Windows

Alternative Installation Methods

Forcing CLI Mode

If you prefer to bypass the GUI and use the terminal wizard instead, pass the --mode cli flag to the TypeScript entry point after running the bootstrap script:

# Run bootstrap, then force CLI mode

./PAI-Install/install.sh && bun run .claude/PAI-Install/main.ts --mode cli

Explicit GUI Mode Launch

After the initial bootstrap has installed Bun, you can explicitly launch the Electron GUI by specifying the mode:

bun run .claude/PAI-Install/main.ts --mode gui

This command duplicates the default behavior of the installer but makes the graphical mode explicit.

Verifying Your Installation

To confirm that PAI is running correctly after you install it with the Electron GUI:

# Verify the Bun server is listening on port 1337

lsof -i :1337

# Check for the Electron process

ps aux | grep electron

You should see the Bun process listening on 127.0.0.1:1337 and an Electron process running the wrapper application.

Summary

• PAI provides three installation modes: CLI, web server, and Electron GUI, with the GUI serving as the default for the best user experience.
• The bootstrap process: install.sh checks for curl, git, and Bun, then executes main.ts which dispatches to the Electron wrapper in electron/.
• Automatic setup: The installer handles npm dependencies for Electron ^34.0.0, clears macOS quarantine flags, and launches the frameless browser window pointing to http://127.0.0.1:1337.
• Architecture: The Electron GUI wraps the Bun-based web server, providing audio autoplay support and cross-platform consistency while maintaining the same underlying installation logic.

Frequently Asked Questions

What is the default installation mode for PAI?

The default installation mode is GUI. When you run ./PAI-Install/install.sh, the bootstrap script executes main.ts without an explicit mode flag, which defaults to launching the Electron GUI. This provides the visual wizard experience with automatic audio playback and polished interface elements.

Why does the Electron GUI require npm install?

The Electron GUI requires npm install because the wrapper is a separate Node.js application located in the electron/ directory. When main.ts detects GUI mode, it checks for the existence of electron/node_modules/.package-lock.json. If this file is missing, the installer automatically runs npm install to download Electron ^34.0.0 and its dependencies before launching the graphical interface.

How do I fix the "app is damaged" error on macOS?

The PAI installer automatically handles this error by clearing macOS Gatekeeper quarantine flags. In main.ts (lines 50-57), the script executes xattr -cr on the Electron application bundle during the installation process. If you encounter this error when running the installer manually, you can resolve it by running xattr -cr on the PAI application bundle or by allowing the application in System Settings under Privacy & Security.

Can I run PAI without the GUI after installation?

Yes, you can run PAI without the GUI by using the CLI or web server modes. After the initial bootstrap has installed Bun, you can launch the terminal wizard by running bun run .claude/PAI-Install/main.ts --mode cli. Alternatively, you can run the web server mode with --mode web and access the installer through a standard browser at http://127.0.0.1:1337 without the Electron wrapper.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}