Settings Reference¶

SynthOrg has over 300 individually-resolved settings across 34 namespaces, split between user-facing namespaces (visible in the dashboard) and operator-only namespaces (operator-tunable, hidden from the basic UI). 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 three sources, in priority order (first wins):

Database: values set via the REST API or dashboard persist here
Environment variables (SYNTHORG_<NAMESPACE>_<KEY>)
Code defaults (the SettingDefinition.default field)

YAML (synthorg-config.yaml) is a company-template ingestion format, not a precedence tier: synthorg init reads it once to seed the database, and its values are thereafter resolved through the chain above. See Configuration Precedence for the full model.

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

Setting Types¶

Type	Example	Validation
`STRING`	`api.base_url`	Length bounds, regex
`INTEGER`	`api.rate_limit.auth_max_requests`	`min`/`max` bounds
`FLOAT`	`budget.risk_budget.per_task_risk_limit`	`gt`/`ge`/`lt`/`le`
`BOOLEAN`	`notifications.min_severity.enabled`	true/false
`ENUM`	`observability.root_log_level`	Validated against `enum_values`
`JSON`	`providers.configs`	Pydantic schema

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)¶

Namespace	What it configures
`api`	Rate limits, CORS, request timeouts, auth cookie settings
`company`	Company name, autonomy level, monthly budget, currency, model-tier profile, communication pattern
`providers`	LLM provider CRUD, routing strategy, SSRF discovery allowlist
`memory`	Memory backend, retention, embedding model, consolidation policy
`budget`	Monthly budget, currency, alerts, auto-downgrade, risk budget, quota poller
`security`	Autonomy levels, approval policies, output scanner, policy engine
`coordination`	Coordination metrics, error taxonomy, orchestration ratio alerts
`observability`	Log level, correlation tracking, sink overrides, custom sinks
`appearance`	Dashboard theme axes (colour palette, density, typography, animation, sidebar mode)
`dashboard`	Misc dashboard UI preferences (sidebar collapsed, recent commands, advanced-mode toggles, dismissals)
`org_chart`	Org-chart view preferences (particle flow, badges, status dots, minimap, collapsed departments)
`backup`	Enabled, schedule, compression, retention count/age
`cockpit`	Flight-recorder run replay, stuck/runaway thresholds, snapshot cadence, steering proposer and active-directive limits

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.

Namespace	What it configures
`engine`	Prompt profiles, stagnation detection, context compaction, evolution, crash recovery, health monitoring
`communication`	Message bus configuration, delegation policies, meeting protocol timeouts
`a2a`	A2A gateway auth, allowlist, agent card verification, webhook security
`integrations`	Secret backend, OAuth manager, health prober interval, webhook dedup window
`meta`	Self-improvement signal aggregation, rollout strategies, proposer model
`notifications`	Sink registry, dispatcher timeout, severity threshold
`tools`	Sandbox backends, tool access levels, progressive disclosure thresholds
`settings`	Dispatcher polling interval, change-notification channel
`client`	Human-response timeout, scored-feedback passing score / strictness multiplier / floor for synthesised AIClients
`hr`	Training-pipeline kill switch, evaluation metric toggles (quality, cost, latency, task count)
`simulations`	Client-intake benchmark door toggle (`client_intake_enabled`, off by default) and per-run timeouts for synthetic-client task and code-review simulations
`telemetry`	Anonymous product telemetry opt-in (off by default; token embedded at build)
`workers`	Uvicorn worker count, distributed dispatcher publish retry budget and backoff
`research`	Research-mode provider/model and pipeline strategies (query planning, credibility triage, deduplication, synthesis)
`charter`	Deep CEO-interview charter pacing (model, turns, temperature, token budget) and default currency
`external_api`	Governed external API access: provider, response-size cap, timeout, and per-minute rate limit
`self_improvement`	Self-modifying meta-loop: master and per-strategy toggles, toolsmith gate, per-call models, and structural tuning (schedule, rollout, regression, guards); every switch defaults off
`chief_of_staff`	Unified-chat + Chief-of-Staff capability flags (turn-router, multi-voice, propose, concern-routing, group-chat, learning, alerts, narrative, invite, direct-MCP) and per-feature models
`knowledge`	Knowledge substrate (document ingestion + retrieval) enable and optional generative-RAG synthesis (model, strategy, per-answer chunk budget)
`design`	Image-generation master flag and the image model the design `image_generator` tool routes through
`demo`	Demo-mode showcase content (e.g. greeting copy)

