Where rta keeps things
Configuration
rta runs with no configuration at all, and a fresh machine needs none. What is worth doing once is connecting the agent clients that are on it, and that is what rta init is for:
rta initIt looks at the machine. For each client it finds — Claude Code, VS Code, Codex, Gemini — it offers to register rta with it, as the command it would run, one question each, Enter to skip; it prints the line that turns on tab completion for your shell, and offers to attach the first-party plugin index (the same question rta plugin install pg asks, with the address in it, and --yes answers it at a terminal), naming the command instead where there is nobody to ask. It writes no config file, and run again it offers only what is not done yet. A client that already has a registration, with whatever options, is left as it is, and one it can run nothing for (Cursor, GitHub Copilot CLI) is named with the command that prints what to add. On a machine with none of the clients it knows it says so, because rta mcp install <name> prints the standard block for any other client that speaks MCP. The questions are asked on your terminal whatever stdout is, so rta init -o json > answer.json asks them there and leaves the answer alone in the file. On a terminal that cannot redraw (TERM=dumb, a serial console) each is a plain [y/N] line under the same text — where it registers and the command it runs — so a yes is never given blind.
rta init --yes registers every client it lists without asking, which is what a dotfiles script or a devcontainer wants, and --dry-run shows what that would run. With neither a terminal nor --yes it stops with exit code 3 and changes nothing.
When you do want a setting, the config file is ~/.config/rta/config.yaml ($XDG_CONFIG_HOME/rta/config.yaml when that is set, on macOS as well as Linux; rta config path prints the real one), and rta config schema describes every key. RTA_CONFIG overrides the location, which is what portable setups and test harnesses use.
Nothing in the config grants anything. It holds connection profiles, dashboard preferences and theme — see Your config file for the commands that change it and Profiles for the environments.
The files
| What | Where | Notes |
|---|---|---|
| Config | $XDG_CONFIG_HOME/rta/config.yaml, else ~/.config/rta/config.yaml — on macOS as well as Linux | RTA_CONFIG overrides. Builds before this one kept it in ~/Library/Application Support/rta on macOS, which nothing reads now: rta doctor names what is left there (old config) with the command that moves it, and every command at a terminal says so in one line until it is moved. Beside it: policy.yaml (your own team policy), remotes.yaml (the servers you operate) and the kv.identity key kv init --generate makes |
| Data directory | $RTA_DATA_DIR, else $XDG_DATA_HOME/rta, else ~/.local/share/rta — on macOS as well as Linux | Everything rta writes below is in it, owner-only. rta doctor prints it |
| Encrypted store | kv.age and kv.recipients | Secrets |
| Grants | grants.json, with its seal key grants.key | Sealed against tampering |
| Agent record | agent-log.jsonl, with its seal key agent-log.key | Hash-chained; The record |
| Locks | lockdown.json, with lockdown.key | Sealed like the grants; Locks |
| Switched-on profile | profile.json | Which profile rta use switched on, and until when. Not sealed, because all it can do is remove a bound: a file that goes missing leaves the grants alone deciding, which the sealed grants are the answer to; Profiles |
| Plugins | trusted.json (what you approved), plugins/store/ and plugins/bin/ (what an index installed, and the links that find it), plugin-cache/ with plugin-cache.key (what each plugin build declared, sealed, so a run does not start every plugin to ask), indexes/ (the clones) | Using plugins |
| Notebook and shortlists | notes.json, recent.json | The CLI |
| Team policy | .rta-policy.yaml, walking up from the working directory | Team policy |
Exact paths differ per platform. rta doctor prints the real ones rather than the documented ones, which is the answer to use when they disagree.
A machine whose environment names no home — a service started without HOME, a container run as a uid with no environment — is asked its account database first. When that has none either, rta keeps its state in rta-<uid> under the temporary directory, which does not outlast a reboot or a container, says so on stderr once per run, and refuses to use that directory when it is not a private directory of the account. Set HOME or RTA_DATA_DIR to keep grants, the record and the store: a state directory that vanishes with the container is an audit trail that does too. A config path that falls back to ./.rta.yaml for want of a config directory is not honoured for profiles, plugin settings or the dashboard, which is why a container sets RTA_CONFIG as the MCP chapter shows.
Related
- Installation — putting rta on your
$PATH - The path gate — why an agent cannot read most of these