Skip to content
DashboardWebsite

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.


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 below

That’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):

SectionWhy
storageThe MongoDB connection string cannot be stored in the database it points to.
corsThese settings are security-critical. Changing them from an authenticated session must not be possible.
authapi_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.
jwtRotating 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_factorRotating the secret encryption key makes every already-enrolled user’s TOTP secret unreadable without a re-encryption step.
secretsRotating the key that encrypts every stored secret makes all of them unreadable without a re-encryption step.
mailHow this server reaches a mail server, including its password. Like storage, this is infrastructure and a secret. See Email.
workerThe job worker loop starts with the process, before any stored override is read. See worker.
networkAnyone who can add a trusted proxy can make any request claim any source address, which defeats every per-IP check at once — see network.
githubWhere 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_bundleOne field — gitlab.egress is editable. A path on the server’s own filesystem. See gitlab.
rate_limit.enabledOne 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.
deploymentIdentifies 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):

SectionWhy
telemetryRead 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.


In the dashboard: Platform Admin → System → General.

KeyDefaultDescription
levelinfoLog 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.

KeyDefaultDescription
mongodb.uri—Full MongoDB connection URI. Required; MONGODB_URI overrides it
mongodb.database—Target database. Required
KeyDefaultDescription
allow_origins["*"]Allowed origins — restrict to known callers in production
allow_credentialstrueAllow cookies / auth headers
allow_methods["*"]Allowed HTTP methods
allow_headers["*"]Allowed request headers
KeyDefaultDescription
api_keynullBootstrap admin key. null disables authentication entirely
default_admin_emailnullHuman superadmin account, created once at startup if set
default_admin_passwordnullPassword 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.

KeyDefaultDescription
allow_public_org_creationtrueWhether anyone can create a new organization unilaterally
terms_versionunsetThe version of your terms every new account must accept (1–32 chars)
terms_urlunsetWhere those terms are published (http(s)://)
privacy_urlunsetYour privacy policy, linked beside the terms — optional
require_verified_emailfalseRefuse 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.

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 (and privacy_url), which also gates the “Continue with …” buttons;
  • POST /v1/auth/register — in every mode, invitations included — refuses a body whose accepted_terms_version isn’t the current version (400), and a social-login sign-in that would create an account fails with oauth_error=terms_required;
  • the account records terms_accepted_version and terms_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.

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.

KeyDefaultDescription
enabledfalseWhether the platform offers social sign-in
google_client_idnullGoogle OAuth client ID
google_client_secretnullGoogle OAuth client secret (stored encrypted; never returned)
microsoft_client_idnullMicrosoft OAuth client ID
microsoft_client_secretnullMicrosoft OAuth client secret (stored encrypted; never returned)

In the dashboard: Platform Admin → System → General.

KeyDefaultDescription
public_base_urlnullPublic URL of this deployment, used when constructing links in email and external callbacks
KeyDefaultDescription
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_enabledtrueWhether network access rules are enforced. Env: NETWORK_FILTER_ENABLED
list_sources_dirnullDirectory used by file address lists. Env: NETWORK_LIST_SOURCES_DIR

Controls the built-in metrics and tracing system.

KeyDefaultDescription
enabledtrueCollect 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).

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.

KeyDefaultBounds
telemetry_days301–365
audit_days73030–3650
finding_low_medium_days1801–3650
finding_high_critical_days7301–3650
resource_content_days901–3650
feedback_days7301–3650
sweep_enabledtrue—
sweep_interval_hours241–168
network_events_days71–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.

KeyDefaultBounds
stuck_timeout_minutes605–1440
sweep_enabledtrue—
sweep_interval_hours11–168
max_attempts31–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.

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.

KeyDefaultBounds
enabledtrue— (env JOB_WORKER_ENABLED)
concurrency41–64
poll_seconds2.00.01–60
lease_seconds30030–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.

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.

