config.toml

config.toml holds avar’s settings for you, on this machine, across every project. It is optional, and avar never creates it.

1. Location
2. Example
3. Keys
   1. forward_env
   2. idle_timeout
4. How the file is read

Location

The file lives in avar’s state directory:

Setting the AVR_HOME environment variable moves the whole state directory, this file included, to the directory it names.

Example

# ~/.avr/config.toml
forward_env = ["AWS_PROFILE", "GITHUB_TOKEN"]
idle_timeout = "4h"

Keys

forward_env

A standing grant. Each named host variable is forwarded into every guest session, in every project, when the host has it. Unlike forward_env in a project’s .avr.toml, it needs no approval: this file is yours.

--env-file and --env on the command line override it for the same name. See what crosses into Linux.

idle_timeout

How long an environment with no live avr session waits before avar stops it. Durations use Go’s syntax: a number followed by h, m or s, and combinations such as 1h30m.

A VS Code, Cursor or Zed window connected to the environment counts as a session, although avr code, avr cursor and avr zed exit once the editor opens. Before stopping a running environment, the check looks inside it for a connected window. If it finds one, it leaves the environment running and restarts its timeout. If it cannot look, it leaves the environment running. Opening an editor also restarts the timeout, so the editor has time to connect. See avr code.

avar checks every thirty minutes, so an environment stops up to half an hour after its timeout rather than exactly at it. The check is registered with the host’s scheduler (a launchd agent on macOS, a Task Scheduler task on Windows) when avar creates an environment, and avar says so the first time, with the command that removes it. Setting idle_timeout = "0" removes the check at your next avr, and avar says so; setting a timeout again puts it back. A check you delete yourself stays deleted.

How the file is read

The file is read by the same strict reader as .avr.toml, and accepts the same subset of TOML. Its keys are the two above and nothing else. A key avar does not know, a value of the wrong kind, or TOML the reader does not support is an error, never a setting quietly ignored:

avr: /Users/you/.avr/config.toml line 2: unknown key "idle_timout": did you mean idle_timeout? config.toml understands idle_timeout, forward_env
     Nothing was started or changed. Fix the file and run the command again; until then idle auto-stop is paused, and `avr status`, `avr stop` and `avr destroy` still work

The message names the file, the line and the key, and says what to write instead. Some examples of what it refuses:

While the file cannot be read:

• every command stops before it starts, creates or changes anything, and exits 1;
• avr status, avr stop and avr destroy print the same error and still run, so you can always see and release what is running;
• avr help and avr version work as usual;
• the background idle check stops nothing. It cannot tell what you meant, and guessing the two-hour default would stop environments you may have asked it to leave alone. It resumes once the file is fixed.

Earlier versions of avar read this file leniently and ignored what they could not read. If a file that seemed to work is now refused, the line the message names was either not being applied, or needs quotes or a unit.