Reference

Configuration

Two files decide how Prometheus behaves: a YAML file for settings and a separate env file for secrets. The split is deliberate, and the rule that follows from it is the only one you have to remember — nothing secret ever belongs in the YAML.

Where the config is found

Prometheus looks in a fixed order and takes the first hit. This is quoted from the shipped template itself, so it cannot drift from the search the code actually performs:

oara config --show-defaults | head -14
# Prometheus configuration — reference defaults
# Copy to config/prometheus.yaml and customize (or run `prometheus setup`).
# config/prometheus.yaml is gitignored — your secrets stay local.
#
# CONFIG SEARCH ORDER (first hit wins):
#   1. an explicit --config path
#   2. config/prometheus.yaml          — repo-local (checkout installs)
#   3. $PROMETHEUS_CONFIG_DIR/prometheus.yaml
#      (default ~/.prometheus/prometheus.yaml — pip installs; this is
#       what `prometheus setup --fast` writes)
#
# SECRETS never belong in this file — put them in the env file the daemon
# and the systemd unit both load: ~/.config/prometheus/env
# (PROMETHEUS_API_TOKEN, PROMETHEUS_TELEGRAM_TOKEN, ANTHROPIC_API_KEY, …).

If you installed with uv tool install or pip — which is almost everyone — yours is ~/.prometheus/prometheus.yaml, and entry 2 never applies. The repo-local path exists for people running from a checkout, and it wins over your home directory when both are present. That is the one surprise in the list: a checkout you forgot you were standing in will quietly take precedence.

Secrets go in the env file

~/.config/prometheus/env is a plain KEY=value file, mode 0600. Both the daemon and the systemd unit load it, which is why it is the env file and not your shell profile — a service started at boot never sees your shell.

The YAML does have a model.api_key field that accepts a key inline, and the template documents it while telling you not to use it. The reasoning is worth repeating, because it is the reason the split exists: a prometheus.yaml gets copied between machines and pasted into issues. An undocumented key that works is worse than a documented one you are told to avoid.

Reading the defaults

There are 46 top-level sections. Rather than reproduce them here — where they would start going stale the day this page was written — read them from the binary you have installed:

oara config --show-defaults > reference.yaml
grep -n '^[a-z_]*:' reference.yaml
16:system:
21:bootstrap:
25:model:
135:compaction:
153:checkpoints:
…
1170:vault:
1184:doctor:
1189:tasks:
1197:heartbeat:
1216:documents:
1224:escalation:

It is worth actually reading rather than grepping. The comments carry the reasons — several of them record the incident that produced the setting, including dates. That is the closest thing to a design rationale the project has.

The handful you are likely to change

Defaults below are the shipped values, read from the template.

What actually constrains the agent, in order

This is the part worth reading slowly, because the setting with the most reassuring name is the weakest of the three and none of the first two covers bash. The template states all of this in its own comments; it is collected here because it is spread across a hundred and fifty lines and the order matters.

oara doctor reports both floors and their live state, including ! Bash write floor: mode 'auto' but UNAVAILABLE when bwrap is missing. If you are about to expose this daemon to anything, that line is the one to read first — and Tokens and the open web API is the other half of the question.

Credit where it is due: the required setting for the read floor refuses to run bash at all if the AppArmor profile is missing or the transition does not happen, rather than silently falling back to an unconfined shell. Being handed a weaker sandbox than you asked for is the failure you would not notice, and it is refused by design in several places here — coding.sandbox_type raises for the same reason.

Where everything else lives

Two commands wipe things deliberately and are worth knowing before you need them: oara --reset-telemetry deletes telemetry.db and exits, and oara --reset-data deletes all user data — telemetry, memory, LCM, audit, evals, wiki, sentinel and generated skills. Neither asks twice.