KeyDefaultBoundsDescription
max_concurrent_units41–32Units analyzed in parallel within one run
llm_timeout_seconds120.05–600Per-call deadline handed to the provider SDK
llm_max_attempts31–6Total attempts per unit, not retries on top of one — 1 disables retrying
llm_retry_backoff_seconds1.00.1–30Base delay for exponential backoff with full jitter
llm_max_output_tokens4096512–32000Ceiling on one unit’s structured response, handed to the provider SDK
injection_scan_enabledtrue—Run agent-injection detection on every change
injection_scan_semanticfalse—Whether organizations may turn on tier 2, the LLM scorer
injection_scan_semantic_max_spans201–200Most pattern matches tier 2 scores in one change
injection_scan_gate"review"off | review | failWhat 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 namesWhose 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.

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.

KeyDefaultBounds
calibration_enabledtrue—
min_samples31–100
max_entries_per_rule51–50
max_chars4000200–40000
severity_ceilingHIGHCRITICAL/HIGH/MEDIUM/LOW
trusted_onlytrue—
pr_comments_enabledtrue—
command_prefix@opentremor2–64 chars
proposal_rejection_threshold0.60.0–1.0
proposal_disable_threshold0.90.0–1.0
proposal_confirm_threshold0.90.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.

How rules from ADRs are read. Configure it with PATCH /v1/admin/settings; a change applies to the next sync.

KeyDefaultBounds
sync_interval_hours241–720
max_files2001–2000
max_file_bytes1000001000–1000000
stale_after_minutes305–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.

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.

KeyDefaultBounds
grace_period_days301–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.

KeyDefaultDescription
secretrandom per-processHS256 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_days14Reserved — refresh-token rotation isn’t implemented yet

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.

KeyDefaultDescription
access_ttl_minutes480Session token lifetime (1–1440)
KeyDefaultDescription
encryption_keyrandom per-processFile/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.

KeyDefaultDescription
product_nameOpenTremorAdmin-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.

PATCH /v1/admin/settings
{"llm_egress": {"enabled": true, "allow_private_networks": true, "allowed_hosts": ["llm.corp.example"]}}
KeyDefaultDescription
enabledtrueWhether this deployment offers LLM-backed features
egress.enabledfalseWhether 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_networksfalseWhether 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.

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.

KeyDefaultDescription
egresssee belowFile/env only. Where a notification channel may be pointed
max_channels_per_org20Refused 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_channel20Most 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_seconds5.0Per-delivery HTTP timeout, 1.0–30.0. Deliveries never block a response, but they do hold a background task

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.

KeyDefaultDescription
enabledtruefalse 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_networksfalseSet 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 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.

KeyDefaultDescription
https_enabledtrueWhether HTTPS sinks can be created and run. When turned off, existing HTTPS sinks pause and keep their place in the log
syslog_enabledfalseSame for syslog sinks (RFC 5424 over TLS). Off by default: a syslog sink opens TCP connections to a host an admin chooses
egresssee belowWhere a sink may point, for both transports
max_sinks_per_org31–20. Creation is refused with a 409. Platform sinks are not counted
batch_size500Events per HTTPS request or syslog connection, 1–5000

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.

KeyDefaultDescription
secret_encryption_keyrandom per-processEncrypts 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.

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.

KeyDefaultEditableDescription
enabledtruefile/env onlyWhether 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_attempts10✅Failed logins per account (1–1000) before POST /v1/auth/session stops checking the password at all. Cleared by any successful login
login_window_minutes15✅The window that budget is measured over (1–1440)
mfa_max_attempts5✅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_attempts60✅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_minutes15✅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.

KeyDefaultDescription
api_base_urlhttps://api.github.comBase 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).

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.

PATCH /v1/admin/settings
{"gitlab_egress": {"enabled": true, "allow_private_networks": true, "allowed_hosts": ["gitlab.corp.example"]}}
KeyDefaultDescription
egress.enabledfalseWhether the GitLab integration is offered at all. Connecting returns 400 while it is false, and existing connections stop working
egress.allow_private_networksfalseWhether 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_bundlenullPath 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.

PATCH /v1/admin/settings
{"jira_enabled": true, "jira_egress": {"allow_private_networks": true, "allowed_hosts": ["jira.corp.example"]}}
KeyDefaultDescription
enabledfalseWhether 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_networksfalseWhether 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_size50Findings 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.

KeyDefaultDescription
modeself_hostedself_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 of plan_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.py in OpenTremor-platform).