Guides
Run as a service
serve runs the scanner continuously. It re-scans on an interval, pulls events from connectors you configure, applies a policy, writes a journal, and can expose a small local HTTP API.
#Start it
PYTHONPATH=/path/to/kelvar/python python3 -m vigil.cli serve ./your-repo \
--connectors ./connectors \
--interval 300 \
--api-port 8787| Flag | Default | Meaning |
|---|---|---|
path | . | The folder to watch. |
--agent NAME | codebase-guardian | A built-in agent to run. Repeat the flag to run several. |
--connectors DIR | ./connectors in the watched folder | A folder of connector JSON files. |
--interval N | 300 | Seconds between ticks. |
--api-host | 127.0.0.1 | Address the API binds to. |
--api-port N | 0 | Port for the API. 0 leaves the API off. |
--once | off | Run one tick and exit. Exits with status 1 if the tick blocked. |
#What a tick does
Each tick polls every connector, runs the agents' checks on the folder, and applies your policy. A connector item at or above the block threshold becomes a block action, and so does a finding at or above it. Items at or above the alert threshold become alerts. Each outcome is written to the journal.
A tick that blocks prints BLOCK with the reason. With --once, the command then exits with status 1, so you can use serve --once as a gate that also covers connector signals.
#Policy
Drop a .vigil/policy.json in the watched folder to set thresholds.
{
"block_at_severity": "high",
"alert_at_severity": "medium"
}Both default to the values shown. A policy file that is not valid JSON is ignored, and the defaults apply. See Configuration.
#The journal
Every tick appends to .vigil/journal.jsonl in the watched folder. Each row is one JSON object with a kind.
| Kind | Meaning |
|---|---|
tick | A tick ran. |
finding | A check produced a finding. |
insight | A connector item or a webhook produced an insight. |
action | The policy decided to alert or block. |
kernel-error | Something failed. The error is recorded and the tick continues. |
Print a 24-hour roll-up at any time.
PYTHONPATH=/path/to/kelvar/python python3 -m vigil.cli summary ./your-repo#Connectors
A connector is a JSON file that describes an HTTP source. On every tick, Kelvar fetches it and turns each item into an insight. Connectors only read. A connector that fails produces an error insight and the tick carries on. See Configuration for the connector schema.
#The HTTP API
With --api-port set, the service answers on the host and port you chose. See the API reference for endpoints.
#Run it under a supervisor
serve is a plain foreground process. Run it under launchd on macOS or systemd on Linux so that it restarts on failure, and send its output to your log system.
#Watch mode
For local development, watch re-scans when files change. It polls the folder about every two seconds and prints a report after each change.
PYTHONPATH=/path/to/kelvar/python python3 -m vigil.cli watch ./your-repo