Configuration Reference

This is an operator reference for the default gateway configuration. If you only use the desktop app, start with Configuration Overview and change these values only when you need a gateway-level setting.

Most users do not need to read this page end to end. Use it when support, automation, or a deployment guide asks for a specific setting name.

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
`install.unix_root_directory_name`	`pioneer`	Default Unix install root directory name
`install.macos_root_directory_name`	`Pioneer`	Default macOS install root directory name
`install.windows_root_directory_name`	`Pioneer`	Default Windows install root directory name
`install.macos_background_item_name`	`Pioneer`	macOS background item display name
`install.macos_associated_bundle_identifier`	`ai.pioneer.macos`	Bundle id associated with the macOS background item

Most users should not change install settings.

Gateway settings

Key	Default	Purpose
`gateway.settings_version`	`1`	Gateway runtime settings schema version
`gateway.settings_file_name`	`gateway-settings.toml`	Runtime settings filename under gateway home
`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.trusted_proxy_peers`	`[]`	Immediate proxy IPs whose single replacement `Forwarded` or `X-Forwarded-For` client address may be trusted. Keep empty for direct and LAN use.
`gateway.keepawake`	`false`	Keep the gateway process awake when supported by the host platform
`gateway.telemetry.enabled`	`true`	Enable the gateway’s consent-gated OTLP metrics and traces export.
`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.

Telemetry settings

Gateway telemetry uses OTLP/HTTP endpoints for metrics and traces. The app-config switch enables the exporter, while the user-facing general.telemetry_enabled setting from Settings API records the current consent choice and can turn export off at runtime.

Key	Default	Purpose
`gateway.telemetry.enabled`	`true`	Enable the telemetry exporter in the gateway process.
`gateway.telemetry.otlp_metrics_endpoint`	`https://telemetry.getpioneer.dev/v1/metrics`	OTLP/HTTP endpoint for metrics.
`gateway.telemetry.otlp_traces_endpoint`	`https://telemetry.getpioneer.dev/v1/traces`	OTLP/HTTP endpoint for traces.
`gateway.telemetry.export_interval_ms`	`30000`	Interval between export attempts.
`gateway.telemetry.export_timeout_ms`	`3000`	Maximum time allowed for one export attempt.

Telemetry credentials stay on the gateway side. A client receives status and diagnostics through the normal observability surfaces, not through exported credentials.

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.

Self-improvement settings

Self-improvement is configured per workspace through the Settings API, not through a [gateway.self_improvement] TOML section. The settings object contains enabled, an optional default_model, and an optional reviewer_model. Each model selection names a native API provider and model. CLI runtime ids and local providers are not eligible for this service. When enabled and eligible, the service can turn completed work into learned skills. Learned skills remain workspace-scoped and go through the normal skill policy, visibility, provenance, dependency, and prompt-capacity checks.

Hook recovery settings

Hook recovery repairs persisted hook/task/turn state after gateway restart or stale runtime activity.

Key	Default	Purpose
`gateway.hooks.recovery.enabled`	`true`	Enable startup and runtime recovery for hook execution state.
`gateway.hooks.recovery.startup_scan`	`true`	Scan for stale hook work during gateway startup.
`gateway.hooks.recovery.poll_interval_ms`	`2000`	Runtime recovery polling interval.
`gateway.hooks.recovery.batch_size`	`64`	Maximum recovery rows handled in one batch.
`gateway.hooks.recovery.max_concurrent`	`4`	Maximum concurrent recovery jobs.
`gateway.hooks.recovery.stale_running_after_ms`	`120000`	Mark running work stale after this duration.
`gateway.hooks.recovery.strict_debug`	`false`	Enable stricter debug behavior for recovery development.

Artifact storage settings

Artifacts are gateway-owned durable files and generated outputs.

