Skip to main content
There are two normal ways to run Pioneer. For personal use on one computer, install the desktop app. It can bring up a local gateway for you, so you do not need to think about services, ports, or tokens on the first run. For a shared machine, a server, or a machine that should keep working while your laptop is closed, install the gateway directly. Then connect to it from the desktop app.
Pioneer is early-stage software. Start in a test environment and only move important work into Pioneer after you understand how tools behave on your machine.
Tools are not sandboxed yet. A tool run executes as the same OS user that runs the gateway.

​
Local Desktop Install

Choose this if you want the fastest path: download the app, open it, start working.
Download the Pioneer .dmg, open it, and move Pioneer.app into Applications. When the app opens for the first time, it can start a local gateway for you.
The desktop app is the right starting point if your goal is simply “use Pioneer on this computer.” It keeps the first setup small: you install the UI, the UI manages the local gateway, and then you add a model provider.
The desktop app uses bundled gateway assets and the native install flow for local setup. The shell bootstrap scripts below are mainly for direct gateway installs.

​
Remote Gateway Install

Install the gateway directly when you want Pioneer to live on another machine: a workstation, a server, a home box, a lab machine, or a remote environment with access to specific files and tools. On macOS or Linux: 
curl -fsSL https://getpioneer.dev/install.sh | bash
To install the native computer-use gateway variant without installing the desktop app: 
curl -fsSL https://getpioneer.dev/install.sh | bash -s -- --computer-use
On Windows PowerShell: 
iwr -useb https://getpioneer.dev/install.ps1 | iex
To install the native computer-use gateway variant from PowerShell: 
$env:PIONEER_INSTALL_COMPUTER_USE="1"; iwr -useb https://getpioneer.dev/install.ps1 | iex
On Windows CMD: 
curl -fsSL https://getpioneer.dev/install.cmd -o install.cmd && install.cmd && del install.cmd
The installer downloads the gateway release, verifies checksums, installs the pioneer CLI, and registers a current-user gateway service.

​
Service lifecycle by OS

PlatformService modePersistence behavior
Linuxsystemd --user serviceRequires systemd linger so the gateway survives logout and starts after reboot
macOSper-user LaunchAgentStarts after the user logs in; not available as a boot-time LaunchDaemon before login
Windowscurrent-user Scheduled TaskStarts at user logon; not available as a boot-time Windows Service before login
On Linux server or headless installs, the installer validates and tries to enable systemd lingering for the current user. If your OS policy denies that operation, run this once on the gateway machine and then rerun the installer: 
sudo loginctl enable-linger "$USER"
You can choose a channel or exact version when release assets exist for your platform: 
--channel stable|beta|canary
--version x.y.z
--computer-use
--headless
--no-start
--force-start
Channel, version, and gateway variant selection depend on matching release assets being published for the target platform. The default gateway asset is headless. The computer-use variant includes native desktop-control dependencies and uses release assets with a -computer-use suffix.

​
Check That It Runs

After a gateway install, open a new terminal and run: 
pioneer status
The status output should tell you whether the service is active, which address it listens on, whether the gateway is reachable, and where its runtime home lives. To inspect secret storage health without printing secret values, run: 
pioneer secrets status
If your shell cannot find pioneer, open a new terminal. On Unix systems, make sure ~/.local/bin is in your PATH: 
export PATH="$HOME/.local/bin:$PATH"

​
Connect The Desktop App

A local gateway usually appears in the desktop app automatically. For a remote gateway, first issue a token on the machine that runs the gateway: 
pioneer issue-superuser-token
Then add a gateway connection in the desktop app using the gateway host, port, and token. Give it a plain name you will recognize later, such as Work Gateway, Home Server, or Sandbox. Remember that the desktop app is only the client. If you connect to a gateway on a server, tools run on that server and see that server’s files, environment variables, network, and permissions. Saved desktop gateway tokens are stored in the desktop keystore. The desktop registry stores token refs, not raw bearer tokens.

​
Bind Address And Port

The production gateway listens on: 
[gateway]
listen_addr = "0.0.0.0:17878"
For local-only use, bind it to localhost: 
[gateway]
listen_addr = "127.0.0.1:17878"
Config files live here:
PlatformConfig path
macOS~/Library/Application Support/pioneer/config.toml
Linux~/.config/pioneer/config.toml
Windows%APPDATA%\pioneer\config.toml
Restart the gateway after changing the address: 
pioneer stop
pioneer start
Do not expose a gateway broadly on the public internet. Use firewall rules, trusted networks, and tokens carefully.

​
Update Or Stop

Update the gateway with: 
pioneer update
You can also update from a specific release channel: 
pioneer update --source release --channel stable
Release-based updates preserve the installed gateway variant. A headless gateway updates from the standard asset name; a computer-use gateway updates from the -computer-use asset name. Stop and unregister the current-user service with: 
pioneer stop
The current CLI exposes stop, not a separate uninstall command. Back up runtime data before manually deleting Pioneer directories.

​
Next

Once the gateway is running, go to Quick Start and configure your first model provider.