Skip to content

Configuration

Opsmith has two layers of configuration:

Layer Set by Where Examples
Process settings The operator OPSMITH_* environment variables Database, sandbox, data directory
Project configuration Tenant admins A TOML file, the API, or the UI Repositories, connectors, intervals, budgets, protected paths

This page covers project configuration. Process settings are listed in Deployment.

The configuration file

Describe your projects in one TOML file and apply it. Applying is safe to repeat: records are matched by name and updated in place.

Project settings are the exception. Applying replaces them with the file's [projects.settings], and anything the file leaves out goes back to its default, so settings changed in the UI or through the API since the last apply are lost, checks included. Keep the file as the one place you change settings, or copy UI changes into it first.

opsmith apply opsmith.toml --tenant acme

A minimal file:

[[projects]]
name = "payments"

[[projects.repositories]]
name = "payments-api"
scm_provider = "github"
url = "https://github.com/acme/payments-api.git"
full_name = "acme/payments-api"
credentials_ref = "env:GITHUB_TOKEN"     # a reference, never the secret itself
test_command = "pytest -q"

[[projects.services]]
name = "payments-api"
repository = "payments-api"
path_prefixes = ["app/"]

[[projects.connectors]]
name = "loki"
type = "loki"
service = "payments-api"
config = { url = "http://loki:3100", query = '{service_name="payments-api"}' }

opsmith.example.toml is a complete, annotated example.

If anything in the file is invalid, opsmith apply prints what is wrong and writes nothing. Unknown keys are errors, at every level, so a misspelt key or table ([projects.setings]) cannot be silently ignored.

Nothing removes records: deleting an entry from the file does not delete it from Opsmith. Disable a connector with enabled = false instead.

Projects and settings

A project groups repositories, services and connectors that belong together, and carries the settings below. All are optional; the defaults are shown.

The examples on this page each start with [projects.settings]. A project may declare that header only once, so put the keys of several examples under a single [projects.settings]; tables such as [projects.settings.budgets] and [[projects.settings.checks]] follow it.

[projects.settings]
inference_interval_hours = 6        # how often each service is analyzed
lead_max_carry = 3                  # runs a lead may stay undecided before it is escalated
audit_cron = "0 2 * * *"            # when repositories are audited (UTC)
audit_full_every_days = 7           # a full audit at least this often; changed files only in between
ingest_interval_seconds = 900       # given to a connector without interval_seconds when it is created or applied
pr_poll_seconds = 600               # how often open pull requests are checked
recently_closed_days = 14           # suppress findings matching a task merged or closed this recently
min_task_confidence = 0.3           # findings below this do not become tasks
max_tasks_per_aggregation = 25      # the rest wait for the next aggregation
auto_submit_for_review = true       # false leaves new tasks in "proposed"; nothing submits them later
post_merge_verification = true      # watch the signal after a merge
verification_delay_hours = 6        # how long to wait after the merge before judging
executor_agent = "heuristic"        # or "claude" or "openai"; see Models
osv_online = false                  # look up dependency vulnerabilities at osv.dev
Setting Allowed values
inference_interval_hours Greater than 0, at most 8760 (a year)
lead_max_carry 1 to 100
audit_full_every_days 1 to 3650
max_tasks_per_aggregation 1 to 1000
audit_cron Five fields: minute, hour, day of month, month, day of week. Lists, ranges and steps are supported; names such as MON are not. An expression that can never fire (31 February) is rejected. A step restarts each day, so */7 in the hour field also fires at midnight, three hours after 21:00
ingest_interval_seconds 60 to 31536000 (a year)
pr_poll_seconds 60 to 604800 (a week)
recently_closed_days 0 to 3650
verification_delay_hours 0 to 8760
budgets.* Token, time and count caps are positive; cost caps may be 0, which stops every stage, the offline rules included. At most 10^8 tokens, $100,000 per run, $1,000,000 per day, 86400 execution seconds, 1000 agent iterations, 100 concurrent executions
min_task_confidence 0 to 1

Values are checked when you save them. A bad value is refused with a message; it cannot be stored and fail later inside a job.

Names are the exception, because they are not compared with what exists. A misspelt executor_agent or stage provider fails the run that uses it, and a misspelt stage name under llm.stages (stages.checks) is ignored, so that stage uses llm.default. The stage names are inference, audit_triage, check, task and executor.

A connector keeps the interval it was given. Changing ingest_interval_seconds in the UI or the API later does not change existing connectors: apply the file again, or set the schedule (Schedules).