Key	Default	Purpose
`gateway.artifacts.max_file_bytes`	`536870912`	Maximum size for one artifact file.
`gateway.artifacts.max_workspace_bytes`	`10737418240`	Maximum artifact storage per workspace.
`gateway.artifacts.max_files_per_workspace`	`100000`	Maximum artifact count per workspace.
`gateway.artifacts.upload_session_ttl_secs`	`3600`	Time-to-live for incomplete upload sessions.
`gateway.artifacts.gc_grace_secs`	`86400`	Grace period before artifact garbage collection can remove eligible files.
`gateway.artifacts.output_dir_ttl_secs`	`86400`	Time-to-live for temporary artifact output directories.
`gateway.artifacts.readable_copy_ttl_secs`	`86400`	Time-to-live for readable artifact copies.
`gateway.artifacts.quota_warn_at_percent`	`80`	Workspace quota warning threshold.
`gateway.artifacts.http_streams_global`	`32`	Maximum concurrent artifact and avatar HTTP streams across the gateway.
`gateway.artifacts.http_streams_per_principal`	`8`	Maximum concurrent authenticated HTTP streams for one principal.
`gateway.artifacts.http_streams_per_session`	`4`	Maximum concurrent authenticated HTTP streams for one session.
`gateway.artifacts.http_open_handles`	`32`	Maximum concurrent storage opens used by HTTP delivery.
`gateway.artifacts.http_max_single_range_bytes`	`134217728`	Maximum size of one accepted HTTP byte range. Multipart ranges are not supported.
`gateway.artifacts.http_tiny_range_bytes`	`4096`	Largest range counted by the tiny-range abuse limiter.
`gateway.artifacts.http_tiny_range_window_secs`	`10`	Sliding window for tiny-range request limiting.
`gateway.artifacts.http_tiny_range_max_requests`	`32`	Maximum tiny-range requests in one window for one authenticated session.
`gateway.artifacts.http_open_timeout_secs`	`15`	Maximum time allowed to authorize and open one HTTP representation.
`gateway.artifacts.http_body_idle_timeout_secs`	`30`	Maximum idle interval while streaming an HTTP response body.
`gateway.artifacts.view_grant_ttl_secs`	`180`	Lifetime of a short-lived browser/system-viewer grant.
`gateway.artifacts.view_grants_global`	`4096`	Maximum active view grants across the gateway.
`gateway.artifacts.view_grants_per_session`	`16`	Maximum active view grants owned by one live session.
`gateway.artifacts.view_grant_streams`	`4`	Maximum concurrent streams that consume view grants.

Resilience settings

Command execution resilience settings control how long command execution leases can stay active and how long recovery can keep trying to reconcile command execution state. Provider stream item resilience settings do the same for streamed provider items that may need reconciliation after interruption or restart. Context compaction has its own lease and recovery window because compaction can remain active while the gateway rebuilds a thread context.

Key	Default	Purpose
`gateway.resilience.command_execution.lease_secs`	`600`	Lease duration for command execution ownership.
`gateway.resilience.command_execution.idle_secs`	`1800`	Idle duration after which command execution can be treated as stale.
`gateway.resilience.command_execution.hard_secs`	`3600`	Hard maximum duration for command execution before recovery treats it as overdue.
`gateway.resilience.command_execution.recovery_max_wall_clock_secs`	`3600`	Maximum wall-clock time allowed for command execution recovery.
`gateway.resilience.provider_stream_items.lease_secs`	`960`	Lease duration for provider stream item ownership.
`gateway.resilience.provider_stream_items.idle_secs`	`900`	Idle duration after which a provider stream item can be treated as stale.
`gateway.resilience.provider_stream_items.hard_secs`	`1800`	Hard maximum duration for provider stream item reconciliation before recovery treats it as overdue.
`gateway.resilience.context_compaction.lease_secs`	`600`	Lease duration for context-compaction ownership.
`gateway.resilience.context_compaction.idle_secs`	`1800`	Idle duration after which context compaction can be treated as stale.
`gateway.resilience.context_compaction.hard_secs`	`14400`	Hard maximum duration for context compaction before recovery treats it as overdue.
`gateway.resilience.context_compaction.recovery_grace_secs`	`900`	Additional grace period for reconciling compaction after recovery.

Provider transport timeouts are configured separately under [gateway.provider]: non_stream_request_timeout_secs, connect_timeout_secs, first_chunk_timeout_secs, inter_chunk_idle_timeout_secs, and the optional max_stream_duration_secs. These control the provider request itself; the resilience leases above control ownership and recovery of persisted streamed items after interruption.

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.active_recall_model`	`thread`	Provider/model selector for active recall planning when configured at app-config level. `thread` means the current thread model.
`gateway.memory.proactive_writes_model`	`thread`	Provider/model selector for post-turn extraction. `thread` means the current thread model.
`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
active_recall_model = "thread"
proactive_writes_model = "thread"
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 does not own these settings. It reads and updates gateway-owned runtime settings through the settings API. That is what lets the same desktop app connect to a different gateway and show that gateway’s actual memory configuration.

