Settings API

Settings methods expose the gateway-owned runtime settings that clients can read and update over JSON-RPC. These settings are gateway-scoped, not workspace-scoped. Provider API keys, MCP secrets, skills, tasks, artifacts, and workspace state remain separate workspace-owned surfaces. The gateway loads settings from app config defaults and its runtime settings file, then returns the effective snapshot. Updates are persisted to the same gateway settings file. Runtime systems that depend on these settings, such as memory hooks, thread episodic context, CLI runtime instances, keep-awake, and remote access, are refreshed through the gateway instead of requiring clients to edit files directly. This matters for remote gateways. A desktop or mobile client should call settings/get and settings/update; it should not write gateway-settings.toml on disk.

Methods

Method	Params	Result	Purpose
`settings/get`	`GatewaySettingsGetParams`	`GatewaySettingsGetResponse`	Return the effective gateway settings snapshot.
`settings/update`	`GatewaySettingsUpdateParams`	`GatewaySettingsUpdateResponse`	Persist gateway settings overrides and return the new effective snapshot.

Snapshot shape

The response contains a settings object with general, memory, thread_episodic, cli_runtimes, and remote_access sections.

Section	Fields
`general`	`keepawake`, `preflight_model`
`memory`	`enabled`, `deterministic_recall_enabled`, `active_recall_enabled`, `tools_enabled`, `proactive_writes_enabled`, `background_extraction_enabled`, `proactive_writes_model`, `debug_trace_enabled`, `strict_diagnostics_enabled`
`thread_episodic`	`enabled`, `indexing_enabled`, `recall_enabled`, prompt budgets, chunking limits, recall thresholds, index job retry settings, and capacity warning thresholds.
`cli_runtimes`	Complete list of configured CLI runtime instances: `id`, `kind`, `display_name`, `enabled`, `binary_path`, `home_path`, and optional `shadow_home_path`.
`remote_access`	Remote-access enablement, relay server display value, service name, transport, key presence, and live status snapshot.

Model selection objects use:

Field	Meaning
`source`	`thread` to inherit the thread model, or `custom` to use an explicit provider and model.
`model_provider`	Required for effective custom model overrides.
`model`	Required for effective custom model overrides.

Reading settings

settings/get accepts an empty params object.

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "settings/get",
  "params": {}
}

Response:

{
  "settings": {
    "general": {
      "keepawake": false,
      "preflight_model": {
        "source": "thread"
      }
    },
    "memory": {
      "enabled": true,
      "deterministic_recall_enabled": true,
      "active_recall_enabled": true,
      "tools_enabled": true,
      "proactive_writes_enabled": true,
      "background_extraction_enabled": true,
      "proactive_writes_model": {
        "source": "thread"
      },
      "debug_trace_enabled": false,
      "strict_diagnostics_enabled": false
    },
    "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,
      "chunk_target_min_chars": 700,
      "chunk_target_max_chars": 1200,
      "chunk_max_chars": 1600,
      "max_chunks_per_item": 64,
      "index_batch_limit": 16,
      "retry_base_delay_secs": 30,
      "retry_max_delay_secs": 900,
      "max_attempts": 5,
      "near_capacity_percent": 90.0
    },
    "cli_runtimes": {
      "instances": [
        {
          "id": "codex",
          "kind": "codex",
          "display_name": "Codex CLI",
          "enabled": true,
          "binary_path": "codex",
          "home_path": "~/.codex"
        }
      ]
    },
    "remote_access": {
      "enabled": false,
      "server": "relay-eu-west-1.getpioneer.dev:2333",
      "service_name": "pioneer_gateway",
      "transport": "tcp",
      "has_key": false,
      "status": {
        "state": "disabled"
      }
    }
  }
}

Updating settings

settings/update takes an update object. general is a patch: omitted fields keep their current effective value. thread_episodic is also a patch. memory is a complete memory settings object when present, so clients should send the full memory section they want to keep. cli_runtimes is a complete runtime instance list when present. remote_access is a patch for user-facing remote-access controls.

{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "settings/update",
  "params": {
    "update": {
      "general": {
        "keepawake": true,
        "preflight_model": {
          "source": "custom",
          "model_provider": "openai",
          "model": "gpt-5.1"
        }
      }
    }
  }
}

