Configuration Reference

This is a user-focused reference for settings you are likely to change. It is not an exhaustive internal schema.

Top-level settings

Key	Default	Purpose
`home_directory`	`.pioneer`	Runtime home under the OS user home directory. The gateway stores state and editable prompt identity files here.
`install_state_file_name`	`install-state.toml`	Install state file stored in runtime home

By default, runtime home is ~/.pioneer. On startup, the gateway creates missing SOUL.md and IDENTITY.md files at the root of runtime home. These files seed the Soul Core and Identity Core prompt sections and may be edited over time.

Install settings

Key	Default	Purpose
`install.command_name`	`pioneer`	User-facing CLI command
`install.binary_name`	`pioneer`	Installed gateway/CLI binary name
`install.managed_directory_name`	`managed`	Managed install directory name

Most users should not change install settings.

Gateway settings

Key	Default	Purpose
`gateway.service_name`	`com.pioneer.gateway`	OS service name
`gateway.listen_addr`	`0.0.0.0:17878`	Gateway bind address
`gateway.outbound_queue_capacity`	`128`	Outbound event queue capacity
`gateway.preflight_model`	`thread`	Provider/model used for the internal turn preflight planner. `thread` means the current thread model.

Local-only example:

[gateway]
listen_addr = "127.0.0.1:17878"
preflight_model = "thread"

The desktop app exposes this as Settings > General > Preflight model. Use gateway.preflight_model for new configuration. Legacy memory active-recall model settings are migrated to this general preflight model setting when no explicit preflight model is present.

Task review settings

Key	Default	Purpose
`gateway.tasks.review.enabled`	`true`	Enable task result review runtime.
`gateway.tasks.review.allow_task_create_review_policy`	`false`	Allow callers to override review policy directly in `task/create`.
`gateway.tasks.review.default_parent_review_for_immediate_attached_agent_tasks`	`true`	Require parent-agent review for immediate attached agent tasks.
`gateway.tasks.review.default_max_revision_rounds`	`5`	Default number of revision turns a parent can request.
`gateway.tasks.review.auto_accept_after_seconds`	`300`	Auto-accept candidates that stay in review too long. Set to `0` to disable timeout auto-accept.

Example:

[gateway.tasks.review]
enabled = true
allow_task_create_review_policy = false
default_parent_review_for_immediate_attached_agent_tasks = true
default_max_revision_rounds = 5
auto_accept_after_seconds = 300

Immediate attached subagent tasks use parent-agent review by default. Scheduled or detached work should not depend on a live parent turn and may be finalized automatically according to task policy.

Agent memory settings

Key	Default	Purpose
`gateway.memory.enabled`	`true`	Enable durable agent memory runtime.
`gateway.memory.capsules_dir`	`memory/capsules`	Memvid capsule directory under runtime home.
`gateway.memory.allow_global_user_by_default`	`true`	Include global user memories in ordinary turn scopes.
`gateway.memory.allow_global_agent_by_default`	`false`	Include global agent memories by default.
`gateway.memory.deterministic_recall_enabled`	`true`	Enable bounded deterministic pre-turn recall.
`gateway.memory.active_recall_enabled`	`true`	Enable extra read-only active recall planning for context-heavy turns.
`gateway.memory.tools_enabled`	`true`	Register memory tools for capable agent-mode providers when policy allows; actual visibility is selected by preflight or `request_tools`.
`gateway.memory.proactive_writes_enabled`	`true`	Allow post-turn extraction to write high-confidence durable facts through the quality gate.
`gateway.memory.background_extraction_enabled`	`true`	Run post-turn extraction through background hook execution instead of blocking the user turn.
`gateway.memory.debug_trace_enabled`	`false`	Enable memory debug traces in local diagnostic surfaces.
`gateway.memory.strict_diagnostics_enabled`	`false`	Enable stricter developer diagnostics without bypassing memory policy or quality gates.

Example:

[gateway.memory]
enabled = true
capsules_dir = "memory/capsules"
allow_global_user_by_default = true
allow_global_agent_by_default = false
deterministic_recall_enabled = true
active_recall_enabled = true
tools_enabled = true
proactive_writes_enabled = true
background_extraction_enabled = true
debug_trace_enabled = false
strict_diagnostics_enabled = false

capsules_dir is resolved under runtime home. Pioneer rejects empty paths, absolute paths, .., and other unsafe runtime-home escapes. The desktop app also stores user-facing memory preferences in desktop-settings.toml under runtime home. Desktop settings map onto the same gateway.memory product switches when the desktop runtime loads config. They do not expose candidate review or transcript recall controls.

