Skip to main content

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.

Most users can start with the desktop app and provider settings. Use config files when you need to change gateway behavior, bind addresses, tool limits, database settings, or development paths.

​
How configuration is loaded

Pioneer loads configuration in layers:
1

Built-in defaults

Defaults are compiled from the source tree’s config/default.toml.
2

Development local config

Debug builds also load config/local.toml.
3

User config file

Release builds load the platform user config file.
4

Explicit config override

PIONEER_CONFIG can point to a config file.
Later layers override earlier layers.

​
User config location

PlatformPath
macOS~/Library/Application Support/pioneer/config.toml
Linux~/.config/pioneer/config.toml
Windows%APPDATA%\pioneer\config.toml
Development builds use pioneer-dev config paths.

​
Bind address

The most common config change is the gateway bind address. Default production gateway: 
[gateway]
listen_addr = "0.0.0.0:17878"
Local-only gateway: 
[gateway]
listen_addr = "127.0.0.1:17878"
Binding to 0.0.0.0 makes the gateway reachable from other machines if the firewall allows it. Only do this intentionally.

​
Runtime home

The gateway stores runtime data under a home directory. Default release runtime home: 
home_directory = ".pioneer"
Development runtime home: 
home_directory = ".pioneer.dev"
The runtime home contains state such as:
  • gateway database
  • keystore database
  • install state
  • gateway settings
  • skills
  • computer-use artifacts

​
Provider credentials

Provider keys are stored in the gateway keystore. This means:
  • each gateway has its own provider credentials
  • remote gateways need their own provider setup
  • switching gateways also switches provider settings
Operational details for keystore.db are covered in Secret Storage.

​
Database settings

Gateway database settings live under [gateway.database]. Common defaults: 
[gateway.database]
file_name = "gateway.db"
max_connections = 1
run_migrations_on_startup = true
Most users should leave these alone.

​
Tool safety settings

Tool limits live under [gateway.tools]. Examples include:
  • web fetch timeout
  • maximum download size
  • computer-use artifact retention
  • maximum tool calls per turn
  • retry limits
Tool limits reduce risk, but they are not a sandbox. Tool processes still run as the gateway OS user.

​
Skills settings

Skills settings live under [gateway.skills]. They control:
  • whether skills are enabled
  • skill search paths
  • validation behavior
  • trust thresholds
  • dependency checks
  • dynamic tool registration

​
Environment variables

Useful environment variables:
VariablePurpose
PIONEER_CONFIGLoad an explicit config file
PIONEER_RELEASE_REPOOverride release repo used by installer
PIONEER_RELEASE_API_BASEOverride release API base URL
PIONEER_RELEASE_DOWNLOAD_BASEOverride release download base URL
PIONEER_LOCAL_ASSET_FILEUse a local gateway asset in bootstrap scripts
PIONEER_LOCAL_CHECKSUMS_FILEUse a local checksum file in bootstrap scripts

​
Apply changes

After changing gateway config: 
pioneer stop
pioneer start
pioneer status
For desktop-managed local gateways, restart the gateway from the desktop app if available.

Configuration Reference

View important config keys and examples.