PilotDeck

Open-source agent workspace

Depending on your operating system and how you plan to use it, choose the desktop app, the one-click install or a build from source. Follow the guide to check your environment, start the service and handle day-to-day maintenance, and refer to the common installation and connection issues.

1. Requirements

Item	Requirement
Operating system	Windows 10 or later / macOS 14 or later / Ubuntu 22.04 or later, all with a desktop client; the one-click install script covers macOS / Linux / Windows
LLM API Key	At least one large language model callable through an API (supported protocols include openai, openai-responses, anthropic, google, and it is compatible with providers such as DeepSeek, Qwen, Kimi, MiniMax and OpenRouter)
Ports	3001 (Web UI) and 18789 (Gateway) must be free; if the web port is taken, the launcher automatically tries another port

2. Installation

Option 1: Desktop app (recommended)

Platform	File
macOS (arm64)	PilotDeck-2026.1013.0-mac-arm64.dmg
macOS (Intel / x64)	PilotDeck-2026.1013.0-mac-x64.dmg
Windows (x64)	PilotDeck-2026.1013.0-win-x64-setup.exe

The latest installers are available at: https://github.com/OpenBMB/PilotDeck/releases

Platform	System requirement	Processor architecture	Installer format
Windows	Windows 10 or later	x64, ARM64	.exe
macOS	macOS 14 or later	Intel (x64), Apple Silicon (ARM64)	.dmg
Linux (DEB)	Ubuntu 22.04 or later	x64, ARM64	.deb
Linux (RPM)	Rocky Linux 9 or later	x64, ARM64	.rpm

How to install:

• Windows: Double-click the downloaded .exe installer and follow the setup wizard.
• macOS: Double-click the downloaded .dmg image, drag PilotDeck into the Applications folder, then launch it from Applications.
• Linux (DEB): Open a terminal in the folder containing the package and install it with APT (dependencies are handled automatically): sudo apt install ./PilotDeck-VERSION-linux-x64.deb
• Linux (RPM): Open a terminal in the folder containing the package and install it with DNF (dependencies are handled automatically): sudo dnf install ./PilotDeck-VERSION-linux-x64.rpm

The commands above use the x64 package as an example; replace VERSION with the actual version number. On ARM64 devices, replace x64 in the file name with arm64. After the Linux installation finishes, you can launch PilotDeck from the application menu.

Option 2: One-click install (macOS / Linux / Windows)

Bash

curl -fsSL https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.sh | bash

The install script checks for Git and a supported Node.js 22 runtime, installs dependencies and builds the web frontend. If the terminal asks for a password, enter your Mac login password (it is not shown as you type; this is normal).

• Install path: ~/.pilotdeck/app/
• Config file: ~/.pilotdeck/pilotdeck.yaml
• Command: pilotdeck

Windows: Open PowerShell with normal user privileges and run:

PowerShell

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.ps1 | iex"

The script installs PilotDeck under %USERPROFILE%\.pilotdeck, checks for Node.js 22.13+ and node:sqlite, installs missing dependencies via winget when available, and creates a pilotdeck.cmd launcher in %USERPROFILE%\.pilotdeck\bin. Git LFS fetch failures can be ignored.

Once the installation finishes, the script starts PilotDeck and prints the Web UI address, but it does not open a browser automatically. Copy the address shown in the terminal, or run:

PowerShell

Start-Process "http://localhost:3001"

The next time you use it, open a new PowerShell window and run:

PowerShell

pilotdeck

If you get a message that pilotdeck cannot be found, run the launcher directly:

PowerShell

& "$HOME\.pilotdeck\bin\pilotdeck.cmd"

The default address is http://localhost:3001. If the port is taken, the launcher tries another port, so always use the address printed in the starting terminal. Run pilotdeck status to check the running state. When you are done, return to the PowerShell window running the service and press Ctrl+C to shut it down cleanly.

The one-click install uses the GitHub main branch; running the install command again fetches the current version.

If the default web port is already in use, you can start on another port, for example:

Bash

pilotdeck --port 8080

In that case, use the address actually printed in the terminal. The web interface port differs from the internal port of the AI proxy; do not mix them up.

Option 3: Build from source (for developers)

All systems require Node.js >=22.13.0 <23, Git, Python 3, system build tools and ripgrep. Git LFS is only used to download large demo media and is not required for core functionality.

macOS

Step 1: Install system tools.

Install the Xcode Command Line Tools:

Bash

xcode-select --install

If you use Homebrew, you can install Git LFS and ripgrep:

Bash

brew install git-lfs ripgrep

Then install Node.js 22 with your preferred Node.js version manager. For example, with fnm:

Bash

curl -fsSL https://fnm.vercel.app/install | bash
# run after reopening the terminal
fnm install 22
fnm use 22
node --version

node --version must print v22.13.0 or a higher v22.x. On an Intel Mac you should also run node -p "process.arch" and confirm that it outputs x64.

Step 2: Clone the source code.

Run this in the directory where you want to keep the code:

