Quickstart

Five minutes from zero to first alert firing.

From nothing to "first alert fires" in about five minutes. Generate a config, wire one rule, run the agent, watch it complain.

1. Generate a config

nanook init

The interactive picker walks you through which collectors and channels to enable. If you want to skip the prompts and grab the canned starter:

nanook init --template

By default the config lands in ~/.nanook/nanook.toml so nanook run finds it from any cwd. Pass --here if you'd rather drop a ./nanook.toml next to a checkout (the dev workflow); -c <path> overrides the location explicitly. Either way the file looks like this:

# nanook agent config

[labels]
# host = "node-1"

[log]
level = "info"

[channels.ops]
type = "log"

[[collectors]]
name = "cpu"
interval = 5

[[collectors]]
name = "mem"
interval = 10

[[collectors]]
name = "disk"
interval = 60

[[adapters]]
name = "stdout"

# uncomment for file output
# [[adapters]]
# name = "file"
# [adapters.opts]
# path = "/var/log/nanook/metrics.log"

[[alerts]]
expr = "cpu.usage > 90%"
count = 3
channel = "ops"

[[alerts]]
expr = "mem.usage > 90%"
count = 1
channel = "ops"

cpu.usage, mem.usage, and disk.usage are fractions in [0, 1]. The % suffix in nanook-expr divides by 100, so 90% parses as 0.9. Writing cpu.usage > 90 would never fire.

2. Tweak the rule so it actually fires

The starter alerts on CPU above 90% for three ticks. Lower the bar so it fires on a normal laptop:

[[alerts]]
expr    = "cpu.usage > 5%"
count   = 1
channel = "ops"

count is how many consecutive ticks the predicate must hold before triggering.

If you want to expose the admin server (so nanook ctl and nanook tui can talk to the agent), add this on top of the file:

[admin]
enabled    = true
addr       = "127.0.0.1:9091"
authorized = ["ssh-ed25519 AAA... me"]

The admin endpoint is auth-required by default and refuses to start without at least one authorized key. Generate a client identity:

nanook keygen

That writes ~/.nanook/admin/id_ed25519 and ~/.nanook/admin/id_ed25519.pub. Paste the contents of the .pub file into authorized. The ctl client and the TUI sign their requests with ~/.nanook/admin/id_ed25519 automatically.

Hacking on a laptop and don't want to bother? Set auth = "none" on the [admin] block to opt out. Don't ship that to a shared host. See Admin server.

3. Validate it

Confirm the config parses and every piece can be built:

nanook check

A green check means you're good. A failing check points at the bad span.

4. Run

nanook run
# or just
nanook

You'll see structured logs in your terminal. After a few seconds the alert fires:

INFO alert kind=fire rule="cpu.usage > 5%" channel=ops trigger=cpu.usage=0.123

5. Poke it from another shell

While nanook is still running, open a second terminal:

nanook ctl state                          # snapshot of every collector + rule
nanook ctl pause cpu                      # stop the cpu collector
nanook ctl resume cpu                     # bring it back
nanook ctl silence "cpu.usage > 5%" 60s   # mute that rule for 60s
nanook ctl reload                         # re-read the config from disk

See ctl for the full set.

6. Look at the dashboard

nanook tui

A ratatui dashboard with live metrics, current alert state, and the agent's log ring. See TUI.

What's next

  • Read Configuration end to end. It's short.
  • Pick a real channel: Channels for Slack, Discord, webhooks, exec.
  • Pick a real adapter: Adapters for Prometheus, statsd, file.
  • Skim nanook-expr. The DSL has more moves than > and <.