Settings API

Settings methods expose gateway-owned runtime settings and the workspace-scoped self-improvement settings associated with the RPC connection. Clients can read and update them over JSON-RPC. Provider API keys, MCP secrets, skills, tasks, artifacts, and other workspace state remain separate surfaces. The gateway loads runtime settings from app config defaults and its runtime settings file, then returns the effective snapshot. Updates are persisted to the same gateway settings file. Self-improvement settings are resolved for the workspace bound to the RPC connection. Runtime systems that depend on these settings, such as memory hooks, thread episodic context, CLI runtime instances, keep-awake, voice input, 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, self_improvement, thread_episodic, cli_runtimes, remote_access, and voice_input sections.

Section	Fields
`general`	`keepawake`, `telemetry_enabled`, `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`
`self_improvement`	`enabled`, plus optional `default_model` and `reviewer_model` selections for the workspace.
`thread_episodic`	`enabled`, `indexing_enabled`, `recall_enabled`, prompt budgets, recall thresholds, index job retry settings, capacity warning threshold, and nested `vector_search` settings.
`cli_runtimes`	Complete list of configured CLI runtime instances: `id`, `kind`, `display_name`, `nickname`, `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.
`voice_input`	Voice-input enablement, local provider/model selection, and model installation/runtime state.

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.

Self-improvement model selections use a separate object with provider and model. They are workspace settings, and they must name native API providers. CLI runtime ids and local providers are not valid self-improvement model selections. Vector search reports both configuration and readiness. provider_key tells the client whether the selected remote provider needs a key and whether one is present. refill_status reports index work, while local_model_status reports local model installation. Refill status values are disabled, unknown, required, running, complete, and failed. Local model status values are not_selected, unknown, missing, downloading, installed, and failed. Voice runtime phases are disabled, model_not_selected, missing, downloading, installing, loading, ready, and failed. effective_enabled reports whether the gateway can accept voice input after applying configuration and runtime readiness.

Reading settings

settings/get accepts an empty params object.

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

Response:

{
  "settings": {
    "general": {
      "keepawake": false,
      "telemetry_enabled": true,
      "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
    },
    "self_improvement": {
      "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,
      "index_batch_limit": 16,
      "retry_base_delay_secs": 30,
      "retry_max_delay_secs": 900,
      "max_attempts": 5,
      "near_capacity_percent": 85.0,
      "vector_search": {
        "enabled": false,
        "embedding_normalized": true,
        "use_search_instructions": false,
        "provider_key": {
          "required": false,
          "present": false
        },
        "refill_status": "disabled",
        "local_model_status": "not_selected"
      }
    },
    "cli_runtimes": {
      "instances": [
        {
          "id": "codex",
          "kind": "codex",
          "display_name": "Codex",
          "nickname": "codex",
          "enabled": true,
          "binary_path": "codex",
          "home_path": "~/.codex"
        },
        {
          "id": "claude",
          "kind": "claude",
          "display_name": "Claude",
          "nickname": "claude",
          "enabled": true,
          "binary_path": "claude",
          "home_path": "~/.claude"
        }
      ]
    },
    "remote_access": {
      "enabled": false,
      "server": "relay-eu-west-1.getpioneer.dev:2333",
      "service_name": "pioneer_gateway",
      "transport": "tcp",
      "has_key": false,
      "status": {
        "state": "disabled"
      }
    },
    "voice_input": {
      "enabled": false,
      "runtime": {
        "phase": "disabled",
        "effective_enabled": false
      }
    }
  }
}

Updating settings

settings/update takes an update object. general is a patch: omitted fields keep their current effective value. thread_episodic and its nested vector_search object are patches. memory is a complete memory settings object when present, so clients should send the full memory section they want to keep. self_improvement is a complete workspace settings object when present. cli_runtimes is a complete runtime instance list when present. remote_access and voice_input are patches for their user-facing 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 vector search, send only the fields that should change inside thread_episodic.vector_search:

{
  "method": "settings/update",
  "params": {
    "update": {
      "thread_episodic": {
        "vector_search": {
          "enabled": true,
          "provider": "openrouter",
          "model": "openai/text-embedding-3-small",
          "embedding_normalized": true,
          "use_search_instructions": true
        }
      }
    }
  }
}

Set provider, model, or local_model to null to clear a selection. The gateway reports embedding_dimension and readiness fields; clients cannot set those fields. To enable workspace self-improvement, send the complete section with native API provider and model selections:

{
  "method": "settings/update",
  "params": {
    "update": {
      "self_improvement": {
        "enabled": true,
        "default_model": {
          "provider": "openai",
          "model": "gpt-5.4"
        },
        "reviewer_model": {
          "provider": "openai",
          "model": "gpt-5.4"
        }
      }
    }
  }
}

The gateway enables the learner only when the selected model is eligible and available. Learned skills stay workspace-scoped and pass the same policy, visibility, and prompt-capacity checks as installed skills. 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",
            "nickname": "codex",
            "enabled": true,
            "binary_path": "codex",
            "home_path": "~/.codex",
            "shadow_home_path": null
          },
          {
            "id": "claude",
            "kind": "claude",
            "display_name": "Claude",
            "nickname": "claude",
            "enabled": true,
            "binary_path": "claude",
            "home_path": "~/.claude",
            "shadow_home_path": null
          }
        ]
      }
    }
  }
}

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 update voice input, send a patch. provider and model accept null when the current selection should be cleared. Set retry_install to true to retry a failed local model installation.

{
  "method": "settings/update",
  "params": {
    "update": {
      "voice_input": {
        "enabled": true,
        "provider": "local",
        "model": "parakeet-tdt-0.6b-v3",
        "retry_install": true
      }
    }
  }
}

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_self_improvement_settings.json
/schemas/gateway_self_improvement_model_selection.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_thread_episodic_vector_search_settings.json
/schemas/gateway_thread_episodic_vector_search_settings_update.json
/schemas/gateway_thread_episodic_vector_provider.json
/schemas/gateway_thread_episodic_vector_provider_key_status.json
/schemas/gateway_thread_episodic_vector_refill_status.json
/schemas/gateway_thread_episodic_vector_local_model_status.json
/schemas/gateway_thread_episodic_vector_refill_status_changed_notification.json
/schemas/gateway_cli_runtime_settings.json
/schemas/gateway_cli_runtime_instance_settings.json
/schemas/gateway_native_agent_config.json
/schemas/gateway_remote_access_transport.json
/schemas/gateway_remote_access_state.json
/schemas/gateway_remote_access_error_kind.json
/schemas/gateway_remote_access_status_changed_notification.json
/schemas/gateway_remote_access_settings.json
/schemas/gateway_remote_access_settings_update.json
/schemas/gateway_remote_access_status_snapshot.json
/schemas/gateway_settings_update.json
/schemas/gateway_voice_input_provider.json
/schemas/gateway_voice_input_settings.json
/schemas/gateway_voice_input_settings_update.json
/schemas/gateway_voice_input_runtime_snapshot.json
/schemas/gateway_voice_input_runtime_phase.json
/schemas/gateway_voice_input_status_changed_notification.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