panoptikon/README.md

# Panoptikon – Watch the world from NixOS
A NixOS module for monitoring website content and command output changes.

![](./panoptikon.jpg)

## Overview

Panoptikon is a generic command output and website watcher that periodically runs scripts and reports changes. It's designed to be flexible and can monitor anything from API endpoints to system metrics.

## Features

- **Flexible Watchers**: Monitor any command output or website content
- **Custom Frequencies**: Run scripts at any interval using systemd.timer syntax
- **Multiple Reporters**: Report changes to various destinations (IRC, Telegram, Prometheus, etc.)
- **Secret Support**: Securely pass credentials to scripts without exposing them in the Nix store
- **Stateful Tracking**: Automatically tracks previous output and reports only changes
- **Modular Design**: Easy to extend with custom watchers and reporters

## Installation

Add Panoptikon to your NixOS configuration:

```nix
{ config, pkgs, ... }:

{
  # Enable Panoptikon service
  services.panoptikon.enable = true;

  # Configure your watchers
  services.panoptikon.watchers = {
    # Your watcher configurations go here
  };
}
```

## Configuration

### Basic Watcher Configuration

```nix
{
  services.panoptikon.enable = true;
  
  services.panoptikon.watchers = {
    # Monitor GitHub metadata
    github-meta = {
      script = pkgs.writers.writeDash "github-meta" ''
        ${pkgs.curl}/bin/curl -sSL https://api.github.com/meta | ${pkgs.jq}/bin/jq
      '';
      frequency = "*:0/5";  # Every 5 minutes
      reporters = [
        # Report changes to Telegram
        (pkgs.writers.writeDash "telegram-reporter" ''
          ${pkgs.curl}/bin/curl -X POST https://api.telegram.org/bot''${TOKEN}/sendMessage \
            -d chat_id=123456 \
            -d text="$(cat)"
        '')
        # Also show desktop notifications
        (pkgs.writers.writeDash "notify" ''
          ${pkgs.libnotify}/bin/notify-send "$PANOPTIKON_WATCHER has changed."
        '')
      ];
    };

    # Monitor a website for specific content
    nixos-updates = {
      script = pkgs.panoptikon.urlSelector "#news h2" "https://nixos.org/blog/";
      frequency = "daily";
      reporters = [
        # Report to IRC
        (pkgs.panoptikon.kpaste-irc {
          target = "#nixos";
          server = "irc.libera.chat";
          messagePrefix = "New NixOS blog post: ";
        })
      ];
    };

    # Monitor a local command
    disk-space = {
      script = pkgs.writers.writeDash "disk-space" ''
        df -h / | tail -1 | awk '{print $5 " used
        }'';
      frequency = "*:0/30";  # Every 30 minutes
      reporters = [
        # Log to systemd journal
        (pkgs.writers.writeDash "journal-log" ''
          journalctl -t panoptikon-disk-space --since "1 hour ago" | tail -5
        '')
      ];
    };
  };
}
```

## Service Management

### systemd Integration

Each watcher gets its own systemd service and timer:

```bash
# List all Panoptikon services
systemctl list-units "panoptikon-*"

# Check a specific watcher
systemctl status panoptikon-github-meta

# View logs
journalctl -u panoptikon-github-meta -f

# Trigger a manual run
systemctl start panoptikon-github-meta
```

### Timer Configuration

Timers use systemd timer syntax. Common examples:

- `*:0/5` - Every 5 minutes
- `daily` - Once per day
- `*:0/15` - Every 15 minutes
- `weekly` - Once per week

See [systemd.time(7)](https://www.freedesktop.org/software/systemd/man/systemd.time.html) for full syntax.

## Security Considerations

- Watchers run as the `panoptikon` system user
- Scripts are executed in `/var/lib/panoptikon`
- Use `LoadCredential=` to securely pass secrets
- Scripts should be written defensively (use `set -euo pipefail`)

## Troubleshooting

## Examples

See the [examples directory](./examples/) for complete configurations.

Run `nix run .#panoptikon-vm` to start a VM with Panoptikon and example watchers pre-configured.