Concepts

Where ivralo works

Workspace

The one directory ivralo works in. Started inside a git repository, the workspace is that repository: nothing is copied, and ivralo keeps its own state in a .ivralo/ folder that it adds to .git/info/exclude. Outside a repository it is the home's workspace/ folder, and IVRALO_WORKSPACE overrides both. See Working in a repository.

Home

The directory ivralo works from: the shipped skills, brand.json, the database's compose file, the home's .env, and records such as trusted.json and the API token. It is whatever IVRALO_HOME names, else the ivralo checkout you started in. The installed program carries copies of a home's starting files, and ivralo init --home <dir> lays them out in a directory you own. See Quickstart.

Fallback home

A home ivralo only found instead of being told about, such as the checkout it runs from, which a cloned repository can look like. Its files count as the folder's own, not yours: its .env, skills and settings files are not read, its permissions.json can only deny, and every command that would write into it refuses. Exporting IVRALO_HOME makes it a real home. See Run from a checkout.

Trusted folder

A workspace you said yes to when ivralo asked whether to trust the files in it. Only in a trusted folder do the repository's own declarations take effect: the commands in IVRALO.md, its language servers, the allow entries of its .ivralo/permissions.json and its .ivralo/.env. The answer is recorded in the home's trusted.json by path, never in the folder, and ivralo trust records or revokes it. See Working in a repository.

IVRALO.md

The file at the repository's root that tells ivralo how the project works; AGENTS.md is read when there is none. A few sections are read by code, such as # Commands for the project's checks and # Evidence for ignored folders that hold logs; everything else is handed to every agent as the project's own instructions. It can only narrow what ivralo does: nothing that decides a permission reads it. See Working in a repository.

The agents

Main agent

The agent you talk to. It does most of the work itself, holding the team's grants under the same approvals, and hands work to a specialist only when the task needs a fresh context or a narrower grant. It never holds the right to read an account such as your mail or Google; that stays with the specialist that owns it. See Working in a repository.

Preset

What an agent is made from: a key such as coder or investigator, a display name, a set of grants, one hint sentence saying what it is for, and a limit on its tool calls. A preset has no prompt of its own; the expertise is in the skills. ivralo agents lists them.

Specialist

The agent a preset builds: a model, a Python worker in its own process, and the whole skill shelf, its own skills first. The Code Engineer (coder) edits code, and the Incident Investigator (investigator) reads an incident's evidence and files a report. Several Code Engineers can work at once, each in its own git worktree. See Parallel coders.

Skill

Knowledge packaged as markdown: a directory with a SKILL.md, and optional scripts/ and references/. A skill teaches when to use a technique, the hard rules and worked code. ivralo ships 18; skills you install or write live on a second shelf, skills.local/, in the home.

What may happen

Grant

A named permission of the form domain.grade, such as code.edit, shell.full or git.push. Every specialist has a baseline of eight, among them running Python, reading and writing files, asking you, and handing work to a colleague (team.run); a preset declares what it needs beyond that. A grant decides which tools an agent holds, never whether a call still asks: an edit asks for your yes whatever the grants say. See Approvals.

Mode

A set of grants for runs that nobody is watching. Developer mode, the default, grants them nothing that would have to ask, so they refuse instead. Server mode adds two: an unattended run may commit, and push a branch ivralo made itself to open a draft pull request. The mode is IVRALO_MODE in the home's .env, never a repository's. See Server mode and incidents.

Changeset

One turn's edits held as one unit. The edits are made in a staged copy of your tree, verified there with the project's checks, and then landed in your tree or dropped, all together. It is off unless you turn it on, and each edit still asks. See Changesets.

Incidents and long work

Bundle

A folder inside the workspace that holds an incident's evidence: logs, a deploy log, metrics, the alert. Every file in it is evidence and nothing outside it is. ivralo never writes into a bundle, with one exception: an alert taken in over the API is first written as a small bundle of one file. See The evidence bundle.

Report

What an investigation ends in: report.md under .ivralo/incidents/<id>/, with report.json and digest.json beside it. It keeps what was observed apart from what was inferred, every number in it is computed by code, and its outcome is one of four, decided by code from the Investigator's judgement. See Reading the report.

Job

A unit of long work, such as a plan run, one request or an alert's investigation, whose record lives in PostgreSQL so it outlives the process that started it. Its state moves through queued, running, waiting_for_approval, blocked and one of completed, failed or cancelled. A job that reaches a call needing a person parks on that question, and continues once someone answers. See Alert intake.

Session

A conversation: a sequence of runs sharing history, stored in PostgreSQL. Two terminals share the active session unless told otherwise, and each incident investigation is its own session, named after the bundle and the moment. ivralo sessions lists them, and -s <id> picks one. See The session.