Full Configuration Reference
Pydantic validates every field at startup and applies its default. See Configuration for a faster path to a working setup, or Environment Variables for the override list.
Full reference
Section titled “Full reference”storage: mongodb: # required — MongoDB is the only storage backend uri: "mongodb://user:pass@host:27017/db?authSource=db" database: "opentremor" # collection names below all have defaults — override only if you need to
cors: allow_origins: ["https://your-app.example.com"] # ["*"] for dev allow_credentials: true allow_methods: ["GET", "POST", "PUT", "PATCH", "DELETE"] allow_headers: ["*"]
auth: api_key: "change-me-to-a-strong-secret" # null → disabled (anonymous default-org owner)
jwt: # secret: "set-me-in-production" # random per-process if omitted refresh_ttl_days: 14 # reserved; refresh-token rotation not yet implemented
# session.access_ttl_minutes isn't set here — it's platform-managed, see below
two_factor: # secret_encryption_key: "set-me-in-production" # random per-process if omitted
rate_limit: enabled: true # the thresholds are NOT set here — they're platform-managed, see below
network: trusted_proxies: ["172.30.12.0/24"] # the proxies in front of core; [] ignores X-Forwarded-For filter_enabled: true # false turns every network access rule off list_sources_dir: "/etc/opentremor/network-lists" # where `file` address lists are read; unset refuses them
secrets: # encryption_key: "set-me-in-production" # random per-process if omitted
mail: backend: "log" # log | smtp — see /configuration/email/
# llm is NOT set here — enabled and egress are platform-managed, see below
gitlab: # egress is NOT set here — it's platform-managed, see below # ca_bundle: "/etc/opentremor/company-ca.pem" # default for orgs that paste no CA of their own
github: # api_base_url: "https://api.github.com" # GitHub's REST API; change it only for a test fake
notifications: # Defaults are usually right: any public address, no private networks. Set # allow_private_networks when self-hosting and notifying something on your own network. egress: enabled: true allow_private_networks: false allowed_hosts: [] max_channels_per_org: 20 max_recipients_per_channel: 20 timeout_seconds: 5.0
deployment: mode: "self_hosted" # self_hosted | cloud — see belowThat’s the entire file — logging, registration, branding, social_login, server, session,
telemetry, retention, jobs, analysis, feedback and org_offboarding are deliberately
absent, and rate_limit and llm appear with only their file-only fields; see below.
The example configs shipped in each repo (OpenTremor-core/configs/opentremor-core*.yaml,
OpenTremor-platform/configs/opentremor-platform*.yaml) point here rather than restating any of
it — this page is the single source of truth for which sections a config file can set.
Platform settings — admin-editable subset
Section titled “Platform settings — admin-editable subset”logging, registration, branding, social_login, server, session, telemetry, retention,
jobs, analysis, feedback, knowledge, org_offboarding, audit_push, gitlab.egress, jira and llm are not read from this file or from any
environment variable. Their only possible baseline is a fixed, hardcoded default
(the Pydantic field default shown in each section below). create_app() resets these sections
to that default when it loads the config, discarding any file or environment values for
them before anything else in the process reads them. The only way to change one is
GET/PATCH /v1/admin/settings (superadmin only — in the dashboard, the settings pages under
Platform Admin → Security, Connections and System).
This is deliberate, not a limitation: previously, an admin-editable field with no override yet simply reflected whatever the local YAML happened to contain — which meant two instances that had never been touched via the admin UI could show different “effective” values purely because they shipped with different config files, with no way to tell a deliberate choice from incidental YAML drift. Resetting these sections to one fixed, documented default removes that ambiguity by construction: there is exactly one baseline and exactly one way to change it.
A config file can still set one of these fields. The server does not reject it, but the value has
no effect. At boot, the server logs a warning that names each such field. GET /v1/admin/settings
lists them under ignored_file_settings. The dashboard shows a note under each one with the value
the file sets. Remove the field from the file, or set the value in the dashboard.
Covered — hardcoded default + live database override, no restart, ever: logging,
registration, branding, social_login, server, session, rate_limit (thresholds only), retention,
jobs, analysis, feedback, knowledge, org_offboarding, audit_push, gitlab (egress only), jira, llm (enabled and egress). A PATCH
takes effect for the very next request. For session.access_ttl_minutes, it takes effect at the next
login or session switch and does not retroactively extend a cookie a user already holds. For
retention.telemetry_days/retention.audit_days, it takes effect immediately: the change is
pushed live onto the running MongoDB TTL indexes via collMod, not just re-read on the next request.
See Data Retention for retention’s field-by-field detail,
Platform Admin — Running a stuck-job sweep manually
for jobs’s, and Deleting an organization for
org_offboarding’s — all three are covered here only at the same summary depth as every other
section.
Excluded — genuinely file/env-driven (unaffected by any of the above):
| Section | Why |
|---|---|
storage | The MongoDB connection string cannot be stored in the database it points to. |
cors | These settings are security-critical. Changing them from an authenticated session must not be possible. |
auth | api_key is a bootstrap credential that must work independently of any stateful system, including this API; default_admin_email and default_admin_password take effect only on first boot. Ongoing auth management happens through POST /v1/admin/users/{id}/superadmin, org invites/roles, SSO connections, and service accounts instead — see Authentication. |
jwt | Rotating the session-signing secret invalidates every existing session across every replica. (Session lifetime is a separate, covered section — see session below; only the signing secret itself is excluded here.) |
two_factor | Rotating the secret encryption key makes every already-enrolled user’s TOTP secret unreadable without a re-encryption step. |
secrets | Rotating the key that encrypts every stored secret makes all of them unreadable without a re-encryption step. |
mail | How this server reaches a mail server, including its password. Like storage, this is infrastructure and a secret. See Email. |
worker | The job worker loop starts with the process, before any stored override is read. See worker. |
network | Anyone who can add a trusted proxy can make any request claim any source address, which defeats every per-IP check at once — see network. |
github | Where GitHub’s REST API is. Every org’s GitHub App sends its credentials there, so no admin session may move it. See github. |
gitlab.ca_bundle | One field — gitlab.egress is editable. A path on the server’s own filesystem. See gitlab. |
rate_limit.enabled | One field, not a section — the rest of rate_limit is editable. Whether brute-force protection runs at all is the single change a stolen superadmin session would most want to make, and the one an operator couldn’t undo from inside a compromised deployment. |
deployment | Identifies the deployment this process belongs to: the operator’s cloud instance or a customer’s self-hosted one. It is not a business setting, and no authenticated administrator may change it. See deployment below. |
Excluded — fixed at the hardcoded default, not configurable by any means (not file, not env, not the admin API either):
| Section | Why |
|---|---|
telemetry | Read once, synchronously, inside create_app() itself — RequestSpanMiddleware’s enabled flag is constructed from it before the FastAPI app object even exists for an async database read, so no override could ever apply. (The TTL/retention duration for the spans it produces is a separate, covered section — see retention below and Data Retention; only the on/off switch itself is excluded here.) |
See Platform Admin — Settings for the full endpoint reference,
Platform Admin — Preparing MongoDB for the
POST /v1/admin/storage/prepare-mongodb action — opentremor-admin init-db as a
dashboard button.
Fields
Section titled “Fields”logging
Section titled “logging”In the dashboard: Platform Admin → System → General.
| Key | Default | Description |
|---|---|---|
level | info | Log verbosity: debug, info, warning, error |
Not set in this file — level above is the fixed baseline; change it live via
PATCH /v1/admin/settings (logging_level) — see Platform settings.
The log format is set by the LOG_FORMAT environment variable, not a key here. Error reporting is set
with the SENTRY_* environment variables, also not keys here. See
Logs and Troubleshooting.
storage
Section titled “storage”| Key | Default | Description |
|---|---|---|
mongodb.uri | — | Full MongoDB connection URI. Required; MONGODB_URI overrides it |
mongodb.database | — | Target database. Required |
| Key | Default | Description |
|---|---|---|
allow_origins | ["*"] | Allowed origins — restrict to known callers in production |
allow_credentials | true | Allow cookies / auth headers |
allow_methods | ["*"] | Allowed HTTP methods |
allow_headers | ["*"] | Allowed request headers |
| Key | Default | Description |
|---|---|---|
api_key | null | Bootstrap admin key. null disables authentication entirely |
default_admin_email | null | Human superadmin account, created once at startup if set |
default_admin_password | null | Password for default_admin_email (min. 8 characters — shorter values are silently skipped, not rejected) |
auth.api_key is the bootstrap key — it always resolves to owner of the default org (and platform superadmin — see Platform Admin) and is never stored in the database. Additional keys and human accounts are created at runtime (POST /v1/auth/keys, POST /v1/auth/register) and scoped to whichever org created them — see Authentication.
auth.default_admin_email/default_admin_password create a ready-to-use human login the first time the server starts with them set — idempotent (only acts if no user with that email exists yet, so it’s safe to leave in a config that’s applied on every restart). This is the declarative counterpart to opentremor-admin grant-superadmin: convenient for a fresh install where running a command against the database isn’t the point.
When auth is enabled, every endpoint except the health probes (GET /health, GET /health/ready) requires either:
X-API-Key: <key>or a session cookie / bearer token from POST /v1/auth/session.
registration
Section titled “registration”| Key | Default | Description |
|---|---|---|
allow_public_org_creation | true | Whether anyone can create a new organization unilaterally |
terms_version | unset | The version of your terms every new account must accept (1–32 chars) |
terms_url | unset | Where those terms are published (http(s)://) |
privacy_url | unset | Your privacy policy, linked beside the terms — optional |
require_verified_email | false | Refuse every org-scoped endpoint to a human session whose account hasn’t confirmed its email address — see Email. Leave off until mail.backend is smtp |
When set to false, two things 403 for everyone except a superadmin: POST /v1/auth/register with
org_name set (and no invite_token), and POST /v1/orgs (an already-logged-in user creating
an additional org). Two things are unaffected either way, since neither creates a new
organization: registering with neither org_name nor invite_token (an org-less account — see
Invitations), and registering with invite_token (joining an
existing org an invite grants access to). Use this to require an invitation for organization
creation on a publicly accessible instance without changing who can register an account.
Not set in this file — change it live via PATCH /v1/admin/settings
(registration_allow_public_org_creation), no restart — see
Platform settings above.
The dashboard hides what the setting forbids: with it false, the sign-up page drops the “create
an organization” choice and its org-name field, and the onboarding page an org-less account lands
on offers only the invite route. Both read the value from the public
GET /v1/auth/registration-options on load —
presentation only, with the two endpoints above still enforcing the setting.
Requiring your terms at sign-up
Section titled “Requiring your terms at sign-up”An operator that publishes terms for its service sets terms_version and terms_url (both, or
nothing happens). From then on, every self-service sign-up must accept that exact version:
- the sign-up page shows a required checkbox linking to
terms_url(andprivacy_url), which also gates the “Continue with …” buttons; POST /v1/auth/register— in every mode, invitations included — refuses a body whoseaccepted_terms_versionisn’t the current version (400), and a social-login sign-in that would create an account fails withoauth_error=terms_required;- the account records
terms_accepted_versionandterms_accepted_at.
Changing terms_version applies from the next sign-up: a form opened before the change is refused
and must be reloaded. Accounts that already exist are not asked again. Accounts that an
organization provisions through its own SSO connection or SCIM are never asked — they are that
organization’s users. OpenTremor ships no terms of its own. By default, sign-up asks for none. Set
all three live with PATCH /v1/admin/settings (registration_terms_version,
registration_terms_url, registration_privacy_url) or from Platform Admin → Security → Sign-up & Sessions.
social_login
Section titled “social_login”In the dashboard: Platform Admin → Security → Sign-in Providers.
Platform-wide Continue with Google / Microsoft on the login and register pages — one OAuth client per provider for the whole deployment. This is not an organization’s SSO connection, which always takes precedence for the email domains it claims. See Quick Start: Sign in with Google or Microsoft.
| Key | Default | Description |
|---|---|---|
enabled | false | Whether the platform offers social sign-in |
google_client_id | null | Google OAuth client ID |
google_client_secret | null | Google OAuth client secret (stored encrypted; never returned) |
microsoft_client_id | null | Microsoft OAuth client ID |
microsoft_client_secret | null | Microsoft OAuth client secret (stored encrypted; never returned) |
server
Section titled “server”In the dashboard: Platform Admin → System → General.
| Key | Default | Description |
|---|---|---|
public_base_url | null | Public URL of this deployment, used when constructing links in email and external callbacks |
network
Section titled “network”| Key | Default | Description |
|---|---|---|
trusted_proxies | [] | IPs or CIDRs of the proxies in front of the server: HAProxy, an ingress controller, the dashboard. Env: TRUSTED_PROXIES, comma-separated |
filter_enabled | true | Whether network access rules are enforced. Env: NETWORK_FILTER_ENABLED |
list_sources_dir | null | Directory used by file address lists. Env: NETWORK_LIST_SOURCES_DIR |
telemetry
Section titled “telemetry”Controls the built-in metrics and tracing system.
| Key | Default | Description |
|---|---|---|
enabled | true | Collect and expose telemetry spans |
When enabled, every HTTP request is recorded as a span, and enriched domain spans are recorded on ingest and analysis submission. Spans are queryable via GET /v1/metrics/* (org-admin only, org-scoped).
retention
Section titled “retention”In the dashboard: Platform Admin → System → Data Lifecycle.
TTL/purge policy for telemetry spans, the audit log, findings, and raw analyzed resource content.
Covered by PATCH /v1/admin/settings; see
Data Retention for the full policy this backs: why each field has the
lifecycle it does, how TTL-based and sweep-based fields differ in when they take effect, and the
severity/status tiering for findings.
| Key | Default | Bounds |
|---|---|---|
telemetry_days | 30 | 1–365 |
audit_days | 730 | 30–3650 |
finding_low_medium_days | 180 | 1–3650 |
finding_high_critical_days | 730 | 1–3650 |
resource_content_days | 90 | 1–3650 |
feedback_days | 730 | 1–3650 |
sweep_enabled | true | — |
sweep_interval_hours | 24 | 1–168 |
network_events_days | 7 | 1–90 |
telemetry_days/audit_days are pushed live onto the running MongoDB backend’s TTL indexes via
collMod the moment they’re PATCHed — no restart, no re-prepare. The other fields govern the
retention sweep (POST /v1/admin/retention/run), normally triggered by
OpenTremor-task-scheduler’s heartbeat rather than this endpoint’s
value alone.
In the dashboard: Platform Admin → System → Jobs.
Policy for background jobs: how many times a queued job is retried after its worker dies, and
the stuck-job sweep. The platform owns this section because job tracking is generic infrastructure,
not analysis-specific. Configure it with PATCH /v1/admin/settings.
See Platform Admin — Running a stuck-job sweep manually
for the full endpoint reference.
| Key | Default | Bounds |
|---|---|---|
stuck_timeout_minutes | 60 | 5–1440 |
sweep_enabled | true | — |
sweep_interval_hours | 1 | 1–168 |
max_attempts | 3 | 1–10 |
stuck_timeout_minutes is how long a job can go without a progress update (updated_at, stamped
on every status transition and progress report) before the sweep (POST /v1/admin/jobs/sweep)
presumes it is orphaned and marks it failed. Retry it afterward with POST /jobs/{job_id}/retry. sweep_enabled/sweep_interval_hours govern the sweep itself, normally
triggered by OpenTremor-task-scheduler’s heartbeat rather than by this
endpoint’s value alone, as with retention.
max_attempts is the maximum number of times a worker may claim a queued job. When a replica
dies mid-job, its claim’s lease expires, and the next worker to poll (or the sweep) returns the job
to the queue. After max_attempts claims, the job is marked failed instead. The sweep never
affects queued jobs waiting their turn, no matter how long the queue is.
worker
Section titled “worker”The job worker each replica runs to claim and process queued jobs, including background analysis and pull-request analysis. This section is file/env only because the loop starts with the process.
| Key | Default | Bounds |
|---|---|---|
enabled | true | — (env JOB_WORKER_ENABLED) |
concurrency | 4 | 1–64 |
poll_seconds | 2.0 | 0.01–60 |
lease_seconds | 300 | 30–3600 |
concurrency is how many jobs one replica runs at once. A job queued by a replica wakes that
replica’s worker at once; poll_seconds bounds how long a job queued elsewhere waits. A claim
lasts for lease_seconds and is renewed every third of that interval while the job runs. A dead
replica’s jobs are picked up again within roughly that time. Setting enabled: false on a replica
makes it serve requests only. At least one replica must run a worker, or queued jobs wait forever.
An analysis whose API key was passed inline with the request runs on the replica that accepted it,
not in the queue; no other replica can rebuild it.
analysis
Section titled “analysis”In the dashboard: Platform Admin → Analysis → Engine, and Platform Admin → Analysis → Agent
Injection for the injection_scan_* fields.
This section configures how the server-side analysis loop drives the LLM. The analysis engine owns
it outright; the platform does not. llm, below, covers access: whether the feature is on and what
key encrypts per-org credentials. This is generic infrastructure. Configure this section with
PATCH /v1/admin/settings (analysis_* fields), with no restart. These controls are useful while a
provider is misbehaving. See Architecture — the drain loop
for what each one bounds.
| Key | Default | Bounds | Description |
|---|---|---|---|
max_concurrent_units | 4 | 1–32 | Units analyzed in parallel within one run |
llm_timeout_seconds | 120.0 | 5–600 | Per-call deadline handed to the provider SDK |
llm_max_attempts | 3 | 1–6 | Total attempts per unit, not retries on top of one — 1 disables retrying |
llm_retry_backoff_seconds | 1.0 | 0.1–30 | Base delay for exponential backoff with full jitter |
llm_max_output_tokens | 4096 | 512–32000 | Ceiling on one unit’s structured response, handed to the provider SDK |
injection_scan_enabled | true | — | Run agent-injection detection on every change |
injection_scan_semantic | false | — | Whether organizations may turn on tier 2, the LLM scorer |
injection_scan_semantic_max_spans | 20 | 1–200 | Most pattern matches tier 2 scores in one change |
injection_scan_gate | "review" | off | review | fail | What an injection finding does to a pull request’s commit status, for an organization that has not chosen its own |
demo_preferred_packs | ["python-code-change", "terraform-plan"] | pack names | Whose sample the demo analysis loads: the first enabled one, else any enabled pack that ships a sample |
llm_max_output_tokens is a correctness bound, not a cost one — the organization’s
monthly LLM budget is what caps spend. It matters because
every provider truncates rather than errors when a response outgrows its cap: set it too low
and findings are silently lost off the end of a long analysis. The backends detect the overflow
and fail the unit with a message naming the cap, rather than reporting the half-written result as
a schema violation, so “raise this” is an obvious fix rather than a guess. The default holds a
unit with a handful of findings comfortably; a unit that reliably overflows it is usually one that
should have been split.
max_concurrent_units is a per-run bound: N concurrent analyze jobs can have N × this many
calls in flight. The organization’s monthly LLM budget is the
backstop against runaway spend, and the loop honors that budget per unit. Raising concurrency
beyond what your provider’s rate limit allows makes 429s more likely. They are retried, but retries
increase wall-clock time.
llm_timeout_seconds replaces the provider SDK’s default, which is much longer than a job’s useful
deadline. Anthropic’s default is 10 minutes. A timed-out call is treated as transient and retried,
not fatal.
The three injection_scan_* fields are free on every plan and in both deployment modes. The
deterministic tiers make no provider call, so leaving detection on costs a few milliseconds of
matching per changed file. It is neither metered nor counted against an organization’s demo quota.
injection_scan_semantic is the exception. It only allows organizations to turn on tier 2; each
organization turns it on in Organization → Features → Agent Injection and pays for it with its own LLM
connection and monthly budget. See
tier 2. By default,
injection_scan_gate is review, and an organization can choose its own. This holds a pull
request at pending rather than failing it. See the gate.
The system retries only transient failures: 408/409/429 and 5xx responses, plus timeouts and dropped connections. It fails the run on the first attempt for an invalid API key, rejected schema, or unparseable response, because retrying produces the same result.
feedback
Section titled “feedback”In the dashboard: Platform Admin → Analysis → Review Feedback.
What reviewer verdicts can change in later analyses. Configure it with PATCH /v1/admin/settings;
see Review Feedback for what each field protects against, and
Review Feedback Loop for the design.
| Key | Default | Bounds |
|---|---|---|
calibration_enabled | true | — |
min_samples | 3 | 1–100 |
max_entries_per_rule | 5 | 1–50 |
max_chars | 4000 | 200–40000 |
severity_ceiling | HIGH | CRITICAL/HIGH/MEDIUM/LOW |
trusted_only | true | — |
pr_comments_enabled | true | — |
command_prefix | @opentremor | 2–64 chars |
proposal_rejection_threshold | 0.6 | 0.0–1.0 |
proposal_disable_threshold | 0.9 | 0.0–1.0 |
proposal_confirm_threshold | 0.9 | 0.0–1.0 |
Capture has no switch because recording a triage decision is inert and always useful. Every field
above governs use: whether verdicts reach the analysis prompt, how many, and what they can never
change. severity_ceiling and min_samples help stop the loop from quietly suppressing a real
finding. Set trusted_only: false to let any commenter on a public pull request write into every
later prompt for the organization. Keep it enabled unless every repository is private.
knowledge
Section titled “knowledge”How rules from ADRs are read. Configure it with
PATCH /v1/admin/settings; a change applies to the next sync.
| Key | Default | Bounds |
|---|---|---|
sync_interval_hours | 24 | 1–720 |
max_files | 200 | 1–2000 |
max_file_bytes | 100000 | 1000–1000000 |
stale_after_minutes | 30 | 5–1440 |
sync_interval_hours is how old a repository’s last sync must be before the scheduler’s heartbeat
syncs it again; a push to the default branch syncs at once. max_files caps the files read per
repository and sync. A file over max_file_bytes is never sent to an LLM. A sync still running
after stale_after_minutes counts as dead, so the next one can start.
org_offboarding
Section titled “org_offboarding”In the dashboard: Platform Admin → System → Data Lifecycle.
The grace period between DELETE /v1/admin/organizations/{org_id} scheduling an organization’s
deletion and permanent deletion. Configure it with PATCH /v1/admin/settings; see
Platform Admin — Deleting an organization for
the full endpoint reference and details about what survives a purge.
| Key | Default | Bounds |
|---|---|---|
grace_period_days | 30 | 1–365 |
The system reads this value for each request. A change immediately applies to the computed
purge_after for any pending organization and to the next run of
POST /v1/admin/organizations/purge-pending.
| Key | Default | Description |
|---|---|---|
secret | random per-process | HS256 signing secret. Must be set explicitly (and shared across every replica) in any real deployment via JWT_SECRET — otherwise sessions won’t validate across pods, and every restart invalidates all logged-in sessions |
refresh_ttl_days | 14 | Reserved — refresh-token rotation isn’t implemented yet |
session
Section titled “session”Session lifetime is admin-editable; the signing secret remains file/env-only. See Platform settings above.
In the dashboard: Platform Admin → Security → Sign-up & Sessions.
Session token lifetime — kept separate from jwt so it can be platform-managed (live-editable via
PATCH /v1/admin/settings) without also exposing jwt.secret, whose rotation invalidates every
existing session across every replica.
Not set in this file or via env vars — change it live via PATCH /v1/admin/settings
(session_access_ttl_minutes), no restart — see
Platform settings above. Takes effect for newly
issued sessions only (login, register, session-switch); doesn’t retroactively extend a session a
user is already holding.
| Key | Default | Description |
|---|---|---|
access_ttl_minutes | 480 | Session token lifetime (1–1440) |
secrets
Section titled “secrets”| Key | Default | Description |
|---|---|---|
encryption_key | random per-process | File/env only, and never returned by the API. Encrypts every secret stored at rest (Fernet): SSO connection client secrets, notification channel URLs and signing secrets, Slack app client secrets, per-org LLM connection API keys and CA bundles, and the GitHub App private key and webhook secret. Same must-be-set-in-production rule as jwt.secret via SECRETS_ENCRYPTION_KEY — otherwise stored secrets become unreadable across restarts/replicas |
The key encrypts storage, not any particular feature — every stored secret, whichever half of the server keeps it, is encrypted under this one key.
branding
Section titled “branding”| Key | Default | Description |
|---|---|---|
product_name | OpenTremor | Admin-editable — Platform Admin → System → General, or PATCH /v1/admin/settings {"branding_product_name": "…"}. How the deployment names itself to people: the issuer an authenticator app lists a two-factor entry under, the name of a Slack app an organization creates, and the title of a test notification. An authenticator entry keeps the issuer it was enrolled with |
Model-provider access for the analysis engine: whether the deployment offers LLM-backed features,
and where an organization’s LLM connection may point. Per-org provider credentials are encrypted
under secrets.encryption_key.
Neither field is set in this file. A platform admin sets both live: enabled in Platform Admin
→ Analysis → Engine, egress in Platform Admin → Connections → LLM Endpoints, or either
through PATCH /v1/admin/settings — see
Platform settings above. Org admins cannot change
them.
{"llm_egress": {"enabled": true, "allow_private_networks": true, "allowed_hosts": ["llm.corp.example"]}}| Key | Default | Description |
|---|---|---|
enabled | true | Whether this deployment offers LLM-backed features |
egress.enabled | false | Whether a connection may name a custom base_url. false restricts every organization to the hosted providers’ own endpoints and makes provider_kind: "openai_compatible" unusable since it has no default address. Creating such a connection returns 400, and existing ones stop working |
egress.allow_private_networks | false | Whether a custom address may resolve into RFC1918/loopback/unique-local space. Needed for a model server in your own datacentre. Prefer pairing it with allowed_hosts |
egress.allowed_hosts | [] | Exact hostnames, or *.suffix patterns. Empty means “any host the address rules permit” — a restriction on where, not on who. *.corp.example matches llm.corp.example but not corp.example |
egress.allowed_lists | [] | Names of host address lists whose hosts are allowed too. Naming a list restricts the policy even while the list is empty: an empty list allows nothing |
Notification channels use their own notifications.egress policy.
Two rules hold whatever egress says, because no deployment ever means to permit them:
link-local is always blocked (169.254.0.0/16, fe80::/10 — cloud instance metadata), and
the resolved address is checked, not the hostname, since a policy that trusts the name is
defeated by any name whose A record points at 127.0.0.1. Every address a name resolves to must
pass, and the check runs again each time a connection is used — a stored row outlives its
validation. See LLM Providers and Connections.
With enabled: false, these return 501: POST /v1/{pack}/{changeset}/analyze,
POST /v1/{changeset}/analyze/auto and POST /v1/orgs/{org_id}/llm-connections. Listing and deleting stored connections deliberately keep
working, so an operator who turns the feature off can still see and clean up what organizations
left behind. Ingest, pack listing and the
client-led analysis workflow are unaffected — none of them call a provider.
notifications
Section titled “notifications”Outbound notification delivery — see Notifications for the
guide. The admin API excludes this entire section, unlike llm, which a platform admin
edits. Every field here is either a privilege boundary or a limit that protects the server rather
than the organization.
| Key | Default | Description |
|---|---|---|
egress | see below | File/env only. Where a notification channel may be pointed |
max_channels_per_org | 20 | Refused at create time with a 409. A soft ceiling on fan-out, not an entitlement — notifications are free on every deployment mode |
max_recipients_per_channel | 20 | Most members one email channel may mail, 1–200. Refused at create and update time with a 422. Each recipient is one message through the mail server |
timeout_seconds | 5.0 | Per-delivery HTTP timeout, 1.0–30.0. Deliveries never block a response, but they do hold a background task |
notifications.egress
Section titled “notifications.egress”Same EgressPolicy shape as llm.egress above — enabled,
allow_private_networks, allowed_hosts, allowed_lists — and the same two unconditional rules: link-local is
always blocked, and the resolved address is what gets checked. Only the defaults differ.
| Key | Default | Description |
|---|---|---|
enabled | true | false disables notification channels outright. Note this differs from llm.egress.enabled, which defaults to false: a notification channel is a customer-named address by definition, so false here is “the feature is off”, not “use the built-in endpoints” |
allow_private_networks | false | Set true on a self-hosted deployment notifying an internal Mattermost or webhook |
allowed_hosts | [] | Empty means any host the address rules permit |
allowed_lists | [] | Names of host address lists whose hosts are allowed too |
This is a separate policy from llm.egress. The two policies answer different
questions, and deployments routinely want opposite answers: a cloud instance ships
llm.egress.enabled: false — every org uses the hosted providers’ own endpoints —
while still needing to reach hooks.slack.com. Sharing one policy would couple “I run my own
model” to “I can send a finding to an address inside my network”.
A destination is checked twice: at save time, so an admin gets an explanatory 422 rather than
a channel that stores successfully but never delivers, and again on every delivery, because a
hostname that resolved to a permitted address when saved can resolve elsewhere later.
audit_push
Section titled “audit_push”Audit log streaming to a SIEM — see Audit Log Streaming for
the guide. Admins can edit the whole section, including egress, as with llm: a platform admin turns
a transport on and lets sinks reach a private SIEM without a redeploy. Org admins never reach it.
| Key | Default | Description |
|---|---|---|
https_enabled | true | Whether HTTPS sinks can be created and run. When turned off, existing HTTPS sinks pause and keep their place in the log |
syslog_enabled | false | Same for syslog sinks (RFC 5424 over TLS). Off by default: a syslog sink opens TCP connections to a host an admin chooses |
egress | see below | Where a sink may point, for both transports |
max_sinks_per_org | 3 | 1–20. Creation is refused with a 409. Platform sinks are not counted |
batch_size | 500 | Events per HTTPS request or syslog connection, 1–5000 |
audit_push.egress
Section titled “audit_push.egress”Same EgressPolicy shape and defaults as notifications.egress, and the
same unconditional rules. enabled is not read: the two transport switches above turn the feature
on and off. A sink’s destination is checked when saved and again before every send; a
syslog sink connects to the checked address.
two_factor
Section titled “two_factor”| Key | Default | Description |
|---|---|---|
secret_encryption_key | random per-process | Encrypts enrolled users’ TOTP secrets at rest (Fernet). Same must-be-set-in-production rule as jwt.secret and secrets.encryption_key via TWO_FACTOR_SECRET_KEY — otherwise every already-enrolled secret becomes unreadable across restarts/replicas |
File/env only, like the other two encryption keys — see the exclusion table in
Platform settings above. This is only the
encryption key: whether an org requires 2FA is per-org data
(PATCH /v1/admin/organizations/{org_id}/2fa-policy), not config. See
Two-factor authentication.
rate_limit
Section titled “rate_limit”Attempt budgets for endpoints that verify a credential.
This section is split: the five thresholds are admin-editable, while enabled is file/env only.
Change the thresholds at Platform Admin → Security → Rate Limits (or PATCH /v1/admin/settings).
They apply to the very next request, with no restart. Any values for them in a config file are
discarded at boot like those in every other admin-editable section. enabled works differently:
it is read from the file, never returned by GET /v1/admin/settings, and rejected by PATCH with
a 422.
The asymmetry is deliberate. Adjusting a threshold is an ordinary operational decision, and the
bounds below limit how loose it can get. Turning off all protection is the change a stolen
superadmin session would most want to make, and the change an operator couldn’t undo from inside
a compromised deployment. Requiring the config file also lets operators change it alongside
ingress rules, the other half of the same protection. The llm section is split in the opposite
direction: its toggle is safe to change live, while its egress policy is not.
| Key | Default | Editable | Description |
|---|---|---|---|
enabled | true | file/env only | Whether the application layer runs at all. Only sensible to turn off when something in front already does this (an API gateway, WAF, Cloudflare) — off means unlimited failed attempts |
login_max_attempts | 10 | ✅ | Failed logins per account (1–1000) before POST /v1/auth/session stops checking the password at all. Cleared by any successful login |
login_window_minutes | 15 | ✅ | The window that budget is measured over (1–1440) |
mfa_max_attempts | 5 | ✅ | Second-factor attempts per account (1–100), over a fixed 15-minute window. Counts correct codes too — a challenge ends either way. Cleared by a successful second factor |
ip_max_attempts | 60 | ✅ | Failed credential presentations per source IP (1–10000), across every credential type at once: login, API key, SCIM bearer token, invite and public-report link tokens |
ip_window_minutes | 15 | ✅ | The window for the per-IP budget (1–1440) |
Exceeding a budget returns 429 with a Retry-After header. The response to the attempt that
crosses a threshold is unchanged (a 401 stays a 401), so the API does not reveal where the
line sits. Only the next attempt is turned away.
Two budgets, keyed differently, on purpose. Per-account budgets stop a distributed password-spray attack from evading limits by rotating source addresses. The per-IP budget catches guessing against endpoints with no account to key the budget to. A success clears an account’s budget but never the IP’s. Many unrelated users can share an IP through a NAT or office egress, so letting a success reset the IP budget would give an attacker a free reset by authenticating to their own account.
github
Section titled “github”| Key | Default | Description |
|---|---|---|
api_base_url | https://api.github.com | Base URL of GitHub’s REST API. Core sends every org’s App calls there: App creation, installation tokens, pull request diffs, comments and statuses |
Leave it at the default. The end-to-end suite points it at a fake GitHub. Each organization still registers its own App (GitHub App).
gitlab
Section titled “gitlab”In the dashboard: Platform Admin → Connections → GitLab for egress.
Where an organization’s self-managed GitLab may be. The base URL is typed by an
org admin, so egress decides which hosts on this server’s network an org can make it call.
egress is not set in this file. A platform admin sets it live in the dashboard (Platform Admin
→ Connections → GitLab) or through PATCH /v1/admin/settings as one object, gitlab_egress — see
Platform settings above. Org admins cannot change it.
ca_bundle stays in the file. The organization chooses which CA to trust for a GitLab certificate
on its connection; ca_bundle is only the default for orgs that provide none.
{"gitlab_egress": {"enabled": true, "allow_private_networks": true, "allowed_hosts": ["gitlab.corp.example"]}}| Key | Default | Description |
|---|---|---|
egress.enabled | false | Whether the GitLab integration is offered at all. Connecting returns 400 while it is false, and existing connections stop working |
egress.allow_private_networks | false | Whether a GitLab URL may resolve into RFC1918/loopback/unique-local space — usually needed, since a self-managed GitLab tends to live on the company network. Prefer pairing it with allowed_hosts |
egress.allowed_hosts | [] | Exact hostnames, or *.suffix patterns. Empty means any host the address rules permit |
egress.allowed_lists | [] | Names of host address lists whose hosts are allowed too |
ca_bundle | null | Path to a PEM file of CAs a GitLab certificate may chain to — the default for orgs that store no CA on their own connection (useful when every org sits behind the same company CA). Replaces the system store for GitLab calls only. There is no setting that turns verification off |
The same two rules as llm.egress apply:
link-local is always blocked, and every resolved address is checked again each time a job
calls GitLab.
In the dashboard: Platform Admin → Connections → Jira.
Whether this deployment offers the Jira integration, and where an organization’s
Jira may be. Not set in this file: a platform admin sets it live, through the dashboard or
PATCH /v1/admin/settings with jira_enabled, jira_egress and jira_batch_size. Org admins
cannot change it.
{"jira_enabled": true, "jira_egress": {"allow_private_networks": true, "allowed_hosts": ["jira.corp.example"]}}| Key | Default | Description |
|---|---|---|
enabled | false | Whether orgs may connect Jira. Off pauses every org: nothing is sent to Jira, and connections, rules and links to issues are kept |
egress.allow_private_networks | false | Whether a Jira URL may resolve into RFC1918/loopback/unique-local space. Needed for a Data Center on the company network |
egress.allowed_hosts | [] | Exact hostnames, or *.suffix patterns. Empty means any host the address rules permit. Jira Cloud is public and needs nothing here |
egress.allowed_lists | [] | Names of host address lists whose hosts are allowed too |
batch_size | 50 | Findings handled per org on each sync tick (1–500), so a backfill cannot hit Jira’s rate limit in one burst |
Unlike gitlab, the switch is enabled, not egress.enabled: Jira Cloud is a public
host, so “is it offered” and “may it reach a private network” are separate questions.
egress.enabled is not consulted. Link-local is always blocked, and every resolved address is
checked again on each call.
deployment
Section titled “deployment”| Key | Default | Description |
|---|---|---|
mode | self_hosted | self_hosted or cloud |
File/env only (DEPLOYMENT_MODE) — never admin-API-editable, even though nothing
structurally prevents it the way telemetry is prevented. It identifies which
deployment this process is, not a business setting an authenticated admin should
ever flip live.
self_hosted(the default — every OSS/quickstart/Helm config leaves this unset) — every org is unconditionally entitled to run every pack, regardless ofplan_tier/trial_usage.cloud(set only on the operator’s own SaaS config) — an org needs a paying plan, or is still within its one-time, lifetime 100-analysis free trial. See Billing / quota enforcement for the full mechanism (controllers/services/billing/entitlements.pyin OpenTremor-platform).