Thread episodic context settings

Thread episodic context is the searchable conversation-history layer. It is separate from durable memory. Durable memory stores selected facts and project decisions. Thread episodic context indexes visible conversation snippets so Pioneer can recall old discussion fragments when a future turn needs them.

Key	Default	Purpose
`gateway.thread_episodic.enabled`	`true`	Enable the thread context layer. When off, indexing and recall should not contribute to turns.
`gateway.thread_episodic.indexing_enabled`	`true`	Allow new visible conversation items to be indexed.
`gateway.thread_episodic.recall_enabled`	`true`	Allow indexed thread context to be recalled into future prompts.
`gateway.thread_episodic.default_prompt_chars`	`2400`	Default prompt budget for recalled thread snippets.
`gateway.thread_episodic.max_prompt_chars`	`12000`	Hard upper prompt budget for recalled snippets.
`gateway.thread_episodic.max_hit_chars`	`1200`	Maximum characters taken from a single recalled hit.
`gateway.thread_episodic.default_max_candidates`	`32`	Default number of candidate search hits considered before final filtering.
`gateway.thread_episodic.max_candidate_work`	`128`	Upper work bound for candidate processing.
`gateway.thread_episodic.max_segments`	`16`	Maximum memvid capsule segments per workspace/thread context surface.
`gateway.thread_episodic.min_relevancy`	`0.25`	Minimum relevance threshold for recalled candidates.
`gateway.thread_episodic.min_results`	`1`	Minimum desired results when recall is allowed.
`gateway.thread_episodic.snippet_chars`	`360`	Default compact snippet size for prompt display.
`gateway.thread_episodic.index_batch_limit`	`16`	Number of pending index jobs handled in one batch.
`gateway.thread_episodic.retry_base_delay_secs`	`30`	First retry delay for failed index jobs.
`gateway.thread_episodic.retry_max_delay_secs`	`900`	Maximum retry delay for index jobs.
`gateway.thread_episodic.max_attempts`	`5`	Maximum attempts before an index job is considered failed.
`gateway.thread_episodic.near_capacity_percent`	`85.0`	Diagnostic threshold for near-capacity memvid capsules.

Vector search

Vector search is an opt-in projection for thread episodic context. It keeps embedding configuration in app config and reports provider-key, refill, and local-model readiness through the Settings API.

Key	Default	Purpose
`gateway.thread_episodic.vector_search.enabled`	`false`	Enable semantic/vector search for the thread episodic projection.
`gateway.thread_episodic.vector_search.provider`	unset	Embedding provider: `openai`, `openrouter`, or `local`.
`gateway.thread_episodic.vector_search.model`	unset	Selected embedding model id.
`gateway.thread_episodic.vector_search.local_model`	unset	Local embedding model selection retained for the local provider.
`gateway.thread_episodic.vector_search.embedding_normalized`	`true`	Normalize embeddings before storage and search.
`gateway.thread_episodic.vector_search.use_search_instructions`	`false`	Add a retrieval instruction to query embeddings without changing stored document embeddings.

Example:

[gateway.thread_episodic]
enabled = true
indexing_enabled = true
recall_enabled = true
default_prompt_chars = 2400
max_prompt_chars = 12000
max_hit_chars = 1200
default_max_candidates = 32
max_candidate_work = 128
max_segments = 16
min_relevancy = 0.25
min_results = 1
snippet_chars = 360
index_batch_limit = 16
retry_base_delay_secs = 30
retry_max_delay_secs = 900
max_attempts = 5
near_capacity_percent = 85.0

[gateway.thread_episodic.vector_search]
enabled = false
embedding_normalized = true

