Skip to main content
Pioneer can run as a desktop app with a local gateway, or as a gateway service that a client connects to. For personal use on one computer, install the desktop app. It can start a local gateway for you, so the first setup does not require service, port, or token configuration. For a shared machine, a server, or a machine that should keep working while your laptop is closed, install the gateway directly and connect to it from the desktop app.
Before important work, confirm which gateway you are connected to, which provider keys are configured there, and which permission mode is selected for the turn. Pioneer enforces turn permissions and sandbox/resource policy on the gateway that owns the work.
Tool approval prompts are controlled per turn by permission modes. Supervised asks before sensitive tool actions; Auto-accept edits allows file edits but still asks for commands, network, MCP writes, skill tools, computer use, and subagents.

​
Local desktop install

Choose this when you want to work from the same computer as the desktop app: download the app, open it, and start the local gateway.
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.
For local use, the desktop app handles the first setup. It runs the UI, starts the local gateway, and then guides you through adding a model provider.

​
Desktop updates

The desktop app has a native update flow. It checks the configured Pioneer release channel for an asset matching the current operating system and architecture, downloads it into the app’s runtime home, verifies its checksum, and stages an update through the platform updater helper. The app does not replace itself with an asset for a different platform or with a version that is not newer than the installed one. The default channel is stable. Operators and test environments can disable checks or select another channel with PIONEER_DESKTOP_UPDATE_DISABLED, PIONEER_DESKTOP_UPDATE_FORCE_CHECK, and PIONEER_DESKTOP_UPDATE_CHANNEL. These controls affect the desktop app updater; pioneer update remains the gateway/CLI update command described below.
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 Pioneer should run on another machine, such as a workstation, server, home computer, or lab machine. The gateway then has access to that machine’s files and tools. On macOS or Linux:
To install the native computer-use gateway variant without installing the desktop app:
On Windows PowerShell:
To install the native computer-use gateway variant from PowerShell:
On Windows CMD:
The installer downloads the gateway release, verifies checksums, installs the pioneer CLI, and registers a current-user gateway service.

​
Service lifecycle by OS

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:
You can choose a channel or exact version when release assets exist for your platform:
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:
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:
If your shell cannot find pioneer, open a new terminal. On Unix systems, make sure ~/.local/bin is in your 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:
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. The desktop app is a client. If it connects to a gateway on a server, tools run on that server. Turn permission modes and sandbox/resource policy determine which actions Pioneer allows, asks about, audits, or blocks there. 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:
For local-only use, bind it to localhost:
Config files live here: Restart the gateway after changing the address:
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:
You can also update from a specific release channel:
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:
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.

​
Further reading

  • Permission Modes explains how to choose Supervised, Auto-accept edits, or Full access.
  • Gateway Architecture explains what the gateway service owns at runtime.
  • Client Architecture explains why desktop and mobile apps are clients of a gateway.
  • Permission System explains turn permission modes, sandbox/resource policy, approval requests, and audit events.
  • Secret Storage explains where gateway tokens, provider keys, MCP secrets, and remote-access keys live.
  • Configuration Overview explains when to use app config files instead of in-app settings.