# Environment variables

Every environment variable the server, the agent, and the install script read, with defaults.

Monitoring configuration is in [`kogut.toml`](https://docs.kogut.dev/reference/configuration/). 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`](https://docs.kogut.dev/reference/configuration/#server), 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](#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](https://docs.kogut.dev/reference/configuration/#secrets), 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](https://docs.kogut.dev/reference/configuration/#secrets).

## Command-line client

[`kogut status`](https://docs.kogut.dev/reference/cli/#kogut-status), [`kogut incidents`](https://docs.kogut.dev/reference/cli/#kogut-incidents),
and [`kogut checks`](https://docs.kogut.dev/reference/cli/#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`](https://docs.kogut.dev/reference/cli/#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](https://docs.kogut.dev/agent/command-checks/)
in the host's own file. [CLI flags](https://docs.kogut.dev/reference/cli/#kogut-agent) 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](https://docs.kogut.dev/agent/docker/) 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](https://docs.kogut.dev/agent/permissions/). |
| `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](https://docs.kogut.dev/agent/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](https://kogut.dev/install), 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](https://docs.kogut.dev/reference/cli/#the-agent-only-build), unless the installed `kogut` runs the
server or the release has no agent archive.