Bash

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenBMB/PilotDeck.git
cd PilotDeck

Step 3: Enable pnpm.

Bash

node --version
corepack enable

If your current Node.js environment does not have Corepack, install the pnpm version specified in the official source guide:

Bash

npm install -g pnpm@10.32.1
pnpm --version

Step 4: Install project dependencies.

Still in the root of the PilotDeck repository, run:

Bash

corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

If you used a global pnpm in the previous step, run this instead:

Bash

pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

If installing native dependencies reports that Python is missing distutils, try specifying the system Python and reinstalling:

Bash

PYTHON=/usr/bin/python3 corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

Step 5: Start the web service.

A source build does not create a global pilotdeck command. Choose one of the modes below and start it from the repository root.

Development mode supports hot reload and is suited to modifying and debugging the source:

Bash

cd ui
npm run dev

Open the development address printed in the terminal in your browser; the default is http://localhost:5173. If the port is taken, the dev launcher tries another port.

Production mode is suited to normal use and long-running operation:

Bash

cd ui
npm run start

Open http://localhost:3001 in your browser. Pick only one of the two modes; keep the starting terminal running, and press Ctrl+C to stop the service.

Windows

There are two paths for building from source on Windows: WSL2 Ubuntu is recommended, but native PowerShell is also an option.

WSL2 Ubuntu (recommended)

Step 1: Install WSL2 and Ubuntu.

Run this in an administrator PowerShell:

PowerShell

wsl --install -d Ubuntu

If the system asks for a restart, restart first and complete the initial Ubuntu user setup. All the following commands are run in the Ubuntu terminal, not in PowerShell.

Step 2: Install system tools and Node.js in Ubuntu.

Bash

sudo apt-get update
sudo apt-get install -y git git-lfs ripgrep build-essential python3
curl -fsSL https://fnm.vercel.app/install | bash
# run after reopening the Ubuntu terminal
fnm install 22
fnm use 22
node --version

Confirm that Node.js is v22.13.0 or a higher v22.x.

Step 3: Clone the source code in Ubuntu.

Bash

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenBMB/PilotDeck.git
cd PilotDeck

Step 4: Enable pnpm and install dependencies.

Bash

corepack enable
corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

If Corepack is not available, use this instead:

Bash

npm install -g pnpm@10.32.1
pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

Step 5: Start the web service in Ubuntu.

Choose one of the modes from the repository root. Development mode supports hot reload:

Bash

cd ui
npm run dev

Open the development address printed in the terminal in your browser; the default is http://localhost:5173. If the port is taken, the dev launcher tries another port.

Production mode is suited to normal use and long-running operation:

Bash

cd ui
npm run start

Open http://localhost:3001 in your browser. Pick only one of the two modes; keep the Ubuntu terminal running, and press Ctrl+C to stop the service.

Native Windows PowerShell

Step 1: Install system tools.

Run these line by line in PowerShell:

PowerShell

winget install OpenJS.NodeJS.LTS
winget install Git.Git
winget install GitHub.GitLFS
winget install Python.Python.3.12
winget install BurntSushi.ripgrep.MSVC
winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

After the installation finishes, close and reopen PowerShell, then check the environment:

PowerShell

git lfs install
node --version
node -p "process.arch"
npm --version
git --version
python --version
rg --version

node --version must print v22.13.0 or a higher v22.x, and process.arch should output x64. If the Node.js LTS installed by winget is no longer v22.x, switch versions first with a Node.js version manager or the official x64 Node.js 22 archive.

Step 2: Clone the source code.

PowerShell

$env:GIT_LFS_SKIP_SMUDGE = "1"
git clone https://github.com/OpenBMB/PilotDeck.git
Set-Location PilotDeck

Step 3: Enable pnpm.

PowerShell

corepack enable

If Corepack is not available in your environment:

PowerShell

npm.cmd install -g pnpm@10.32.1
pnpm --version

Step 4: Install project dependencies.

PowerShell

corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

If you are using a global pnpm, run this instead:

PowerShell

pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

If PowerShell reports that npm.ps1 or pnpm.ps1 cannot be loaded because of the execution policy, use npm.cmd or pnpm.cmd respectively.

Step 5: Start the web service.

Choose one of the modes from the repository root. Development mode supports hot reload:

PowerShell

Set-Location ui
npm.cmd run dev

Open the development address printed in the terminal in your browser; the default is http://localhost:5173. If the port is taken, the dev launcher tries another port.

Production mode is suited to normal use and long-running operation:

PowerShell

Set-Location ui
npm.cmd run start

Open http://localhost:3001 in your browser. Pick only one of the two modes; keep the PowerShell window running, and press Ctrl+C to stop the service.

Linux

The example below uses Debian/Ubuntu; the system dependency commands for Fedora/RHEL and Arch Linux are also listed in this step.

Step 1: Install system tools.

Debian/Ubuntu:

Bash

sudo apt-get update
sudo apt-get install -y git git-lfs ripgrep build-essential python3

Fedora/RHEL:

Bash

