Docs / Reference

Settings files

Every file ivralo reads as configuration: the ones in your ivralo home, which apply everywhere, and the ones in a repository's .ivralo/ folder, which apply to that repository. For each, where it lives, what it holds and which page covers it.

The home and the workspace

Configuration lives in two places:

The home is the folder that holds your .env, your skills and the files below. IVRALO_HOME names it; without it, ivralo uses the checkout you are in, or the one it runs from. A server install makes one with ivralo init --home.
The workspace's .ivralo/ is a folder at the root of the repository ivralo works in. ivralo adds it to .git/info/exclude, so nothing in it is committed. Its configuration files apply only once you have trusted the folder, and some apply only in part even then.

Nothing conversational is kept in either: sessions, runs and memory are in PostgreSQL. The Python worker can write none of these files.

In the home

File	What it holds	Written by	Covered on
`.env`	Settings as `IVRALO_*=value` lines, and provider keys.	You; `ivralo init` copies `.env.example` and sets the model	Environment variables
`mcp.json`	The MCP servers and which specialists carry each one's tools. Moved by `IVRALO_MCP_CONFIG`.	`ivralo mcp add` and `remove`, or you	MCP servers
`brand.json`	The house colours every PDF, document, deck, workbook and chart uses. Moved by `IVRALO_BRAND_FILE`.	`ivralo init --home` copies the default; you edit it	below
`keybindings.json`	Session keys moved from their defaults.	You	Slash commands and keys
`permissions.json`	Shell allow and deny prefixes, hosts, the shell timeout and the tools unattended runs may use. Moved by `IVRALO_PERMISSIONS`.	You only	permissions.json
`databases.json`	Named databases the analyst may query, each naming the variable its URL is in. Moved by `IVRALO_DATABASES`.	You	below
`identifiers.json`	Identifiers to mask in incident evidence. Moved by `IVRALO_IDENTIFIERS`.	You	Privacy and masking
`schedules.json`	One entry per schedule: its name, when, the request, who it may mail. Moved by `IVRALO_SCHEDULES`.	`ivralo schedule add` and `remove`	Schedules
`trusted.json`	The folders you trusted or declined.	`ivralo trust`, the session's question, `ivralo init --trust`, an API request with `trust`	below
`api-token`	The local API's bearer token, one line.	The first `ivralo serve`, or `ivralo init --token`; `ivralo serve --new-token` replaces it	Local API
`gitconfig`	ivralo's own git name and e-mail, in git's config format.	`ivralo init --server`	Draft pull requests
`google-token.json`	The Google sign-in token. Moved by `IVRALO_GOOGLE_TOKEN`.	`ivralo google login`; `logout` removes it	Google Workspace
`skills.local/assignments.json`	Which specialists own each installed skill. Moved with `IVRALO_SKILLS_LOCAL_DIR`.	`ivralo skills install`, `assign`, `unassign`, `create`, `remove`	Installing skills

Beside them, skills/ is the shipped skill shelf, skills.local/ holds the skills you installed, workspace/ is where ivralo works outside a repository, and pg/ holds the PostgreSQL cluster ivralo made, when it made one (see PostgreSQL).

api-token and trusted.json are written owner-only. A trusted.json that is group- or world-writable, or damaged, trusts nothing.

In the workspace's .ivralo/

File	What it holds	Applies	Covered on
`.env`	Settings for this repository, over the home's and under the shell's. Never `IVRALO_HOME`, `IVRALO_MODE`, `IVRALO_FORGE_GH` or `IVRALO_GITHUB_URL`.	Only in a trusted folder	Environment variables
`permissions.json`	This repository's additions to the home's file. The dialog's `p` writes it.	Its denies always; its allows only in a trusted folder	permissions.json
`databases.json`	This repository's named databases. A name both files use is this file's.	Only in a trusted folder	below
`identifiers.json`	This repository's identifiers to mask, joined with the home's by kind.	Only in a trusted folder	Privacy and masking

The same folder holds ivralo's state for the repository: file history, change records, plans, staged changesets, the code index, incident reports, cassettes, exported conversations and schedule logs. See State.

IVRALO.md sits at the repository's root, not in .ivralo/. See IVRALO.md.

brand.json

{
  "appName": "ivralo",
  "primary": "#0E9384",
  "secondary": "#115E59",
  "accent": "#2DD4BF",
  "text": "#1F2937",
  "bg": "#F0FDFA",
  "grid": "#D9E7E4",
  "zebra": "#F6FCFB",
  "logo": null
}

primary is required. These are the defaults only: when you ask for other colours in a request, the agent passes a palette for that document and leaves this file alone. logo may name an image file, relative to the folder brand.json is in.

databases.json

{
  "orders": { "description": "the shop's orders replica", "env": "ORDERS_DATABASE_URL" }
}

An entry names the environment variable its SQLAlchemy URL is in, never the URL, so the file holds nothing secret. Put the URL in the home's .env or the repository's .ivralo/.env. Every connection is read-only, none of the variables reaches the Python worker, and an entry can never name one of ivralo's own credentials such as IVRALO_DB_URL. IVRALO_SQL_URL, when set, is the connection named default unless a file names one itself. See Documents and data.

trusted.json

{
  "version": 1,
  "folders": { "/srv/app": { "trusted_at": "2026-10-20T09:12:00+00:00", "by": "cli" } },
  "declined": { "/home/me/clones/unknown": { "at": "2026-10-21T14:03:00+00:00", "by": "tui" } }
}

Folders are keyed by their resolved path, so a moved folder is asked about again. by is tui, cli, api or init. It is the home's file, never the folder's: a repository cannot bring its own trust, and no tool lets the model trust a folder. ivralo trust --list shows it, and ivralo trust --revoke removes an entry.

assignments.json

{
  "version": 1,
  "skills": { "runbook-style": { "agents": ["investigator"] } }
}

An owner is a preset key from Capabilities and presets. The file sits with the skills it describes, so removing skills.local/ removes its bindings too.