Plugin environment-variable reference

Every bundled hytte-plugin-* binary is configured the same way: no config DSL, just environment variables read at startup. This page inventories every one of them, swept from source (std::env::var / var_os / option_env! call sites in crates/hytte-plugin-*/src, the hytte-plugin SDK, and hytte-ai-providers) rather than hand-maintained — see #573.

How to set these

Declaratively, per plugin, via the Nix option:

programs.trollshell.plugins.<name>.env = {
  PET_NAME = "nisse";
  PET_LLM_MODEL = "google/gemini-3.5-flash";
};

This renders into the launch-state file the shell reads at startup and is applied as --setenv=K=V when it launches the plugin as a transient trollshell-plugin-<id> user unit (trollshell/src/plugin_launcher.rs). Set the same vars in a shell profile for an ad hoc / hand-launched run — the plugin reads its environment directly either way.

Secrets never go in env. The launch-state file is world-readable, so API keys must go through programs.trollshell.plugins.<name>.secrets instead (e.g. secrets = [ "openrouter" ];), which injects the key from the login keyring as <SLOT>_API_KEY at spawn time — never written to disk. See nix/module-common.nix's secrets option description for the full mechanism.

Precedence, for a plugin that also reads a config file (e.g. usage's ~/.config/trollshell/usage.toml): environment wins over the file, which wins over the plugin's built-in default. Not every plugin has all three layers — each section below says which it actually reads.

Infrastructure vars, not knobs. Every plugin (via hytte-plugin-proto's topology::socket_path) dials the host at $XDG_RUNTIME_DIR/trollshell/plugin.sock, and a couple of plugins resolve their own state/config paths off $XDG_STATE_HOME / $XDG_CONFIG_HOME / $HOME. These are standard session variables set by the login session / systemd, not something you set per-plugin — they're omitted from the tables below and noted inline only where a plugin's behavior depends on them in a non-obvious way.

Bundled plugins

Sections below follow bundledPluginNames' order in flake.nix (12 total).

audio-widget (hytte-plugin-audio-widget)

No runtime knobs — configuration is entirely via the shell/wire protocol (it renders purely off the host's StateKey::AudioSpectrum push).

bar-clock-demo (hytte-plugin-bar-clock-demo)

No runtime knobs — configuration is entirely via the shell/wire protocol.

caw (hytte-plugin-caw)

Also reads $HOME (to locate places.toml) and $XDG_STATE_HOME/$HOME (for the expression/briefing-stamp state dir) — standard XDG paths, not per-plugin knobs.

clock-demo (hytte-plugin-clock-demo)

No runtime knobs — configuration is entirely via the shell/wire protocol.

departures (hytte-plugin-departures)

No environment-variable knobs. Station config (which stop, walk-time budget, line/direction filter) comes entirely from the first [[place]] block of ~/.config/trollshell/places.toml — the same file + schema the native hytte-services::places service owns and documents a default for (feed.rs::load_station_config). The file is re-read on every poll, so an edit while the board is open is picked up on the next fetch. Only $HOME is read (to locate the file) — not a configurable knob.

infobroker (hytte-plugin-infobroker)

No launch-time env knobs for the plugin daemon itself. Its own broker socket and durable grant store are located from $XDG_RUNTIME_DIR and $XDG_STATE_HOME/$HOME respectively (paths.rs) — standard session paths, always set, not meant to be overridden via plugins.infobroker.env.

The crate also ships a separate CLI binary, hytte-infobroker (the client the skill folder's agents shell out to — not what plugins.<name>.env launches, which is the hytte-plugin-infobroker daemon binary). That CLI reads HYTTE_INFOBROKER_TOKEN, the session token hytte-infobroker auth --agent <name> mints and prints as an export line for eval; hytte-infobroker get then requires it be set (cli.rs). This is CLI-side, per-invocation state, not a plugin-launch knob.

pet (hytte-plugin-pet)

preem-demo (hytte-plugin-preem-demo)

No runtime knobs — configuration is entirely via the shell/wire protocol.

terminal (hytte-plugin-terminal)

No runtime knobs — configuration is entirely via the shell/wire protocol.

timer (hytte-plugin-timer)

No runtime knobs — configuration is entirely via the shell/wire protocol.

usage (hytte-plugin-usage)

Precedence is env → ~/.config/trollshell/usage.toml → built-in default, resolved once per field (config.rs::resolve). With no dashboard URL from either source the plugin renders a calm empty-state card and makes no network calls at all.

weather (hytte-plugin-weather)

Shared / SDK-level environment variables

The hytte-plugin SDK itself (crates/hytte-plugin/src, the Plugin trait + run()) reads no environment variables — env-based config is a plugin-author idiom on top of it, not part of the runtime.

hytte-ai-providers (the shared OpenAI-compatible chat client pet and caw's brains both use) reads two, via load_key:

For pet/caw specifically, the OpenRouter key precedence is therefore: OPENROUTER_API_KEY env → ~/.config/trollshell/openrouter.key file → the plugin's own PET_LLM_API_KEY/CAW_LLM_API_KEY env fallback (last resort, not recommended — see each plugin's table above).

A note on *_LLM_MODEL with no value set: when the OpenRouter path is selected (a key is resolved and no *_LLM_URL override is set) but PET_LLM_MODEL/CAW_LLM_MODEL is unset, Provider.model stays None and no model field is sent in the request body. hytte-ai-providers' own docs note OpenRouter requires a model id for a cloud call — the code does not enforce this or supply a default, so an unset model on the cloud path is a misconfiguration rather than a supported "use OpenRouter's default" mode. Consult crates/hytte-ai-providers/src/lib.rs and each plugin's brain.rs/briefing.rs if this needs to change.