Skip to main content
Most users can start with the desktop or mobile app and provider settings. Use config files for gateway behavior, bind addresses, tool limits, database settings, CLI runtime defaults, remote-access relay 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

Development builds use pioneer-dev config paths.

​
Bind address

The most common config change is the gateway bind address. Default production gateway:
Local-only gateway:
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:
Development runtime home:
The runtime home contains state such as:
  • gateway database
  • keystore database
  • install state
  • gateway settings
  • editable identity files (SOUL.md, IDENTITY.md)
  • memory capsules and thread-context indexes
  • skills
  • computer-use artifacts
  • remote-access runtime files
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. As a result:
  • 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:
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 and permission modes reduce risk in different ways. Limits stop runaway loops; permission modes and sandbox/resource policy decide which actions can run, which require approval, and which are rejected.

​
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

​
CLI runtime settings

CLI runtime defaults live under [gateway.cli_agent_runtime], and named runtime instances can be configured under [gateway.cli_agent_runtimes.<id>]. The runtime settings API also exposes settings.cli_runtimes.instances. Client-facing changes should go through settings/update; app config is best for operator defaults and deployment-specific paths.

​
Remote access settings

Remote-access operator defaults live under [gateway.remote_access]. They define the relay address, local gateway address, service name, runtime directory, and restart policy. The runtime enable flag and remote-access key are managed through settings/update. The key is stored in the gateway keystore, not in gateway-settings.toml.

​
Environment variables

Useful environment variables:

​
Apply changes

There are two kinds of settings. App config files provide startup defaults and operator-managed configuration. After changing app config:
For desktop-managed local gateways, restart the gateway from the desktop app if available. Runtime settings such as memory switches, thread-context switches, CLI runtime instances, keep-awake, and remote-access controls are gateway-owned but can be changed through settings/update. Clients should use the settings API instead of editing gateway-settings.toml directly. Those settings are meant to refresh the relevant runtime systems without making the user restart just to toggle behavior.

Configuration Reference

View important config keys and examples.

​
Further reading

  • Gateway Architecture explains which systems read gateway settings at runtime.
  • Persistence explains gateway.db, runtime home, and migration behavior.
  • Secret Storage explains why secret values are stored outside ordinary config.
  • Protocol Layer explains how clients use settings/get and settings/update.