Security headers and error documentation¶

The api namespace also carries operator-tunable settings that govern the response surface of /docs/ and RFC 9457 error payloads, and the notifications namespace has a Slack default URL fallback:

Setting	Type	Default	Purpose
`api.csp_docs_external_origins`	JSON list	`["https://cdn.jsdelivr.net", "https://fonts.scalar.com", "https://proxy.scalar.com"]`	Trusted external origins used to build the relaxed Content-Security-Policy on `/docs/` paths. Override with internally-mirrored hosts when the backend is not allowed to reach the public Scalar CDN. Each origin must match `^https?://[\w.\-:/]+$`; a malformed entry rejects the bridge config and the runtime falls back to defaults with a `WARNING` log.
`api.error_docs_base_url`	STRING	`https://synthorg.io/docs/errors`	Base URL appended with `#<category>` for the RFC 9457 `type` field on every error response. HTTPS-only (`^https://[A-Za-z0-9.\-]+(?::\d{1,5})?(?:/[^\s?#]*)?$`); userinfo, query, and fragment components are rejected at runtime.
`notifications.slack_default_webhook_url`	STRING (sensitive)	`""`	Optional fallback Slack incoming webhook applied when a Slack sink is configured without its own `webhook_url`. Empty default keeps every sink explicit; setting a value lets operators centralise the URL. Encrypted at rest.

All three are restart_required=True: the CSP and error-docs URL are baked into module-level state during startup; the Slack default is read at sink construction and is not hot-reloaded.

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": 1200}'

# 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.rate_limit_auth_endpoint_max_requests (the dedicated per-minute limiter applied as route middleware on the login / setup / change-password / dev-login endpoints; bound at module import, read_only_post_init)
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)
observability.tsa_endpoint_freetsa / tsa_endpoint_digicert / tsa_endpoint_sectigo (the timestamp trust-anchor URL is baked into TsaClient at construction with trust-root validation; swapping the authority mid audit-chain is security-sensitive)

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 the provider registry on retry_max_attempts change and triggers a runtime-services rebuild so the running engine adopts the new cap
BackupSettingsSubscriber: toggles BackupScheduler on enabled change, reschedules on schedule_hours change, re-points the backup path on path change, and re-applies the compression / on_shutdown / on_startup config flags onto the live service
EvalLoopSettingsSubscriber: re-resolves the hr.eval_loop_* model / provider / mode keys and swaps the rebuilt pattern-identifier + fix-proposer strategies onto the live eval-loop coordinator
GithubApiUrlSettingsSubscriber: re-binds integrations.github_api_url onto the GitHub health checker
ObservabilityBridgeSettingsSubscriber: re-applies audit_chain_signing_timeout_seconds onto the live audit sink (plus the HTTP-log batch knobs)
plus the per-domain bridge / live-config subscribers (api, workers, observability, security, tools, notifications, research, knowledge, simulations, ...) registered in api/lifecycle_helpers/settings_dispatcher.py

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, so 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.*`)¶

Setting	Type	Default	Runtime-editable	Purpose
`api.per_op_rate_limit.enabled`	BOOLEAN	`true`	yes	Master switch; when `false` every `per_op_rate_limit` guard becomes a no-op.
`api.per_op_rate_limit.backend`	ENUM	`memory`	no (restart)	Sliding-window store backend. `memory` is the only shipped implementation; `redis` is reserved for cross-worker fairness.
`api.per_op_rate_limit.overrides`	JSON	`{}`	yes	Per-operation overrides keyed by operation name. Shape: `{"<op>": [max_requests, window_seconds]}`. Setting either component to `0` disables the guard for that operation; negative values are rejected.

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.*`)¶

Setting	Type	Default	Runtime-editable	Purpose
`api.per_op_concurrency.enabled`	BOOLEAN	`true`	yes	Master switch for the `PerOpConcurrencyMiddleware`.
`api.per_op_concurrency.backend`	ENUM	`memory`	no (restart)	Inflight-counter store backend. `memory` today; `redis` reserved.
`api.per_op_concurrency.overrides`	JSON	`{}`	yes	Per-operation overrides keyed by operation name. Shape: `{"<op>": <max_inflight>}`. `0` disables; negative values are rejected.

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 Centralised Logging for examples.