To update memory settings, send the full memory section:

{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "settings/update",
  "params": {
    "update": {
      "memory": {
        "enabled": true,
        "deterministic_recall_enabled": true,
        "active_recall_enabled": false,
        "tools_enabled": true,
        "proactive_writes_enabled": false,
        "background_extraction_enabled": true,
        "proactive_writes_model": {
          "source": "thread"
        },
        "debug_trace_enabled": false,
        "strict_diagnostics_enabled": false
      }
    }
  }
}

The response shape is the same as settings/get and contains the new effective snapshot. To update one thread-context setting, send only that field under thread_episodic:

{
  "jsonrpc": "2.0",
  "id": "ddddddddddddddddddddd",
  "method": "settings/update",
  "params": {
    "update": {
      "thread_episodic": {
        "enabled": false
      }
    }
  }
}

Disabling thread_episodic.enabled turns off the thread context layer as a whole. Disabling only indexing_enabled stops new indexing work while leaving existing state in place. Disabling only recall_enabled keeps indexing available but prevents recalled thread snippets from entering future prompts. To update CLI runtime instances, send the full cli_runtimes.instances list you want the gateway to keep:

{
  "jsonrpc": "2.0",
  "id": "eeeeeeeeeeeeeeeeeeeee",
  "method": "settings/update",
  "params": {
    "update": {
      "cli_runtimes": {
        "instances": [
          {
            "id": "codex",
            "kind": "codex",
            "display_name": "Codex CLI",
            "enabled": true,
            "binary_path": "codex",
            "home_path": "~/.codex",
            "shadow_home_path": null
          },
          {
            "id": "codex_work",
            "kind": "codex",
            "display_name": "Codex Work",
            "enabled": false,
            "binary_path": "/opt/homebrew/bin/codex",
            "home_path": "~/.codex-work",
            "shadow_home_path": "~/.pioneer/codex/work"
          }
        ]
      }
    }
  }
}

Runtime ids and display names must be unique after normalization. binary_path, home_path, and shadow_home_path are validated before the settings file is saved. To enable remote access, send the enable flag and key. The key is written to the gateway keystore and is not serialized into gateway-settings.toml.

{
  "jsonrpc": "2.0",
  "id": "fffffffffffffffffffff",
  "method": "settings/update",
  "params": {
    "update": {
      "remote_access": {
        "enabled": true,
        "key": "relay-token"
      }
    }
  }
}

To clear the remote-access key:

{
  "method": "settings/update",
  "params": {
    "update": {
      "remote_access": {
        "clear_key": true
      }
    }
  }
}

remote_access.status is live runtime state. Clients receive gateway/remote_access/status_changed when the relay connection moves through states such as starting, connected, reconnecting, failed, or stopped.

Schemas

Generated schemas include:

/schemas/gateway_settings_get_params.json
/schemas/gateway_settings_get_response.json
/schemas/gateway_settings_update_params.json
/schemas/gateway_settings_update_response.json
/schemas/gateway_settings_snapshot.json
/schemas/gateway_general_settings.json
/schemas/gateway_general_settings_update.json
/schemas/gateway_memory_settings.json
/schemas/gateway_memory_model_selection.json
/schemas/gateway_memory_model_selection_source.json
/schemas/gateway_thread_episodic_settings.json
/schemas/gateway_thread_episodic_settings_update.json
/schemas/gateway_cli_runtime_settings.json
/schemas/gateway_cli_runtime_instance_settings.json
/schemas/gateway_remote_access_settings.json
/schemas/gateway_remote_access_settings_update.json
/schemas/gateway_remote_access_status_snapshot.json

Remote Access Architecture explains gateway-owned tunnel supervision and status projection.
CLI Runtime Architecture explains CLI runtime settings and recovery behavior.
Secret Storage explains why settings snapshots expose secret presence instead of raw values.

Introduction

Workspace & Threads

Features

Methods

Snapshot shape

Reading settings

Updating settings

Schemas

​Methods

​Snapshot shape

​Reading settings

​Updating settings

​Schemas

​Related pages

Methods

Snapshot shape

Reading settings

Updating settings

Schemas

Related pages