Environment variables

Monitoring configuration is in kogut.toml. An empty KOGUT_* variable counts as unset.

Server

For serve and the commands that work on the local database or health.

Variable	Default	Meaning
KOGUT_URL	none	Public panel URL. Requires http:// or https://. Trailing slashes are removed. Overrides [server] url, with the same behaviour.
KOGUT_LISTEN	0.0.0.0:8484	Listen address and port. A bare port is invalid. Overrides PORT and [server] listen.
PORT	none	Port from 1 to 65535 on 0.0.0.0, used without KOGUT_LISTEN.
KOGUT_DATA	./data	Directory for the database (kogut.db), the setup token, logo files, and the copy made before migrations. /data in the container image, /var/lib/kogut with the systemd unit and the NixOS module.
KOGUT_CONFIG	$KOGUT_DATA/kogut.toml	Path of kogut.toml. A missing file counts as an empty one.
KOGUT_LOG_FORMAT	text	text or json. json writes one JSON object per log line, with ts, level, target, message, and the fields. Anything else is an error.
RUST_LOG	info	Which log lines to write: a comma-separated list of levels (error, warn, info, debug, trace, off) and target=level entries, such as debug or info,kogut_engine=debug. A target also covers the modules under it, and a target alone, such as kogut_engine, writes all its lines. Span and field filters such as kogut[span]=debug are not supported. An invalid value logs at info and prints a warning. Logs go to standard error. Even at debug and trace, they leave out passwords, tokens, cookies, and channel URLs and keys. The one exception is the one-time setup token, logged at the first start.
NO_COLOR	none	Any value but the empty string turns off colour codes in text logs and command output. Logs written to anything but a terminal, such as journald or docker logs, never contain colour codes.
TERM	set by the terminal	dumb turns off colour codes, as NO_COLOR does.
TZ	none	Machine time zone when [server] timezone is unset. Accepts a zone name, zone file path, or POSIX rule. Empty means UTC. If unset, reads /etc/localtime. Unreadable zones use UTC.
KOGUT_LOCAL_AGENT	0	1 or true runs the agent inside serve for the host the server runs on. The host takes its name from /etc/hostname under KOGUT_HOST_ROOT and gets a new token, kept only in memory, at every start. An agent elsewhere that used that host’s token can no longer connect. KOGUT_HOST_ROOT, KOGUT_STATE_DIR, DOCKER_HOST and XDG_RUNTIME_DIR work as for the agent; KOGUT_STATE_DIR defaults to $KOGUT_DATA/agent. 0 or false turns it off. Anything else is an error.
CREDENTIALS_DIRECTORY	set by systemd	Fallback directory for secret substitutions, one file per variable name.

These are read at startup and survive reloads of kogut.toml. ${NAME} substitutions are read again on reload; see Secrets.

Command-line client

kogut status, kogut incidents, and kogut checks read a running server’s API.

Variable	Default	Meaning
KOGUT_URL	the local server	The server to ask. Without it, the commands ask the server on this machine at its listen address. --url overrides it.
KOGUT_API_TOKEN	none	A read or write token from Settings → Tokens. Give this or KOGUT_API_TOKEN_FILE, not both. --token overrides both.
KOGUT_API_TOKEN_FILE	none	A file containing the token, for systemd credentials and Docker secrets.

The agent’s KOGUT_TOKEN is a host token and is never sent by these commands.

kogut run reads one more:

Variable	Default	Meaning
KOGUT_PING_URL	none	The heartbeat’s ping URL for kogut run. --ping overrides it.

Agent

Checks come from the server, apart from the command checks in the host’s own file. CLI flags override KOGUT_SERVER and KOGUT_TOKEN.

Variable	Default	Meaning
KOGUT_SERVER	required	Server URL, or comma-separated URLs tried in order on failure.
KOGUT_TOKEN	none	The host token from Hosts → Add a server in the panel. Give this or KOGUT_TOKEN_FILE, not both.
KOGUT_TOKEN_FILE	none	A file containing the token, for systemd credentials and Docker secrets.
KOGUT_INSECURE	0	1 allows a plain http:// server address. Without it, http:// works only for localhost, loopback addresses, and Tailscale addresses (100.64.0.0/10 and fd7a:115c:a1e0::/48). Must be 1 or 0.
KOGUT_SERVER_KEY	none	Pins the server’s public key: sha256: followed by the 64 hex digits of the SHA-256 of the server certificate’s public key (SubjectPublicKeyInfo). Several pins separated by commas. The pin is checked on top of normal certificate checks and needs an https:// server.
KOGUT_HOST_ROOT	/	Absolute path to the host root file system. The Docker setup uses /host.
KOGUT_STATE_DIR	/var/lib/kogut-agent	Where the agent keeps data it has not sent yet, up to 20 MiB and 1 hour. Must be an absolute path the agent can write.
DOCKER_HOST	auto-detected socket	Container API: unix:///path/to/socket or tcp://IP:PORT, with a literal IP. Defaults to /var/run/docker.sock, then the Podman socket below. See socket proxies.
XDG_RUNTIME_DIR	none	Rootless Podman socket location: $XDG_RUNTIME_DIR/podman/podman.sock. Docker’s /var/run/docker.sock takes precedence.
KOGUT_CHECKS	/etc/kogut-agent/checks.toml	Absolute path of the command checks file, read at start. Without this variable, a missing default file means no command checks. A file this variable names must exist.
KOGUT_LOG_FORMAT, RUST_LOG, NO_COLOR, TERM	text, info, none, none	Logging, as for the server.

Without a container socket, the agent reports no containers.

The agent checks certificates against the Mozilla root certificates built into kogut, not the system store. There is no setting to skip the certificate check.

Install script

Read by install.sh, not by kogut itself.

Variable	Default	Meaning
KOGUT_VERSION	latest release	Version to install, such as 0.1.0.
KOGUT_BIN_DIR	/usr/local/bin	Where to put the binary.
KOGUT_NO_SERVICE	0	1 installs only the binary and no systemd unit.

In agent mode, the script writes KOGUT_SERVER and KOGUT_TOKEN to /etc/kogut/agent.env, readable only by root. It downloads the agent-only build, unless the installed kogut runs the server or the release has no agent archive.