Config Validation

boks validates boks.toml when it loads it. If the file has a syntax error or an unknown key, boks prints an error naming the file and exits before running anything — a broken config never silently falls back to defaults.

Common errors

TOML syntax error

Error: Invalid configuration in /home/user/.config/boks/boks.toml

Caused by:
    TOML parse error at line 2, column 21
      |
    2 | forward_ssh_agent = yes
      |                     ^^^ expected a boolean, string, integer, float, ...

true/false must be lowercase booleans in TOML, not yes/no.

Unknown key

Error: Invalid configuration in ./boks.toml

Caused by:
    TOML parse error at line 2, column 1
      |
    2 | security_scan = false
      | ^^^^^^^^^^^^^
    unknown field `security_scan`, expected one of ...

Misspelled options are rejected instead of being silently ignored — the correct key here is security_scan_enabled.

Wrong tool entry format

# Wrong — object without the image key (and `cmd` is not a valid key)
[tools]
python = { cmd = "python3" }

# Correct
python = { image = "boks.sh/python:3.12", command = "python3" }

Missing explicit config

If BOKS_CONFIG points at a file that does not exist, boks errors instead of running with defaults — you named that file, so a typo in the path must not go unnoticed.

Testing your config

Every boks command loads and validates the config first, so any invocation works as a check — the bare boks help screen is the cheapest:

BOKS_CONFIG=./boks.toml boks

If the file is invalid, boks reports the error immediately.