NixOS

The flake’s NixOS module runs the server, the agent, or both.

Configure the server

Add the input and module to your flake:

{
  inputs.kogut.url = "github:piotrkowski/kogut";

  outputs = { nixpkgs, kogut, ... }: {
    nixosConfigurations.server = nixpkgs.lib.nixosSystem {
      modules = [
        kogut.nixosModules.default
        {
          services.kogut = {
            enable = true;
            url = "https://kogut.acme.com";
          };
        }
      ];
    };
  };
}

The module binds kogut to loopback and leaves the firewall closed. Add a reverse proxy:

services.caddy = {
  enable = true;
  virtualHosts."kogut.acme.com".extraConfig = "reverse_proxy 127.0.0.1:8484";
  virtualHosts."status.acme.com".extraConfig = "reverse_proxy 127.0.0.1:8484";
};

To listen on all IPv4 interfaces instead, set services.kogut.listen = "0.0.0.0:8484", and services.kogut.openFirewall = true to open that port.

Apply it with sudo nixos-rebuild switch, open the panel, and create your account with the setup token from the journal:

journalctl -u kogut | grep setup_token

Add checks and secrets

Put kogut.toml settings in services.kogut.settings. Keep secrets in an environment file, not in the Nix store:

services.kogut = {
  environmentFile = "/run/secrets/kogut.env";
  settings = {
    brand.status_domain = "status.acme.com";
    check = [
      { name = "API"; url = "https://api.acme.com/health"; }
    ];
    alert = [
      {
        type = "telegram";
        bot_token = "\${TELEGRAM_BOT_TOKEN}";
        chat_id = "-1001234567890";
      }
    ];
  };
};

Write TELEGRAM_BOT_TOKEN=... in the environment file. The \${...} escape passes the substitution to kogut as written. systemd LoadCredential also works for secret substitutions.

Rebuild after changing settings; the module writes a new file to the Nix store and restarts the service.

Configure the agent

services.kogut-agent = {
  enable = true;
  server = "https://kogut.acme.com";
  tokenFile = "/run/secrets/kogut-agent-token";
};

Use the token from Hosts → Add a server; the module loads it as a systemd credential. It grants journal access, and Docker access when virtualisation.docker.enable is set. Read Permissions and the Docker socket, or set services.kogut-agent.docker = false.

Set other agent environment variables in systemd.services.kogut-agent.environment. All options are in the module.

The kogut package installs completions for bash, zsh, and fish.

Update

Follow Upgrading. If the flake input points to a release tag, change the tag first.