sudo dnf install -y git git-lfs ripgrep gcc gcc-c++ make python3

Arch Linux:

Bash

sudo pacman -Sy --needed git git-lfs ripgrep base-devel python

Then install Node.js 22. For example, with fnm:

Bash

curl -fsSL https://fnm.vercel.app/install | bash
# run after reopening the terminal
fnm install 22
fnm use 22
node --version

Confirm that the output is v22.13.0 or a higher v22.x; do not use Node.js 23 or later.

Step 2: Clone the source code.

Bash

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenBMB/PilotDeck.git
cd PilotDeck

Step 3: Enable pnpm.

Bash

corepack enable

If Corepack is not available in your environment:

Bash

npm install -g pnpm@10.32.1
pnpm --version

Step 4: Install project dependencies.

Bash

corepack pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

If you are using a global pnpm, run this instead:

Bash

pnpm install --frozen-lockfile --filter pilotdeck --filter pilotdeck-ui

Step 5: Start the web service.

Choose one of the modes from the repository root. Development mode supports hot reload:

Bash

cd ui
npm run dev

Open the development address printed in the terminal in your browser; the default is http://localhost:5173. If the port is taken, the dev launcher tries another port.

Production mode is suited to normal use and long-running operation:

Bash

cd ui
npm run start

Open http://localhost:3001 in your browser. Pick only one of the two modes; keep the starting terminal running, and press Ctrl+C to stop the service.

The clone commands for all of the systems above use GIT_LFS_SKIP_SMUDGE=1 to skip the large demo media, which does not affect PilotDeck's core functionality. If you need those files later, run this from the repository root:

Bash

git lfs pull

The dependency installation commands install the Gateway and the Web UI according to the pnpm-lock.yaml committed in the repository, and exclude the Electron packaging dependencies that a web deployment does not need. Do not replace them with npm install.

On the first start of a source build, if no valid ~/.pilotdeck/pilotdeck.yaml is found, the Web UI first enters Onboarding. After you save the model provider, API Key and model, PilotDeck writes the configuration and starts the Gateway automatically.

3. Day-to-day use in the browser

Action	How
Start	Run pilotdeck in a terminal
Use	Open http://localhost:3001 in a browser
Stop	Press Ctrl + C in the terminal
Update	Run the one-click install command again (existing config is not overwritten)

CLI commands

Bash

pilotdeck "Analyze the current project structure"     # one-off conversation
pilotdeck server                 # start the long-running Gateway service (default port 18789)
pilotdeck tui                    # interactive terminal UI
pilotdeck cron list              # list scheduled tasks
pilotdeck cron create --session <key> --message <text> --cron "<expression>"  # create a scheduled task

4. FAQ

Q: Connection test fails

A: Check that the API Key is correct, the network is reachable, the provider balance is sufficient, and the API Base URL includes /v1.

Q: Running pilotdeck in the terminal reports that the command is not found

A:

1. Check whether it is on your PATH:

   Bash

   which pilotdeck
   ls -la /usr/local/bin/pilotdeck
   ls -la ~/.local/bin/pilotdeck

2. If it is linked into ~/.local/bin, make sure that directory is on your PATH:

   Bash

   # add to ~/.zshrc or ~/.bashrc
   export PATH="$HOME/.local/bin:$PATH"
   source ~/.zshrc

3. Create the link manually:

   Bash

   ln -sf ~/.pilotdeck/app/ui/server/cli.js /usr/local/bin/pilotdeck

Q: Port conflict (Port 3001/18080 already in use)

A:

Bash

lsof -i :3001 && kill -9 <PID>

Q: Wrong Node.js version

A:

Bash

# using fnm
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22
fnm use 22

# or using nvm
nvm install 22
nvm use 22

# verify the version
node --version

Q: npm install fails

A: Clear the cache and retry

Bash

npm cache clean --force
cd ~/.pilotdeck/app
rm -rf node_modules package-lock.json
npm install

If it is a network issue, you can set an npm mirror:

Bash

npm config set registry https://registry.npmmirror.com
npm install

Q: The desktop app won't start (macOS) / crashes on launch

A: A DMG received through sandboxed IM apps such as Feishu or WeChat carries the com.apple.provenance extended attribute, which makes Gatekeeper refuse to run it; a DMG downloaded directly from a browser or transferred via AirDrop does not have this problem.

Bash

# Option 1: run the repair script
bash install-pilotdeck.sh

# Option 2: clear the extended attributes manually
xattr -cr /Applications/PilotDeck.app
open /Applications/PilotDeck.app

Alternatively, go to System Settings → Privacy & Security and allow PilotDeck to run.

Q: The install script reports git is not installed?

A: Install the Xcode Command Line Tools: xcode-select --install

If you run into other problems during installation, configuration or use, ask in the Feishu community group and the technical team will be happy to help.

5. Related Resources

Topic	Link
Repository	OpenBMB/PilotDeck
Desktop installers	GitHub Releases
Official website	pilotdeck.openbmb.cn
Tutorial docs	PilotDeck Docs