osv_online = true sends the names and versions of your dependencies to api.osv.dev. Leave it off if that must not leave your network.

checks holds the project's checks: standing instructions a model carries out against the code on a schedule, such as a weekly security review. See Checks.

Repositories

[[projects.repositories]]
name = "payments-api"
scm_provider = "github"               # "github" or "local"
url = "https://github.com/acme/payments-api.git"
full_name = "acme/payments-api"       # owner/repo; derived from the URL when omitted
default_branch = "main"
credentials_ref = "env:GITHUB_TOKEN"
build_command = "python -m compileall -q app"
lint_command = "ruff check ."
test_command = "pytest -q"
audit_types = ["security", "bugs", "dependency", "compliance", "performance"]
Key Meaning
scm_provider github, or local for a git repository on the worker's disk (development and the demo). A local repository's url is a path and must be inside OPSMITH_LOCAL_ROOT. Left out in a file it is local, through the API github, so always set it
url For github: an https:// clone URL, without credentials in it. Nothing else is accepted (no path, file://, ssh:// or http://), because the value is handed to git on the worker
default_branch A plain branch name: letters, digits, ., _, - and /, starting with a letter or digit, at most 100 characters
credentials_ref Where the token comes from. See Credentials and the token permissions
build_command, lint_command, test_command The repository's own build, lint and test commands. Each is optional. They run only inside the sandbox, where there is no network: they must work with what the sandbox image already contains. Do not put pip install or npm ci in them
audit_types Which audits run: security, bugs, compliance, performance, dependency, coverage. The default is every type except coverage

The agent runs these checks while it works, and Opsmith runs them again itself before it opens a pull request. A pull request is only opened when every configured check passes. A repository with no checks configured gets pull requests that nothing verified, so configure at least test_command.

Services

A service is a running thing that emits signals. Mapping it to a repository is what lets Opsmith connect a production symptom to code.

[[projects.services]]
name = "payments-api"
environment = "production"            # default
repository = "payments-api"           # the repository it is built from
owner = "team-payments"
path_prefixes = ["app/"]              # the parts of the repository this service owns
inference_interval_hours = 1          # overrides the project's interval for this service

A signal that names a service Opsmith has not seen creates that service automatically, with its own analysis schedule. Map it to a repository afterwards to get code-level correlation.

Connectors

A connector is a source of signals. Each belongs to a project and usually to a service.

[[projects.connectors]]
name = "loki"
type = "loki"                         # loki | victorialogs | prometheus | file_logs | file_metrics | push_logs | push_metrics
service = "payments-api"              # default service for records that do not name one
service_environment = "production"    # which "payments-api", when it exists in several environments
interval_seconds = 900                # at least 60; left out, the project's ingest_interval_seconds
credentials_ref = "env:LOKI_TOKEN"    # optional; sent as a Bearer token
enabled = true
config = { url = "http://loki:3100", query = '{service_name="payments-api"}' }

Common behaviour of the pull connectors:

  • Each run reads from where the last one stopped up to 60 seconds before now (lag_seconds in config), so records that arrive slightly late are not skipped.
  • After an outage a run catches up at most 24 hours at a time and continues on the next run.
  • A record that cannot be parsed is skipped and counted in the job result. It does not stop the rest. The same goes for a record that cannot be stored: a service or environment name that is too long or holds a NUL, a metric value that is not finite or is beyond 1e150, or attributes nested more than 255 levels deep.
  • Very long messages are truncated to 16 KiB and marked as truncated. A NUL or half a surrogate pair in a text is replaced by U+FFFD.
  • A record without an environment gets the connector's environment (in config). When that is not set and the connector is linked to a service, it gets that service's.
  • The connector's HTTP client is closed after every run.

loki

config key Default Meaning
url required Base URL of Loki
query required LogQL selector
limit 5000 Entries per page. Results are paged, up to 20 pages per run; a window with more than that is continued on the next run rather than cut off
service_label service_name The stream label that names the service
environment the linked service's, else production Environment for streams without an env or environment label
timeout 30 Seconds for each read, at most 120. A whole request may take four times as long
lag_seconds 60 See above

A line that is JSON is read for its level, message and other fields.

prometheus

config key Default Meaning
url required Base URL of Prometheus
queries required A list of { name = "...", promql = "..." }. name becomes the metric name
step 60s Query resolution
baseline_seconds 21600 How far back to read for the baseline each run, at most 30 days
service_label service The label that names the service
environment the linked service's, else production Environment of the metrics this connector reads
timeout, lag_seconds 30, 60 As above

