Settings Reference¶

SynthOrg has ~100 individually-resolved settings across 17 namespaces. Each setting is typed (STRING, INTEGER, FLOAT, BOOLEAN, ENUM, JSON) and has a clearly-documented default. This guide covers how resolution works, which namespaces are user-facing vs operator-only, and how to edit settings at runtime.

Resolution Order¶

Settings resolve through four layers, in priority order (first wins):

1. Database -- values set via the REST API or dashboard persist here
2. Environment variables (SYNTHORG_<NAMESPACE>_<KEY>)
3. YAML config file (synthorg-config.yaml at boot)
4. Code defaults (the SettingDefinition.default field)

DB-backed changes take effect without restart unless the setting is marked restart_required=True.

Setting Types¶

Values marked sensitive=True (API keys, webhook URLs, passwords) are Fernet-encrypted at rest and returned from GET responses as "***" placeholders.

Namespaces¶

User-facing (visible in the dashboard)¶

Operator-only (operator-tunable, hidden from the basic UI)¶

These surface previously-hardcoded timeouts, batch sizes, and resource limits. All default to the ADVANCED level.

REST API¶

All namespaces expose the same endpoint pattern:

# List all settings in a namespace with current values
curl http://localhost:3001/api/v1/settings/api \
  -H "Cookie: session=${TOKEN}"

# Get a single setting's schema (type, default, bounds, description)
curl http://localhost:3001/api/v1/settings/api/rate_limit.auth_max_requests/schema \
  -H "Cookie: session=${TOKEN}"

# Update a single setting
curl -X PUT http://localhost:3001/api/v1/settings/api/rate_limit.auth_max_requests \
  -H "Content-Type: application/json" \
  -H "Cookie: session=${TOKEN}" \
  -d '{"value": 12000}'

# Reset a setting to its default
curl -X DELETE http://localhost:3001/api/v1/settings/api/rate_limit.auth_max_requests \
  -H "Cookie: session=${TOKEN}"

Security policy settings can be exported and re-imported as a bundle:

# Export all registered security settings
curl http://localhost:3001/api/v1/settings/security/export \
  -H "Cookie: session=${TOKEN}" > security-policy.json

# Import into another deployment
curl -X POST http://localhost:3001/api/v1/settings/security/import \
  -H "Content-Type: application/json" \
  -H "Cookie: session=${TOKEN}" \
  -d @security-policy.json

Restart-Required Settings¶

Some settings are bootstrap-only and cannot be hot-reloaded safely. They are marked with restart_required=True in the schema. Common examples:

• api.rate_limit.floor_max_requests / unauth_max_requests / auth_max_requests (the three-tier rate limiter builds at startup)
• api.per_op_rate_limit.backend / api.per_op_concurrency.backend (the per-op stores are constructed once at startup; enabled / overrides ARE runtime-editable)
• api.cors.allowed_origins (Litestar CORS plugin registers at construction)
• backup.path (backup scheduler's output directory)
• observability.ws_ticket_max_pending_per_user (ticket store is constructed once)

Changing a restart-required setting writes the new value to the database but the running process continues using the old value. Restart the backend to pick up the change.

Hot-reloaded Settings¶

The SettingsChangeDispatcher polls the #settings message bus channel and routes change events to registered SettingsSubscriber implementations. Concrete subscribers today:

• ProviderSettingsSubscriber -- rebuilds ModelRouter on routing_strategy change via AppState.swap_model_router()
• MemorySettingsSubscriber -- advisory logging for non-restart memory settings
• BackupSettingsSubscriber -- toggles BackupScheduler on enabled change, reschedules on schedule_hours change

Settings resolved via ConfigResolver bridge configs (e.g. get_communication_bridge_config()) are re-fetched at the top of each polling iteration in their consumers -- operator changes take effect within one poll cycle without restart.

Per-Operation Rate Limiting¶

Two layered rate-limit subsystems sit on top of the global three-tier limiter (api.rate_limit.*). Both are runtime-editable via settings.

Sliding-window guard (api.per_op_rate_limit.*)¶

Example override to tighten memory.fine_tune to two starts per day. The SettingsController routes by (namespace, key) where key is the registry key (underscores), not the yaml_path (dots):

curl -X PUT http://localhost:3001/api/v1/settings/api/per_op_rate_limit_overrides \
  -H "Content-Type: application/json" \
  -H "Cookie: session=${TOKEN}" \
  -d '{"value": "{\"memory.fine_tune\": [2, 86400]}"}'

Inflight concurrency guard (api.per_op_concurrency.*)¶

The six endpoints that declare an inflight cap by default: memory.fine_tune (shared with memory.fine_tune_resume), memory.checkpoint_deploy, memory.checkpoint_rollback, providers.pull_model, providers.discover_models.

Common Configuration Patterns¶

Switch LLM providers¶

Add or update a provider via /api/v1/providers, set routing.strategy via /api/v1/settings/providers/routing_strategy to smart (or the strategy of your choice). The model router rebuilds immediately.

Enable agent sandbox¶

Set tools.sandboxing.default_backend to docker in the tools namespace. Pull the sandbox image once via synthorg start --sandbox true. The backend spawns ephemeral sandbox containers per tool invocation.

Adjust ceremony strategy¶

Edit coordination.ceremony.strategy in the coordination namespace. See Ceremony Scheduling for the available strategies.

Swap log sinks¶

Use observability.custom_sinks (JSON-typed) to add HTTP / syslog / OTLP shipping. See Centralized Logging for examples.

See Also¶

• Company Configuration -- YAML bootstrap config reference
• Security & Trust Policies -- autonomy, approvals, trust
• Centralized Logging -- log sink configuration
• Design: Observability -- architecture and event taxonomy