Use the public settings API for user-facing runtime changes. App config is for defaults and operator-managed configuration; gateway-settings.toml is the runtime override file owned by the gateway.

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.summary_model`	unset	Optional model ID for thread-summary generation. When unset, use the thread’s model.
`gateway.thread.summary_model_provider`	unset	Optional provider for thread-summary generation. When unset, use the thread’s provider.
`gateway.thread.title_model`	unset	Optional model ID for thread-title generation. When unset, use the thread’s model.
`gateway.thread.title_model_provider`	unset	Optional provider for thread-title generation. When unset, use the thread’s provider.
`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.hard_max_timeout_ms`	`120000`	Hard maximum web operation timeout
`gateway.tools.web.default_fetch_max_bytes`	`2097152`	Default fetched content limit
`gateway.tools.web.hard_fetch_max_bytes`	`8388608`	Hard fetched content limit
`gateway.tools.web.default_download_max_bytes`	`134217728`	Default download size limit
`gateway.tools.web.hard_download_max_bytes`	`1073741824`	Hard download size limit
`gateway.tools.web.default_max_results`	`8`	Default web search result count
`gateway.tools.web.hard_max_results`	`20`	Hard web search result count
`gateway.tools.web.default_snippet_chars`	`420`	Default snippet size for search results
`gateway.tools.web.hard_max_snippet_chars`	`4096`	Hard snippet size limit
`gateway.tools.web.default_link_count`	`40`	Default number of links retained from rendered pages
`gateway.tools.web.hard_link_count`	`200`	Hard link count limit
`gateway.tools.web.default_render_max_chars`	`40000`	Default rendered text limit
`gateway.tools.web.ddg_html_search_url`	`https://duckduckgo.com/html/`	DuckDuckGo HTML search endpoint
`gateway.tools.web.ddg_instant_api_url`	`https://api.duckduckgo.com/`	DuckDuckGo instant-answer endpoint
`gateway.tools.web.default_user_agent`	`Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36`	Default user agent for web requests

Tool loop limits

Key	Default	Purpose
`gateway.tools.budget.max_agent_rounds_per_turn`	`32`	Maximum model/tool rounds per turn
`gateway.tools.budget.max_tool_calls_per_turn`	`128`	Maximum tool calls per turn
`gateway.tools.retry.max_recoverable_retry_rounds_per_episode`	`32`	Maximum retry rounds for one recoverable episode
`gateway.tools.retry.max_same_tool_error_retries_per_episode`	`3`	Retry limit for repeated tool errors
`gateway.tools.retry.max_retries_per_tool_name_per_episode`	`16`	Retry limit per tool name in one episode

These limits help stop runaway loops. Permission modes and sandbox/resource policy control whether sensitive tool actions are allowed immediately, require approval, receive scoped grants, or are rejected.

Execution window limits

Execution windows bound long agent turns in smaller windows and also keep total-turn limits.

