Quickstart

Before you start

You need the ivralo command, installed with uv. There is no public package yet: the repository is private, so access is given on request (write to us). The install itself is one line:

uv tool install --python 3.13 'ivralo @ git+ssh://git@github.com/kemalcalak/ivralo.git'

You also need:

• PostgreSQL with pgvector. Docker is the easy way: ivralo init starts the database with the compose file it puts in the home. A database you already run works too (PostgreSQL).
• A model. A local one through Ollama, your company's OpenAI-compatible endpoint, or a hosted API.
• git, and the repository of a service you run, for the investigation.

This page is the developer's path, with questions. On a server with nobody at the keyboard, follow Install on a server instead.

1. Make a home

The home is the directory ivralo works from: the shipped skills, brand.json, the database's compose file and the home's .env. The installed program carries copies of all of it, and init lays them out:

ivralo init --home ~/ivralo

init asks which model you want, then waits for a yes before each step that does something: it writes .env, generates the database password, starts PostgreSQL with docker compose up -d, pulls the Ollama models that are missing and installs the browser the web tools use. Anything already in the directory is kept. At the end it prints the line that points every later ivralo at the home, with the home's full path:

export IVRALO_HOME="$HOME/ivralo"   # in ~/.profile to keep it

Put it in ~/.profile, then open a new terminal or export the variable in this one. On Windows, run the setx line init prints instead.

2. Check the machine

ivralo doctor

doctor walks every part ivralo depends on, one section at a time, and gives each problem one line with its fix. A clean run ends like this:

environment
    ok  python  3.13.5
    ok  home  /home/you/ivralo · from IVRALO_HOME
    ok  .env read  /home/you/ivralo/.env
...
Everything checks out. Start with: ivralo

Anything marked fail comes first. ivralo doctor goes through every section.

3. Choose a model

The model is set in the home's .env, as a model reference. init writes it from your answer; you can change it at any time.

init can write the endpoint lines for you: ivralo init --home ~/ivralo --model-url http://gpu-box:8000/v1 --model my-model.

A hosted model is named at every start, and doctor's providers section says what leaves the machine. Incident evidence is refused on a hosted model unless you allow it for the run with --hosted, which also requires IVRALO_INCIDENT_MASK=true so the model reads placeholders instead of your hosts, addresses and identifiers.

4. Investigate a sample incident

An investigation runs inside the repository of the service that failed, because half of what it establishes is about the deployed code. Go to that repository and make a small bundle, a folder holding the evidence:

cd ~/src/checkout-service
mkdir incident

Put two files in it. A deploy log, where a line with revision= or commit= counts as a deploy:

2026-10-12T10:01:00Z deploy checkout-service revision=6ad91e2

And the service's log around the time it broke, copied as it is:

2026-10-12T10:04:12Z ERROR GET /cart 500 KeyError: 'currency'
2026-10-12T10:04:19Z ERROR GET /cart 500 KeyError: 'currency'

Use a commit your repository really has, and real log lines if you have them: the more the evidence says, the more the report can establish. Then run:

ivralo incident incident/

The first time, ivralo asks whether you trust this folder; say yes for your own repository. The Investigator reads the facts ivralo computed from the bundle and the code, decides the class and the cause, and writes a report. The command prints where it is and the outcome:

.ivralo/incidents/incident-20261012-101500/report.md
DIAGNOSED - class code

With thin evidence the outcome is more likely INSUFFICIENT_EVIDENCE, which is the honest answer, not an error. The exit code is 0 when a report was written, 1 when none was, and 2 when the investigation could not start (not a repository, a missing bundle, a hosted model without --hosted, no database).

Open report.md. Each claim cites a bundle line or a repository line. To see where one came from:

ivralo why -s <id> last "KeyError: 'currency'"

The command prints the session id and this line for you after every investigation. Server mode and incidents explains the report and its four outcomes.

5. A first look at developer mode

In the same repository, open a session:

ivralo

This is the full-screen session. Type a request in your own words, such as "find where the cart reads the currency and explain it". The main agent reads the code and answers; when it wants to change a file it shows a diff and waits for your yes. /help lists the commands, and exit leaves.

For a one-off question from a script, ivralo ask "..." runs the same team unattended: anything that would have to ask you, such as an edit or a shell command outside the read-only list, is refused instead.

Where to go next

• Concepts: the words these pages use.
• Working in a repository: developer mode in full.
• Install on a server: the same thing next to production, with no questions.