Get started

Verify it works

oara doctor reports what is true about this machine right now. It is the fastest way to find out whether a problem is your config, your server, your model or your box — and it is worth running before you have a problem.

Known annoyance doctor currently prints about twenty-five lines of tool-registration logging before the report. Scroll past it — the report starts at the line that reads oara doctor. This will be quieted; the note goes away when it is.

Reading it

Four sections, four states. The state markers matter more than the text:

Mark	Means	Do
✓	Checked, and fine.	Nothing.
✗	Broken. Prometheus will not work correctly like this.	Fix it. Every ✗ carries a `fix:` line.
!	Working, but not the way you probably intend.	Read it once and decide on purpose.
·	Not enabled, so not checked.	Nothing, unless you expected it on.

The last line is the summary. RESULT: OK with 4 warning(s) means it will run. RESULT: 3 error(s), 3 warning(s) means it will not.

Before setup

Run it immediately after installing and it tells you the truth: there is nothing here yet.

oara doctorfresh install

oara doctor

Platform:
  ✗ Config: no prometheus.yaml found
      (searched: …/config/prometheus.yaml, ~/.prometheus/prometheus.yaml)
      fix: Run `oara setup` to create one.
  ✓ Data dirs: writable (~/.prometheus)

Connectivity:
  ✗ Inference: llama_cpp not responding at http://localhost:8080
      fix: Start the inference server (or fix model.base_url), then re-run `oara doctor`.
  ! Web: web.enabled is false — Beacon/REST API is OFF

Model:
  ✗ Model: no model detected (server unreachable)

…
RESULT: 3 error(s), 3 warning(s)

Three errors, and the first one explains the other two. That is the normal shape: fix the topmost ✗ and re-run rather than working down the list.

After setup

Same machine, same command, after oara setup found a llama.cpp server on 8080. This is the full report — nothing trimmed.

oara doctorconfigured

oara doctor

Platform:
  ✓ Config: loaded ~/.prometheus/prometheus.yaml
  ✓ Data dirs: writable (~/.prometheus)
  · Bash read floor: mode 'off' — bash may read ~/.ssh, ~/.gnupg and credential env
      files; the denied_paths list covers the path-declaring tools only
  ! Bash write floor: mode 'auto' but UNAVAILABLE — bwrap (bubblewrap) is not
      installed. bash is running WITHOUT this floor.
      fix: Install bubblewrap (sudo apt install bubblewrap) — or set
           security.bash_write_confinement: off to run without it knowingly.
  ✓ config_pins: none active
  ✓ Python: Python 3.11.15
  ✓ uv: installed
  ✓ Data Dir: ~/.prometheus
  ! Bootstrap: Missing: SOUL.md, AGENTS.md
      fix: Run `oara setup` (the rich wizard) to generate identity files. Until then
           the agent runs with a generic identity (SOUL.md/AGENTS.md shape the system
           prompt only — tools and the loop are unaffected).
  ✓ Dependencies: all required packages installed

Connectivity:
  ✓ Inference: llama_cpp reachable at http://localhost:8080
  ✓ Web: port 8005 free (daemon not running — web API will bind on start)
  ! API token: web auth OPEN — no PROMETHEUS_API_TOKEN set
      fix: Run `oara token rotate` (the daemon also mints one automatically on
           first start with web enabled).
  · Telegram gateway: not enabled
  · Slack gateway: not enabled
  · Discord gateway: not enabled
  · Cloud keys: DeepSeek not set · Kimi not set · GLM not set · MiMo not set ·
      Qwen not set · DashScope/WAN not set · Kling AK+SK not set

Model:
  ✓ Model: detected: gemma-3-27b-it-Q4_K_M

Resources:
  ✓ Advertised tools: 11 of 51 registered offered to the model: bash, edit_file,
      glob, grep, memory, read_file (+5 more)
  ✓ Coding sandbox: backend 'process' — confines file tools only, a shell redirect
      escapes it
  ✓ Trajectory export: enabled — 0 export file(s) in ~/.prometheus/trajectories
  · Whisper STT: voice disabled — check skipped
  ! GPU: No GPU detected
      fix: Running on CPU. For faster inference, configure a GPU machine.
  ✓ Disk: 29.2 GB free

RESULT: OK with 4 warning(s)

The four warnings, and which of them to care about

API token: web auth OPEN

This is the one to act on. With no token, anything that can reach port 8005 can drive the daemon. On a laptop behind a firewall that may be acceptable for an afternoon; on anything reachable it is not. The daemon mints a token on first start with web enabled, or you can do it now with oara token rotate. See tokens and the open web API.

Bootstrap: Missing SOUL.md, AGENTS.md

Expected if you ran --fast, which skips identity generation. The agent works; it just has a generic personality. Run the rich oara setup when you want the real one. The check says exactly what it affects — the system prompt, not the tools and not the loop — which is the kind of scoping worth trusting.

Bash write floor UNAVAILABLE

Only appears on Linux without bubblewrap. It is telling you a confinement you asked for (mode: auto) could not be applied, so bash is running without it. Install bubblewrap, or set the mode to off so the config matches reality. Do not leave it saying auto while it is not happening.

GPU: No GPU detected

Informational. It means slow, not broken.

Two ✓ lines worth reading anyway Coding sandbox: backend 'process' — confines file tools only, a shell redirect escapes it. That is a ✓ because it is working as designed, and it is still telling you the boundary is not airtight. Likewise Advertised tools: 11 of 51 — deferred loading is on, and the model is being shown eleven tools rather than all fifty-one. Both are correct states you should know about, not problems.

A green doctor means the daemon will start. Run it always-on, or connect Beacon.

PreviousConnect Beacon NextRun it always-on