Thread defaults

Key	Default	Purpose
`gateway.thread.default_model`	`google/gemini-3-flash-preview`	Default model ID
`gateway.thread.default_model_provider`	`openrouter`	Default provider name
`gateway.thread.max_context_tokens`	`128000`	Context budget
`gateway.thread.response_reserve_tokens`	`16000`	Reserved response budget

You can override these if you want new threads to start with a different default model.

Web tool settings

Key	Default	Purpose
`gateway.tools.web.default_timeout_ms`	`20000`	Default web operation timeout
`gateway.tools.web.default_fetch_max_bytes`	`2097152`	Default fetched content limit
`gateway.tools.web.default_download_max_bytes`	`134217728`	Default download size limit
`gateway.tools.web.default_max_results`	`8`	Default web search result count

Tool loop limits

Key	Default	Purpose
`gateway.tools.budget.max_agent_rounds_per_turn`	`512`	Maximum model/tool rounds per turn
`gateway.tools.budget.max_tool_calls_per_turn`	`2048`	Maximum tool calls per turn
`gateway.tools.retry.max_same_tool_error_retries_per_episode`	`3`	Retry limit for repeated tool errors

These limits help stop runaway loops, but they are not a security sandbox.

Computer-use settings

Key	Default	Purpose
`gateway.tools.computer_use.artifacts_subdir`	`tools/computer_use`	Where computer-use artifacts are stored under runtime home
`gateway.tools.computer_use.retention_hours`	`24`	Artifact retention
`gateway.tools.computer_use.run_max_steps_default`	`300`	Default maximum steps per computer-use run

Skills settings

Key	Default	Purpose
`gateway.skills.enabled`	`true`	Enable skills
`gateway.skills.allow_implicit_invocation`	`false`	Allow implicit skill invocation
`gateway.skills.validation.strict_agentskills`	`true`	Enforce AgentSkills validation
`gateway.skills.dependencies.preflight_on_resolve`	`true`	Check dependencies before resolving skills
`gateway.skills.runtime.enable_dynamic_tools`	`true`	Let skills register dynamic tools

Provider attachment settings

Key	Default	Purpose
`gateway.provider.attachments.max_bytes_per_attachment`	`104857600`	Max single attachment size
`gateway.provider.attachments.max_total_bytes_per_request`	`209715200`	Max total attachment size per request
`gateway.provider.attachments.max_attachments_per_request`	`64`	Max attachments per request
`gateway.provider.attachments.allow_url_sources`	`true`	Allow URL attachment sources
`gateway.provider.attachments.allow_http`	`false`	Allow plain HTTP URL sources
`gateway.provider.attachments.allow_private_network`	`false`	Allow private-network URL sources

Database settings

Key	Default	Purpose
`gateway.database.file_name`	`gateway.db`	Database filename under runtime home
`gateway.database.max_connections`	`1`	SQLite connection count
`gateway.database.run_migrations_on_startup`	`true`	Apply migrations during gateway startup

Gateway runtime settings file

Runtime secret values are not configured as ordinary app config keys. The gateway creates gateway-settings.toml under runtime home with:

[secrets]
backend = "keystore"

Only keystore is supported. The old db-keystore backend name is not accepted. This setting selects the secret backend; the storage model itself is described in Secret Storage.

Auth settings

Key	Default	Purpose
`gateway.auth.jwt_issuer`	`pioneer`	JWT issuer
`gateway.auth.jwt_audience`	`pioneer-clients`	JWT audience
`gateway.auth.superuser_subject`	`superuser`	Subject for superuser tokens
`gateway.auth.token_ttl_seconds`	`31536000`	Token lifetime

Desktop gateway settings

Key	Default	Purpose
`desktop.gateway.connect_timeout_ms`	`300`	Connection timeout
`desktop.gateway.startup_timeout_ms`	`10000`	Local gateway startup timeout
`desktop.gateway.ws_ping_interval_ms`	`10000`	WebSocket ping interval
`desktop.gateway.registry_file_name`	`gateway-registry.toml`	Desktop gateway registry file

​Top-level settings

​Install settings

​Gateway settings

​Task review settings

​Agent memory settings

​Thread defaults

​Web tool settings

​Tool loop limits

​Computer-use settings

​Skills settings

​Provider attachment settings

​Database settings

​Gateway runtime settings file

​Auth settings

​Desktop gateway settings