Key	Default	Purpose
`gateway.tools.execution_windows.max_agent_rounds_per_window`	`32`	Maximum model/tool rounds in one execution window
`gateway.tools.execution_windows.max_tool_calls_per_window`	`128`	Maximum tool calls in one execution window
`gateway.tools.execution_windows.max_wall_clock_ms_per_window`	`1800000`	Wall-clock limit for one execution window
`gateway.tools.execution_windows.max_provider_tokens_per_window`	unset	Optional provider-token limit for one execution window
`gateway.tools.execution_windows.total.max_windows_per_turn`	unset	Optional maximum execution windows for one turn
`gateway.tools.execution_windows.total.max_tool_calls_per_turn`	unset	Optional total tool-call ceiling across all windows in one turn
`gateway.tools.execution_windows.total.max_wall_clock_ms_per_turn`	unset	Optional total wall-clock ceiling for one turn
`gateway.tools.execution_windows.total.max_provider_tokens_per_turn`	unset	Optional provider-token ceiling for one turn
`gateway.tools.execution_windows.total.max_consecutive_no_progress_windows`	`3`	Stop after this many consecutive windows without progress

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.max_total_bytes`	`1073741824`	Maximum total computer-use artifact bytes retained.
`gateway.tools.computer_use.run_max_steps_default`	`300`	Default maximum steps per computer-use run
`gateway.tools.computer_use.snapshot_transport_max_bytes`	`8388608`	Maximum snapshot payload size transported to the model.
`gateway.tools.computer_use.snapshot_transport_max_side_px`	`1280`	Maximum snapshot side length after transport scaling.
`gateway.tools.computer_use.snapshot_transport_min_side_px`	`320`	Minimum useful snapshot side length.
`gateway.tools.computer_use.snapshot_downscale_factor`	`0.85`	Downscale factor used during snapshot reduction.
`gateway.tools.computer_use.accessibility_tree_max_depth`	`6`	Maximum accessibility tree depth.
`gateway.tools.computer_use.accessibility_tree_max_nodes`	`200`	Maximum accessibility nodes serialized.
`gateway.tools.computer_use.accessibility_tree_max_serialized_bytes`	`196608`	Maximum serialized accessibility tree size.
`gateway.tools.computer_use.accessibility_tree_text_max_chars`	`160`	Maximum text kept per accessibility node.
`gateway.tools.computer_use.semantic_action_timeout_ms`	`30000`	Timeout for semantic computer-use actions.
`gateway.tools.computer_use.app_activation_timeout_ms`	`5000`	Timeout for activating a target app.
`gateway.tools.computer_use.input_simulation_enabled`	`true`	Allow mouse/keyboard input simulation.
`gateway.tools.computer_use.launch_if_missing_default`	`false`	Default for launching missing apps when requested.
`gateway.tools.computer_use.allowed_launch_commands`	`[]`	Optional allowlist for explicit launch commands.
`gateway.tools.computer_use.preflight_screenshot_probe_enabled`	`true`	Capture a preflight screenshot probe before runs.
`gateway.tools.computer_use.max_consecutive_same_snapshot_hash`	`6`	Stop after repeated identical snapshots.
`gateway.tools.computer_use.max_consecutive_same_action_signature`	`8`	Stop after repeated identical action signatures.
`gateway.tools.computer_use.max_consecutive_no_progress_steps`	`4`	Stop after repeated no-progress steps.
`gateway.tools.computer_use.max_recovery_attempts_per_step`	`2`	Recovery attempts allowed for one step.
`gateway.tools.computer_use.max_recovery_attempts_per_run`	`12`	Recovery attempts allowed for one run.

Skills settings

Key	Default	Purpose
`gateway.skills.enabled`	`true`	Enable skills
`gateway.skills.max_skills_per_source`	`256`	Maximum skills loaded from one source
`gateway.skills.max_skill_file_bytes`	`1048576`	Maximum size for a skill file
`gateway.skills.prompt_max_chars`	`24000`	Maximum skill prompt text included in prompts
`gateway.skills.allow_implicit_invocation`	`false`	Allow implicit skill invocation
`gateway.skills.paths.system`	`[]`	System skill source directories
`gateway.skills.paths.user`	`["{homeDirectory}/skills/workspace/{workspaceId}/user"]`	User-installed skill directories
`gateway.skills.paths.registry`	`["{homeDirectory}/skills/workspace/{workspaceId}/registry"]`	Registry-installed skill directories
`gateway.skills.validation.strict_agentskills`	`true`	Enforce AgentSkills validation
`gateway.skills.validation.accept_openclaw_profile`	`true`	Accept OpenClaw-style compatibility metadata
`gateway.skills.security.allow_untrusted_install`	`true`	Allow installs from untrusted sources subject to policy
`gateway.skills.security.min_trust_for_shell_tools`	`untrusted`	Minimum trust level for shell tools
`gateway.skills.security.min_trust_for_http_tools`	`untrusted`	Minimum trust level for HTTP tools
`gateway.skills.security.min_trust_for_function_proxy_tools`	`untrusted`	Minimum trust level for function-proxy tools
`gateway.skills.security.max_install_archive_compressed_bytes`	`10485760`	Maximum compressed skill archive size
`gateway.skills.security.max_install_archive_uncompressed_bytes`	`52428800`	Maximum uncompressed skill archive size
`gateway.skills.security.max_install_archive_entries`	`2048`	Maximum entries in a skill archive
`gateway.skills.security.max_install_file_bytes`	`1048576`	Maximum individual installed skill file size
`gateway.skills.security.upload_ttl_secs`	`3600`	Time-to-live for skill upload sessions
`gateway.skills.security.upload_recommended_chunk_size_bytes`	`262144`	Recommended skill upload chunk size
`gateway.skills.security.upload_max_chunk_size_bytes`	`1048576`	Maximum skill upload chunk size
`gateway.skills.dependencies.preflight_on_resolve`	`true`	Check dependencies before resolving skills
`gateway.skills.dependencies.runtime_recheck_on_tool_call`	`true`	Recheck runtime dependencies before skill tool calls
`gateway.skills.runtime.enable_dynamic_tools`	`true`	Let skills register dynamic tools
`gateway.skills.runtime.enable_read_skill`	`true`	Expose the read-skill runtime helper when enabled
`gateway.skills.runtime.max_dynamic_tools_per_skill`	`64`	Maximum dynamic tools exposed by one skill
`gateway.skills.runtime.read_skill_max_chars`	`72000`	Maximum content returned by read-skill helper
`gateway.skills.runtime.compact_mode_threshold`	`6`	Threshold for compact skill runtime prompt mode
`gateway.skills.runtime.allow_shell_tools`	`true`	Allow skill-provided shell tools when trust policy allows
`gateway.skills.runtime.allow_http_tools`	`true`	Allow skill-provided HTTP tools when trust policy allows
`gateway.skills.runtime.allow_function_proxy_tools`	`true`	Allow skill-provided function-proxy tools when trust policy allows

CLI agent runtime settings

gateway.cli_agent_runtime sets shared defaults for CLI-backed agent runtimes. The legacy app-config fallback is disabled by default. The runtime settings snapshot exposes enabled Codex and Claude instances by default, while named app-config instances can replace or extend that fallback.

Key	Default	Purpose
`gateway.cli_agent_runtime.enabled`	`false`	Enable the legacy Codex and Claude fallback instances from app config.
`gateway.cli_agent_runtime.idle_session_ttl_secs`	`1800`	Time before an idle CLI runtime session can be closed.
`gateway.cli_agent_runtime.startup_timeout_ms`	`30000`	Startup/probe timeout for runtime sessions.
`gateway.cli_agent_runtime.request_timeout_ms`	`120000`	Timeout for runtime requests.
`gateway.cli_agent_runtime.event_channel_capacity`	`2048`	Internal runtime event channel capacity.
`gateway.cli_agent_runtime.stderr_ring_lines`	`200`	Number of recent stderr lines retained for diagnostics.
`gateway.cli_agent_runtime.debug_native_events`	`false`	Include extra native runtime event diagnostics.
`gateway.cli_agent_runtime.command_heartbeat.interval_secs`	`60`	Heartbeat interval for CLI runtime command execution state.
`gateway.cli_agent_runtime.mcp_tools.max_tools`	`512`	Maximum MCP tools materialized for one CLI-backed turn.
`gateway.cli_agent_runtime.mcp_tools.max_total_schema_bytes`	`3145728`	Maximum combined MCP tool-schema size, in bytes, for one CLI-backed turn.
`gateway.cli_agent_runtime.mcp_tools.max_concurrent_calls_per_turn`	`16`	Maximum concurrent MCP tool calls in one CLI-backed turn.

Named instances can be configured under [gateway.cli_agent_runtimes.<id>]:

[gateway.cli_agent_runtimes.codex_work]
kind = "codex"
display_name = "Codex Work"
enabled = true
binary_path = "/opt/homebrew/bin/codex"
home_path = "~/.codex-work"
shadow_home_path = "~/.pioneer/codex/work"
custom_models = ["gpt-5.4"]
app_server_args = ["--experimental"]
startup_probe_timeout_ms = 30000
request_timeout_ms = 45000

startup_probe_timeout_ms is the canonical name for a named runtime instance. startup_timeout_ms remains accepted as a compatibility alias in that section. When gateway.cli_agent_runtimes contains instances, those instances replace the legacy fallback unless the shared enabled flag also adds the defaults. User-facing clients should prefer the settings/get and settings/update cli_runtimes section when editing runtime instances after install.

Voice settings

Voice configuration controls the gateway-side transcription runtime. Microphone capture remains a client concern. The current provider is local; buffered_gateway_session is the default transcription strategy, while experimental_streaming is available for adapters that support it.

Key	Default	Purpose
`gateway.voice.models_dir`	`models/voice`	Model directory under gateway runtime home. The path must stay inside runtime home.
`gateway.voice.transcription_strategy`	`buffered_gateway_session`	Gateway transcription flow.
`gateway.voice.enabled`	`false`	Enable voice input when a provider and model are ready.
`gateway.voice.provider`	unset	Transcription provider. The current supported value is `local`.
`gateway.voice.model`	unset	Local transcription model id.

The settings API reports installation and loading state through voice_input.runtime and gateway_voice_input_status_changed. Use that snapshot to distinguish a disabled voice feature from a model that is downloading, loading, or unavailable.

Remote access settings

Remote access is supervised by the gateway through pioneer-tunnel. App config provides operator defaults; runtime enablement and the relay key are managed through settings/update.

Key	Default	Purpose
`gateway.remote_access.runtime_dir`	`remote-access`	Runtime directory under gateway home for remote-access supervisor files.
`gateway.remote_access.relay_addr`	`relay-eu-west-1.getpioneer.dev:2333`	Relay host and port used by the rathole client.
`gateway.remote_access.local_addr`	`127.0.0.1:17878`	Local gateway address exposed through the relay.
`gateway.remote_access.service_name`	`pioneer_gateway`	Relay service name.
`gateway.remote_access.restart_initial_ms`	`1000`	Initial reconnect delay.
`gateway.remote_access.restart_max_ms`	`30000`	Maximum reconnect delay.
`gateway.remote_access.restart_jitter_percent`	`20`	Reconnect jitter percentage.
`gateway.remote_access.max_restarts`	`0`	Maximum restarts; `0` means retry indefinitely.

The remote-access key is never stored in app config or ordinary settings content. settings/update writes it into the gateway keystore and the settings snapshot exposes only has_key.

Provider attachment settings

Provider runtime settings control request timeouts before the provider-specific adapter runs.

Key	Default	Purpose
`gateway.provider.non_stream_request_timeout_secs`	`120`	Timeout for non-stream provider requests.
`gateway.provider.connect_timeout_secs`	`30`	Provider connection timeout.
`gateway.provider.first_chunk_timeout_secs`	`180`	Streaming timeout before the first chunk.
`gateway.provider.inter_chunk_idle_timeout_secs`	`180`	Streaming idle timeout between chunks.
`gateway.provider.max_stream_duration_secs`	unset	Optional hard limit for the total duration of a streaming provider request.

Provider attachment settings control files, URLs, upload registry behavior, and attachment safety checks.

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.upload_preferred_min_bytes`	`524288`	Minimum size where upload-based transport is preferred.
`gateway.provider.attachments.upload_registry_enabled`	`true`	Enable provider upload registry cache.
`gateway.provider.attachments.upload_registry_ttl_secs`	`604800`	Time-to-live for provider upload registry entries.
`gateway.provider.attachments.enforce_path_allowlist`	`false`	Restrict local attachment paths to configured roots.
`gateway.provider.attachments.allowed_path_roots`	`[]`	Allowed local attachment path roots when allowlist is enforced.
`gateway.provider.attachments.allow_url_sources`	`false`	Allow URL attachment sources. URL sources also require a non-empty domain allowlist and the HTTP and private-network policies that apply to the destination.
`gateway.provider.attachments.allow_http`	`false`	Allow plain HTTP URL sources
`gateway.provider.attachments.allow_private_network`	`false`	Allow private-network URL sources
`gateway.provider.attachments.max_url_redirects`	`3`	Maximum redirects for URL attachments.
`gateway.provider.attachments.url_fetch_timeout_ms`	`15000`	Timeout for URL attachment fetches.
`gateway.provider.attachments.url_fetch_max_bytes`	`20971520`	Maximum bytes fetched from one URL attachment.
`gateway.provider.attachments.url_allowed_domains`	`[]`	Domain allowlist for URL attachments. URL sources remain blocked until this list contains the destination domain.
`gateway.provider.attachments.url_blocked_domains`	`["localhost"]`	Blocked URL attachment domains.
`gateway.provider.attachments.security_dry_run`	`false`	Add a dry-run marker to blocked-attachment diagnostics. A blocked operation remains blocked.
`gateway.provider.attachments.strict_mime_match`	`false`	Require stricter extension/content-type matching.
`gateway.provider.attachments.max_base64_chars`	`209715200`	Maximum base64 payload size accepted.
`gateway.provider.attachments.max_filename_chars`	`128`	Maximum attachment filename length.
`gateway.provider.attachments.retry_max_attempts`	`3`	Retry attempts for transient attachment operations.
`gateway.provider.attachments.retry_initial_backoff_ms`	`200`	Initial retry backoff.
`gateway.provider.attachments.retry_max_backoff_ms`	`2000`	Maximum retry backoff.
`gateway.provider.attachments.retry_jitter_ms`	`80`	Retry jitter.
`gateway.provider.attachments.circuit_breaker_failure_threshold`	`5`	Failures before the attachment circuit breaker opens.
`gateway.provider.attachments.circuit_breaker_open_ms`	`30000`	Circuit breaker open duration.

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.connect_timeout_ms`	`5000`	SQLite connection timeout
`gateway.database.acquire_timeout_ms`	`30000`	SQLite pool acquire timeout
`gateway.database.idle_timeout_ms`	`30000`	SQLite idle connection timeout
`gateway.database.sqlx_logging`	`false`	Enable SQLx query logging

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. The same file also stores gateway-scoped runtime settings that users change through clients, such as memory switches and thread episodic context switches. Clients should change those values with settings/update, not by writing the file directly.

Auth settings

Key	Default	Purpose
`gateway.auth.jwt_issuer`	`pioneer`	JWT issuer
`gateway.auth.jwt_audience`	`pioneer-clients`	JWT audience
`gateway.auth.secret_size_bytes`	`64`	Generated signing secret size
`gateway.auth.token_refresh_leeway_seconds`	`300`	Refresh leeway before access-token expiry
`gateway.auth.access_token_ttl_seconds`	`900`	Access-token lifetime
`gateway.auth.refresh_token_ttl_seconds`	`7776000`	Refresh-token lifetime, 90 days by default
`gateway.auth.device_activation_code_ttl_seconds`	`600`	Device activation-code lifetime
`gateway.auth.auth_exchange_timeout_seconds`	`15`	Timeout for restricted activation and refresh exchanges
`gateway.auth.database_acquire_timeout_ms`	`500`	Database acquire timeout for auth exchanges

The public credential flow is device activation followed by short-lived access credentials and a refresh credential. JWT settings above configure the gateway’s internal access-token implementation; clients should use the device and session methods documented in Identity and authentication, not mint or exchange a shared superuser token.

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.poll_interval_ms`	`200`	Poll interval while waiting for local gateway startup
`desktop.gateway.ws_ping_interval_ms`	`10000`	WebSocket ping interval
`desktop.gateway.ws_pong_timeout_ms`	`30000`	WebSocket pong timeout
`desktop.gateway.ws_reconnect_initial_ms`	`500`	Initial reconnect delay
`desktop.gateway.ws_reconnect_max_ms`	`10000`	Maximum reconnect delay
`desktop.gateway.ws_reconnect_jitter_percent`	`20`	Reconnect jitter percentage
`desktop.gateway.registry_file_name`	`gateway-registry.toml`	Desktop gateway registry file
`desktop.gateway.local_gateway_id`	`local`	Reserved id for the desktop-managed local gateway
`desktop.gateway.registry_version`	`1`	Desktop gateway registry schema version

