Sentinel

Sentinel is a tsnet-embedded Tailscale observer. It tracks tailnet netmap changes, detects meaningful diffs, and sends notifications through configurable sinks.

Features

• Realtime observation via Tailscale IPNBus (source.mode: realtime)
• Optional polling mode (source.mode: poll)
• Presence event detection (peer.online, peer.offline)
• Route-based notifier pipeline with multiple sinks
• Always-on local JSON sink (stdout-debug) for visibility
• Webhook delivery with retries and structured success/failure logging
• Structured logging with stable log_source attribution (sentinel, tailscale, sink)

Installation Paths

• GitHub Release binary (recommended for operators)
• Docker image / Docker Compose
• Source run with go run (development)

See docs/getting-started.md for complete setup details.

Quick Start (GitHub Release Binary)

Download and install from GitHub Releases (Linux amd64 example):

VERSION=v0.1.0

gh release download "$VERSION" \
  --repo jaxxstorm/sentinel \
  --pattern 'sentinel_*_linux_amd64.tar.gz' \
  --pattern 'checksums.txt'

tar -xzf sentinel_*_linux_amd64.tar.gz sentinel
install -m 0755 sentinel /usr/local/bin/sentinel
sentinel version

Then run Sentinel:

sentinel validate-config --config ./config.example.yaml

REQUESTBIN_WEBHOOK_URL="https://your-endpoint" \
sentinel test-notify --config ./config.example.yaml

REQUESTBIN_WEBHOOK_URL="https://your-endpoint" \
sentinel run --config ./config.example.yaml

Quick Start (Docker)

cp .env.example .env

Set SENTINEL_TAILSCALE_AUTH_KEY in .env, then run:

docker compose -f docker-compose.yml -f docker-compose.local.yml up --build

For GHCR image usage, Railway import, and environment matrix details, see docs/docker-compose.md and docs/docker-image.md.

Configuration

• Example config: config.example.yaml
• Supports YAML/JSON with SENTINEL_ environment overrides
• Supports ${VAR_NAME} interpolation in sink URLs

Commands

• run
• status
• diff
• dump-netmap
• test-notify
• validate-config

Use sentinel --help for full command and flag details.

Documentation

Operator docs live under docs/ and are structured for Docsify.

• Getting Started
• Configuration Reference
• Docker Compose and Railway
• Docker Image
• Release Artifacts
• Sinks and Routing
• Troubleshooting
• Command Reference

To preview with Docsify:

docsify serve docs

Development

Run tests:

go test ./...

Run from source with go run:

go run ./cmd/sentinel run --config ./config.example.yaml --log-level debug