Skip to main content
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
  • editable identity files (SOUL.md, IDENTITY.md)
  • skills
  • computer-use artifacts
On startup, the gateway creates missing SOUL.md and IDENTITY.md files in runtime home. Existing files are left unchanged. These files are read into the Soul Core and Identity Core prompt sections.

​
Provider credentials

Provider keys are stored in the gateway keystore and scoped to a workspace. This means:
  • each workspace has its own provider credentials
  • remote gateways need their own provider setup
  • switching workspace or gateway 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_INSTALL_COMPUTER_USESet to 1, true, or yes to make bootstrap scripts install the computer-use gateway variant
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.