Docs / Install

ivralo doctor

ivralo doctor checks everything ivralo depends on, section by section, and gives each problem one line with its fix. Run it after an install, after an upgrade, and before blaming the model.

Running it

ivralo doctor

It takes no options. It reads the same settings every other command reads and changes nothing, with one exception: a stopped PostgreSQL cluster that ivralo made is started, as any ivralo command would start it. It still runs when the workspace cannot be entered, since that is one of the things it diagnoses.

ivralo init ends by running the same report over the settings it has just written.

Reading a row

postgres
    ok  postgres from  docker compose (the ivralo-postgres container)
  fail  reachable  postgresql+psycopg://ivralo:***@127.0.0.1:5432/ivralo - OperationalError: (psycopg.OperationalError) connection failed: ...
        start it with: docker compose up -d

Mark	Meaning
`ok`, green	The check passed. The text after the label says what was found.
`fail`, red	The check failed. The indented grey line under it is the fix.
An indented grey line alone	A note: something off by choice, not configured, or worth knowing. It never fails the report.

There is no yellow in doctor's report: a row passes or fails, and everything else is a note. The yellow hint rows you may have seen come from ivralo init, whose report marks a step that needs nothing now but says what you could do.

The verdict and the exit code

The report ends with one of two lines:

Everything checks out. Start with: ivralo
Some checks failed. Fix those first.

The exit code is 0 when every row passed and 1 when any row failed, so a script or a deploy step can run ivralo doctor as a gate. Notes never change the exit code.

The sections

The sections come in this order. A feature you have not configured gets a single note saying so, never a red row.

The machine and its storage

Section	What it checks
`environment`	Python; the home and how it was found (`IVRALO_HOME`, or the checkout you started in); the code root and its skill shelf; which `.env` files were read; whether the workspace is writable, trusted and a git repository; `IVRALO.md` or `AGENTS.md`. Says when the installed version carries more skills than the home's shelf.
`private files`	That `.env`, `google-token.json` and `api-token` are readable by their owner only.
`postgres`	Where the database comes from (Docker, a URL you named, or a cluster ivralo made), whether it answers, and the address its port is published on. For a made cluster: the data directory, the port and the `pg_dump` line (PostgreSQL).
`disk`	Free space on the workspace's drive, the size of the file history, the database's size.
`libraries`	That every library the engine imports can be imported.

Models

Section	What it checks
`ollama`	When a role or the embedder runs on Ollama: the server, the tags pulled against the tags in use, and how much of each loaded model the GPU holds.
`providers`	Each hosted provider in use: its SDK, its key, and what leaves the machine. An OpenAI-compatible endpoint is asked for its model list; if the gateway forbids the listing, a one-token completion decides. Also says which models count as hosted for incident evidence.
`context`	The configured context window against what Ollama actually runs.

Skills, knowledge and tools

Section	What it checks
`skills`	Both shelves validated and linted, files repaired on load, and who owns each skill.
`mcp`	The servers declared in `mcp.json`. Connections are probed only on demand, with `ivralo mcp test <name>`.
`knowledge`	The knowledge index: the `vector` extension, one real embedding request and the size it returns, and what the index holds.
`web`	The web tools: the search libraries, the browser, a SearXNG if configured. Off on a server.
`ocr`	The `docling` command and its languages, for scanned documents.

Integrations

Section	What it checks
`tracing`	Whether spans are exported, and where.
`database`	Each database connection you declared for the team to query. Not ivralo's own PostgreSQL, which is `postgres` above.
`terminal`	Whether the terminal can show pictures, and your key bindings.
`photos`	The stock photo tools' dependencies.
`mail`, `notify`	The mail account and who may be written to; the Telegram or Slack channel.
`google`, `github`	The Google login and its services; the GitHub token, the `gh` command and the GitHub Clerk.
`forge`	ivralo's git identity, the forge credential and whose it is, and the mode (Install on a server).
`schedules`	Each scheduled request, whether the operating system's scheduler has it, and its last run.

Running code

Section	What it checks
`python runtime`	The worker's sandbox: the process, its limits, its scrubbed environment.
`permissions`	The home's and the repository's `permissions.json`, each summarised, and the merged shell policy.
`egress`	The egress policy: what is denied everywhere, your host lists, and what each exit (web, browser, worker, shell) does with a host nobody decided.
`language servers`	Each server `IVRALO.md` declares: on the `PATH`, allowed to start, and whether it answers.
`api`	The local API: the token file, and whether `ivralo serve` is running on its port, off, or the port is taken by something else.
`code index`	What the repository's code index reflects and holds; a declared language server that produced no symbols is red.
`changesets`	On or off, and any changeset still staged.
`evidence`	The folders `# Evidence` in `IVRALO.md` opens to search, and the files each adds. A declared folder that cannot be one is red.
`capabilities`	The profile, the capability table, each specialist's grants, the baseline, and what the main agent holds.
`session`	The database URL with its password hidden, the schema, the instance limits, the active session and the memory count.

When something is red

Fix the rows in order: a red postgres or environment row usually explains red rows further down. Each failed row's grey line says what to run or change. Then run ivralo doctor again.