kage

Realtime computer monitoring with live connection watch and one-key block

v1.0.0

Linux

Quick Start

Install via jcli (recommended)

jcli install kage

Open the dashboard

kage                                # fullscreen TUI (default)
kage --full                          # enable block / kill / unblock keybinds
kage snapshot -o json | jq .host     # one-shot, scriptable
kage --doh net                       # include public IP (off by default)

What it does

kage (影, "shadow") is a realtime computer monitor with seven live panes: host header, CPU per-core, memory, disks, network, processes — and a dedicated CONNECTIONS pane in orange that blinks for the first 3 s of every new socket. Catch a stranger before it gets comfortable; one keystroke blocks it via nftables.

Connection blink. Every new (remote, proto, port) tuple lights up orange-reversed for 3 seconds. Listening sockets stay dim, blocked sockets are red, trusted sockets green.
One-key block. Select the row, press b, and kage drops the IP into a dedicated inet kage nftables table (output + input chains). --persist writes the snippet under /etc/nftables.d/ so the rule survives a reboot. Falls back to iptables if nft isn't available.
Owner column. Every connection shows the owning process and PID by joining ss -tunaHp output with /proc/[pid] — including the user. Foreign-UID sockets stay listed but anonymous unless you run as root.
Privacy default. Public-IP lookup is OFF by default. Pass --doh to consent to a single DNS-over-HTTPS query to 1.1.1.1/whoami.cloudflare.
Headless mode. Five one-shot subcommands — snapshot, top, net, disk, connections — all support -o json for cron / SSH / pipe use.

TUI keybinds

Key	Action	Gate
`q / Esc`	Quit	—
`?`	Help modal	—
`Tab`	Toggle focus between Connections and Processes	—
`j / k`	Move selection in focused pane	—
`/`	Filter connections by text (proto / process / remote IP)	—
`p`	Pause sampling	—
`c / m / n / P`	Sort processes by cpu / mem / name / pid	—
`b`	Block selected remote IP via nftables	`--i-am-authorized`
`u`	Unblock selected remote IP	`--i-am-authorized`
`t`	Toggle trust list membership	—
`d`	Reverse-DNS lookup for selected remote IP	—
`K` (shift)	SIGTERM the owning process	`--i-am-authorized`

Subcommands

Command	What it does
`kage`	Fullscreen TUI dashboard (default)
`kage snapshot`	One-shot dump — host / cpu / memory / disks / network / connections / top procs
`kage top --by cpu\|mem\|pid\|name -n N`	Focused process table
`kage net`	Interfaces, public IP (with `--doh`), gateway
`kage disk`	Mounted block devices + IO rates
`kage connections [--filter X]`	Active TCP/UDP table, optionally filtered

Global flags

Flag	What it does
`--doh`	Allow Cloudflare DoH for public-IP lookup (OFF by default — privacy)
`--i-am-authorized`	REQUIRED for any write action (block / unblock / kill). Suite consent convention
`--full`	Show extended help (cheat-sheet, or per-subcommand worked examples)
`--persist`	Persist block rules to `/etc/nftables.d/kage.nft` (needs root)
`-o, --output text\|json`	Output format for one-shot subcommands
`--no-color`	Disable ANSI colour

On-disk layout

~/.config/kage/trust.json      # trusted IPs (silenced + green)
~/.config/kage/block.json      # session block list
/etc/nftables.d/kage.nft       # with --persist, root-owned

The KAGE_HOME env var overrides the default config dir. Block / kill writes are explicitly gated by --full; the trust list is editable without it.

Touches / Produces / Gates

Touches (read-only): /proc, /sys, /etc/passwd, ip, ss -tunaHp. With --doh, one HTTPS query to 1.1.1.1.
Touches (with --full): nft rules in the inet kage table, optionally /etc/nftables.d/kage.nft (with --persist), kill(2).
Produces: terminal output, JSON, persistent trust/block books.
Gates: --i-am-authorized required for any write action (block / unblock / kill). --persist additionally requires root (or CAP_NET_ADMIN) to write under /etc/. --full is display-only (extended help) and does not unlock any side effects.