Everything the CLI, library, and MCP server read to find and talk to a device: the config file, every KVM_PILOT_* environment variable, and the precedence between them.

Each field resolves independently, highest priority first:

1. Explicit CLI flags / keyword arguments (--host, resolve_host(host=…)).
2. KVM_PILOT_* environment variables.
3. The profile selected with --profile NAME (a [hosts.NAME] table in the config file).
4. Built-in defaults (see the table below).

So an env var overrides the same key in a profile, and a flag overrides both. Resolution lives in src/kvm_pilot/config.py (resolve_host()).

Default location: ~/.config/kvm-pilot/config.toml (honoring $XDG_CONFIG_HOME) on Unix, %APPDATA%\kvm-pilot\config.toml on Windows. Override the path with the KVM_PILOT_CONFIG environment variable (read once, at import time). The file is optional — everything works from flags + env alone.

The format is TOML with one [hosts.<name>] table per named profile (there is no [defaults] section; unknown keys and tables are ignored). A starter file ships as config.example.toml.

[hosts.homelab]
host = "192.168.8.1"
user = "admin"
passwd = "changeme"        # prefer env injection (KVM_PILOT_PASSWD) over storing here
port = 443
scheme = "https"
verify_ssl = false          # GL/PiKVM ship self-signed certs
timeout = 30.0
driver = "glkvm"            # pikvm (default) | glkvm | blikvm | redfish | ipmi | amt | fake
# totp_secret = "BASE32SECRET"   # only if 2FA is enabled (needs the 'totp' extra)
# redfish_auth = "session"       # redfish driver only: "basic" for endpoints
#                                # without a SessionService (e.g. emulators)

[hosts.rack-bmc]
host = "idrac.lan"
driver = "redfish"

Every key resolve_host() reads, with its default:

Naming a --profile that doesn't exist in the file is an error (KeyError), not a silent fallback.

All of the per-field vars in the table above, plus:

A ready-to-copy env template ships as .env.example.

• If the config file holds a password or TOTP secret, restrict it: chmod 600 ~/.config/kvm-pilot/config.toml — and never commit a copy with real secrets.
• Passing --passwd on the command line exposes the secret to ps and your shell history; prefer KVM_PILOT_PASSWD (or the config file) for real credentials.
• The library never writes secrets back out, and passwords/session tokens are redacted from error text — but double-check logs before posting them.

See the security policy for the broader operational guidance (don't expose a KVM to the internet, the safety layer is advisory, etc.).