Name metrics so that the direction is clear. Names containing words like error, latency or duration are treated as "higher is worse"; success, availability or throughput as "lower is worse".

file_logs and file_metrics

Read files on the worker. For development, tests and simple setups. The path must be inside OPSMITH_LOCAL_ROOT; with that variable unset, these connectors are disabled.

config key Default Meaning
path required A file or glob, for example /var/log/app/*.jsonl. It may not contain ..
format (logs) jsonl jsonl, or text for plain lines
timestamp_field, message_field, severity_field, service_field (logs, jsonl) timestamp, message, level, service Field names in your JSON
pattern (logs, text) timestamp LEVEL [service] message A regular expression with named groups. timestamp is required; severity, service and message are optional
environment the linked service's, else production Environment for records that do not carry one
baseline_seconds (metrics) 21600 Look-back for the baseline, at most 30 days

Metric files are JSON lines with timestamp, name, value and optionally service and labels. A record without a timestamp is skipped and counted.

victorialogs

Reads VictoriaLogs through its LogsQL query API (/select/logsql/query), read-only.

config key Default Meaning
url required Base URL of VictoriaLogs, for example http://victorialogs:9428
query * (everything) A LogsQL filter, for example app_name:(backend OR caddy). Opsmith adds the time window and the ordering itself
service_field app_name The field that names the service. app_name is the syslog tag, which Docker's syslog driver sets to the container or compose service name
limit 5000 Entries per page; up to 20 pages per run, the rest on the next run
environment the linked service's, else production Environment for entries without an environment field
timeout, lag_seconds 30, 60 As above

The level of each entry is, in order: the level of a JSON message; a level word such as ERROR:, WARN, FATAL or nginx's [notice] near the start of a text message; the entry's own level field. Docker's syslog driver marks everything a container writes to stderr as an error, so the level the message states is the more accurate one.

push_logs and push_metrics

For sources that send data to Opsmith instead of being polled: a log shipper, an OpenTelemetry pipeline, a script. They take no config.

[[projects.connectors]]
name = "collector"
type = "push_logs"
service = "payments-api"

Records are sent to POST /api/v1/connectors/{id}/push with a service key; see API. The other connector types accept pushed records as well. A pushed record without environment is filed under production, whatever the connector's service; send environment with each record for any other.

Where connectors may connect

Connector URLs must be plain http:// or https:// URLs without credentials, query string or fragment. Addresses in the link-local range, which includes cloud metadata endpoints, are refused. Private addresses are allowed, because that is where Loki and Prometheus normally run.

Protected paths

Protected paths decide which changes need more than a normal approval.

[projects.settings]
protected_paths = [
  { pattern = ".github/**", mode = "elevated" },
  { pattern = "**/auth/**", mode = "elevated" },
  { pattern = "**/*.pem",   mode = "excluded" },
]
Mode Effect
elevated Only an admin can approve, and must tick an explicit acknowledgement
excluded Opsmith never changes these. A task that needs to cannot be approved; handle it by hand

The three rules above are the defaults. Setting protected_paths replaces them, so include the ones you want to keep.

Patterns are shell-style globs matched against the path from the repository root; * also matches /. A leading **/ also matches at the root. A pattern also covers everything below a directory it names, and a leading / or ./ is ignored: infra, infra/, /infra/** and infra/** all protect the infra directory. A pattern that could never match (empty, or containing ..) is refused when you save it.

The rules are applied twice: to the paths a task names when it is created or edited, and to the files the agent actually changed. The second check is the one that counts: a task that did not mention CI configuration cannot produce a pull request that touches it without an elevated approval.

Budgets

[projects.settings.budgets]
max_tokens_per_run = 400000         # one analysis run, audit triage or execution
max_cost_per_run_usd = 5.0
max_cost_per_day_usd = 50.0         # the whole project, per UTC day
max_execution_seconds = 1800        # one execution attempt
max_agent_iterations = 8            # how long the coding agent may keep trying
max_concurrent_executions = 2       # executions running at once in this project

The caps cover every stage that calls a model, including the coding agent.

When a cap is reached the stage stops, the run is recorded as budget_exceeded, and a budget.exceeded notification is sent. An execution that would start with the day's budget already spent is refused and its task returns to review; a coding agent that reaches a cap mid-run stops there. Calls that fail, are refused or are cut off still count against the caps. Before each model call Opsmith reserves the worst case (the prompt plus the full output allowance), so set max_tokens_per_run comfortably above the stage's max_tokens. The coding agent checks the caps between its turns instead, so its last turn can go over them by one call; the claude agent allows up to 32,000 output tokens per turn.

Models

Which model each stage uses is part of the project settings (executor_agent and [projects.settings.llm]). It has its own page, with the provider options, per-stage examples, prices and what a model must support: Models.

Policy rules and licenses

Your own rules, checked by the compliance audit:

[[projects.settings.policy_rules]]
id = "no-print"
description = "Use the logger, not print()"
path_glob = "app/**/*.py"
forbid_regex = 'print\('
severity = "low"

