> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Pioneer as a desktop app, local gateway, or remote gateway.

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.

<Note>
  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.
</Note>

<Note>
  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.
</Note>

## 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.

<Tabs>
  <Tab title="macOS">
    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.
  </Tab>

  <Tab title="Windows">
    Download the Pioneer `.msi` or `.exe`, run the installer, and open Pioneer from the Start menu. If the local gateway is not running yet, the app will offer to start it.
  </Tab>

  <Tab title="Linux">
    Download the Pioneer `.AppImage`, make it executable, and run it:

    ```bash theme={null}
    chmod +x Pioneer*.AppImage
    ./Pioneer*.AppImage
    ```

    Start the local gateway from inside the app when prompted.
  </Tab>
</Tabs>

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.

<Note>
  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.
</Note>

## 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:

```bash theme={null}
curl -fsSL https://getpioneer.dev/install.sh | bash
```

To install the native computer-use gateway variant without installing the desktop app:

```bash theme={null}
curl -fsSL https://getpioneer.dev/install.sh | bash -s -- --computer-use
```

On Windows PowerShell:

```powershell theme={null}
iwr -useb https://getpioneer.dev/install.ps1 | iex
```

To install the native computer-use gateway variant from PowerShell:

```powershell theme={null}
$env:PIONEER_INSTALL_COMPUTER_USE="1"; iwr -useb https://getpioneer.dev/install.ps1 | iex
```

On Windows CMD:

```cmd theme={null}
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

| Platform | Service mode                | Persistence behavior                                                                  |
| -------- | --------------------------- | ------------------------------------------------------------------------------------- |
| Linux    | `systemd --user` service    | Requires systemd linger so the gateway survives logout and starts after reboot        |
| macOS    | per-user LaunchAgent        | Starts after the user logs in; not available as a boot-time LaunchDaemon before login |
| Windows  | current-user Scheduled Task | Starts 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:

```bash theme={null}
sudo loginctl enable-linger "$USER"
```

You can choose a channel or exact version when release assets exist for your platform:

```bash theme={null}
--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:

```bash theme={null}
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:

```bash theme={null}
pioneer secrets status
```

If your shell cannot find `pioneer`, open a new terminal. On Unix systems, make sure `~/.local/bin` is in your `PATH`:

```bash theme={null}
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:

```bash theme={null}
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`.

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:

```toml theme={null}
[gateway]
listen_addr = "0.0.0.0:17878"
```

For local-only use, bind it to localhost:

```toml theme={null}
[gateway]
listen_addr = "127.0.0.1:17878"
```

Config files live here:

| Platform | Config 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:

```bash theme={null}
pioneer stop
pioneer start
```

<Warning>
  Do not expose a gateway broadly on the public internet. Use firewall rules, trusted networks, and tokens carefully.
</Warning>

## Update or stop

Update the gateway with:

```bash theme={null}
pioneer update
```

You can also update from a specific release channel:

```bash theme={null}
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:

```bash theme={null}
pioneer stop
```

<Note>
  The current CLI exposes `stop`, not a separate uninstall command. Back up runtime data before manually deleting Pioneer directories.
</Note>

## Next

Once the gateway is running, go to [Quick Start](/getting-started/quickstart) and configure your first model provider.

## Further reading

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