config.*

config.* exposes runtime configuration management. Every method below takes effect without a gateway restart; per-method side effects are noted inline.

Methods

Registered in HandlerRegistry::new() but not normally called via RPC — they back the boot path:

config.apply (full overwrite) is not currently registered. To replace the configuration wholesale, use config.patch followed by config.reload.

config.schema

Return the full JSON Schema for ~/.aleph/config.json. Takes no parameters.

Request:

{ "jsonrpc": "2.0", "id": 1, "method": "config.schema" }

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "schema": { "type": "object", "$schema": "...", "properties": { "...": { "...": "..." } } }
  }
}

config.get

Read the active configuration as seen by ConfigWatcher.

Request:

{ "jsonrpc": "2.0", "id": 1, "method": "config.get" }

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "config": {
      "general": { "default_provider": "openai", "fallback_providers": [] },
      "execution": { "default_timeout_secs": 600, "max_runs_global": 16 }
    },
    "source": "/home/user/.aleph/config.json",
    "loaded_at": 1706400000000
  }
}

Sensitive fields (API keys, tokens) are redacted in the response. source and loaded_at identify where the active configuration was loaded from.

config.patch

Apply a partial override using JSON Merge Patch (RFC 7386-style). Only the fields you provide are modified; everything else is preserved.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "config.patch",
  "params": {
    "patch": {
      "execution": { "max_runs_global": 32 },
      "general": { "fallback_providers": ["anthropic", "openai"] }
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "applied": true,
    "changed_keys": ["execution.max_runs_global", "general.fallback_providers"],
    "restart_required": false
  }
}

Parameters:

When restart_required is true, an interface or service must be restarted for the change to take effect; the affected components are listed under restart_components.

config.reload

Reload the configuration from the config file on disk. Use this after manually editing the file or syncing it from a dotfiles repository.

Request:

{ "jsonrpc": "2.0", "id": 1, "method": "config.reload" }

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "reloaded": true,
    "source": "/home/user/.aleph/config.json",
    "changed_keys": ["general.default_provider"],
    "restart_required": false
  }
}

Hot Reload & Reloadable Fields

The [gateway.config_watcher] controls the file watcher; any save triggers the reload pipeline:

1. Debounce -- wait 500 ms so all writes settle
2. Parse -- read and parse the new configuration
3. Validate -- check against the schema
4. Diff -- compute changed field paths
5. Apply -- update the in-memory config and restart affected interfaces
6. Notify -- emit a config.changed event to subscribed clients

{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "topic": "config.changed",
    "data": {
      "section": "execution",
      "value": { "max_runs_global": 32 },
      "timestamp": 1706400000000
    }
  }
}

Hot-reloadable: [general] model catalog and failover chain, [providers.*] provider config, channel on/off, [execution] run caps, [cron] scheduler settings, [exec] approval rules.

Requires restart: core port, bind address, TLS certificates, [memory] embedding model and vector store, [browser] CDP settings.

Related Configuration Sections

config.* does not read or write these dedicated sections; use their namespaces instead:

See Also

• Methods Reference -- All method namespaces
• Protocol -- JSON-RPC 2.0 transport