[[projects.settings.policy_rules]]
id = "license-header"
description = "Every source file carries the license header"
path_glob = "**/*.py"
require_regex = "SPDX-License-Identifier"
severity = "info"

forbid_regex reports each line that matches; require_regex reports each file where nothing matches. Severity is one of info, low, medium, high, critical.

[projects.settings]
license_allowlist = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC"]

Regular expressions you supply here are trusted. Avoid nested quantifiers such as (a+)+: a pathological expression can stall a worker.

Notifications

[projects.settings]
notifications = [
  { type = "log" },
  { type = "webhook", url = "https://hooks.slack.com/services/...", events = ["task.*", "job.dead"] },
]

A webhook receives {"text": "...", "event": "..."}, which Slack-compatible endpoints accept. events are glob patterns; the default is everything.

Event When
task.in_review A new task is waiting for review
task.reproposed A rejected task came back because the evidence materially changed
task.pr_open A pull request was opened
task.execution_failed An execution failed or was refused; the task is back in review
task.ci_failed CI failed on an Opsmith pull request
task.regressed The problem came back after the merge
lead.escalated A lead stayed undecided for too long
inference.failed An analysis run failed (the model call failed or its output was unusable)
check.failed A check run failed or did nothing (no model can follow it, or no file matches)
budget.exceeded A cost or token cap stopped a stage
job.dead A job used up its retries

Delivery is a queued job: a failed delivery is retried, then dead-lettered.

Redaction

Opsmith redacts common secrets and personal data on its own: private keys, cloud and API tokens, Authorization and Cookie headers, credentials in URLs, password=-style assignments (also inside JSON carried in a string), values of sensitive-looking keys, email addresses, card numbers, phone numbers and IP addresses. Add patterns for formats specific to you:

[projects.settings]
redaction_extra_patterns = ['ACME-[0-9]{8}', 'session=[A-Za-z0-9]+']

Each match is replaced by a marker such as [REDACTED:custom_0]. Patterns are validated when saved: each must be a valid regular expression that matches at least one character. See the limits of pattern-based redaction in Security.

Credentials

Configuration never contains a secret, only a reference to one:

Form Resolves to Restrictions
env:NAME The worker's environment variable NAME NAME may not start with OPSMITH_, and may not be POSTGRES_PASSWORD, PGPASSWORD, DATABASE_URL or the variable holding a model provider's API key (ANTHROPIC_API_KEY, OPENAI_API_KEY by default)
file:/path/to/secret The contents of that file, trimmed The file must be inside OPSMITH_SECRETS_DIR (default /run/secrets), and may not be the file holding a model provider's API key

The restrictions exist because the secret is sent to a URL chosen in the same configuration. Give each integration its own variable or file.

Schedules

Opsmith creates schedules from the settings above: one per connector (ingest), per service (analysis), per repository (audit), per enabled check and repository it covers (check), and per project (pull request tracking). You normally change them by changing the settings.

To set one schedule's timing directly, or to pause it, use the API. Find the schedule's id with GET /api/v1/projects/{id}/schedules; the Configuration page does not show it. Here $OPSMITH is Opsmith's address, such as http://127.0.0.1:8000, and $KEY an admin key:

curl -X PATCH $OPSMITH/api/v1/schedules/$SCHEDULE_ID -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"cron": "0 4 * * 1"}'      # or {"interval_seconds": 3600}, {"enabled": false}

Timing set this way is kept when project settings change later. To run a stage once, right now, use POST /api/v1/projects/{id}/trigger (API).

Settings can also be edited as JSON in the UI under Configuration (admins only). The UI replaces the whole settings object. PATCH /api/v1/projects/{id}/settings replaces only the top-level keys you send, each as a whole: {"settings": {"budgets": {"max_cost_per_day_usd": 10}}} resets the other budgets to their defaults, so send the complete budgets object.