Getting Started

Desktop App

Mobile App

Providers

Skills

MCP Servers

Tasks & Automation

Configuration

CLI

Configuration Reference

Top-level settings

Install settings

Gateway settings

Telemetry settings

Task review settings

Self-improvement settings

Hook recovery settings

Artifact storage settings

Resilience settings

Agent memory settings

Thread episodic context settings

Vector search

Thread defaults

Web tool settings

Tool loop limits

Execution window limits

Computer-use settings

Skills settings

CLI agent runtime settings

Voice settings

Remote access settings

Provider attachment settings

Database settings

Gateway runtime settings file

Auth settings

Desktop gateway settings

Further reading

​Top-level settings

​Install settings

​Gateway settings

​Telemetry settings

​Task review settings

​Self-improvement settings

​Hook recovery settings

​Artifact storage settings

​Resilience settings

​Agent memory settings

​Thread episodic context settings

​Vector search

​Thread defaults

​Web tool settings

​Tool loop limits

​Execution window limits

​Computer-use settings

​Skills settings

​CLI agent runtime settings

​Voice settings

​Remote access settings

​Provider attachment settings

​Database settings

​Gateway runtime settings file

​Auth settings

​Desktop gateway settings

​Further reading

Top-level settings

Install settings

Gateway settings

Telemetry settings

Task review settings

Self-improvement settings

Hook recovery settings

Artifact storage settings

Resilience settings

Agent memory settings

Thread episodic context settings

Vector search

Thread defaults

Web tool settings

Tool loop limits

Execution window limits

Computer-use settings

Skills settings

CLI agent runtime settings

Voice settings

Remote access settings

Provider attachment settings

Database settings

Gateway runtime settings file

Auth settings

Desktop gateway settings

Further reading