AI-augmented monitoring configuration for Prometheus, Alertmanager, and Grafana.
MonVisor scans a network, fingerprints the services it finds, lets you approve what to monitor, and generates Prometheus/Alertmanager/rules YAML — using a local RAG knowledge base and a local Ollama model. Everything runs locally; no data leaves the host and there is no API cost.
Status: free-tier CLI is functional (discovery → review → generate → reports, plus an optional web review UI and nginx config). Deploy/Grafana automation is the paid tier and not yet implemented.
Latest release:[v0.1.0]·[all releases]
scan ──▶ review ──▶ generate ──▶ (deploy: paid)
│ │ │
nmap yes/no per RAG + Ollama draft rules.yml;
+ HTTP service deterministic prometheus.yml
probe
- Python 3.11+
nmapon
PATH
(service discovery)curl
andzstd
(needed to install Ollama)Ollamarunning locally, with:- an LLM (default
gemma4:latest
) - the embedding model
nomic-embed-text:latest
- an LLM (default
- ~12–15 GB free disk for the models
promtool
(optional) for config validation
Latest release: v0.1.0 — download
monvisor-0.1.0-install.tar.gz
from the releases page, then:
tar xzf monvisor-0.1.0-install.tar.gz
cd monvisor-0.1.0-install
python3 install.py
The tarball bundles the installer, the wheel, this guide, and the license — no clone or further downloads needed. The rest of this section covers installing from a clone or by hand.
The fastest path is the bundled installer. It checks and installs the system prerequisites (nmap, curl, zstd, python venv), installs and starts Ollama and pulls the models, creates a virtualenv, installs MonVisor, and runs first-time setup — all in one go:
python3 scripts/install.py
It installs MonVisor from the published GitHub release wheel when available. If there is no release yet (or you're working from a clone), build the wheel first so the installer has something local to fall back to:
pip install build # one-time, if not already present
python3 -m build # creates dist/monvisor-*.whl
python3 scripts/install.py # finds and installs the local dist/ wheel
Flags: --no-sudo
(skip system packages), --no-models
(skip pulling Ollama
models), --no-init
(install only), --install-ollama
/ --no-install-ollama
(control the Ollama install prompt), --venv PATH
, --wheel PATH
.
To do everything by hand instead, follow the four steps below. For a fuller walkthrough (every prerequisite, plus troubleshooting), see INSTALL.md.
MonVisor is a Python package. The full install is three parts: system tools, a running Ollama with two models, then the package itself.
sudo dnf install python3 python3-pip nmap curl zstd
sudo apt install python3 python3-pip python3-venv nmap curl zstd
nmap
must be on your PATH
(scanning depends on it). curl
and zstd
are needed to install Ollama in the next step — the Ollama installer is zstd-compressed and fails without it. Python 3.11+ is required.
init
, ask
, and generate
all use a local Ollama instance, and init
builds embeddings from the bundled knowledge, so the models must be pulled before you initialize.
ollama serve & # start the server if it isn't already running
ollama pull gemma4 # the LLM (default model)
ollama pull nomic-embed-text # the embedding model — REQUIRED, init fails without it
Ollama listens on http://localhost:11434
by default. Point MonVisor elsewhere
with MONVISOR_OLLAMA_URL
or monvisor config set ollama-url <url>
.
Use a virtual environment to keep dependencies isolated:
python3 -m venv ~/.venvs/monvisor
source ~/.venvs/monvisor/bin/activate
pip install monvisor-0.1.0-py3-none-any.whl
pip install monvisor-0.1.0.tar.gz
pip install .
pip install -e .
This installs the monvisor
command. The knowledge base (RAG corpus + reference
configs) ships inside the package, so there is nothing else to download —
monvisor init
is fully self-contained. (Developers can override the corpus
with MONVISOR_CORPUS
/ MONVISOR_EXEMPLARS
.)
monvisor init
This creates ~/.monvisor/
(database, vector store, reports, configs), loads
the bundled knowledge into the RAG store (embedding takes a minute), and sets a
password for the web UI. Re-running init
cleanly reloads the knowledge;
monvisor init --reset-knowledge
forces a fresh rebuild.
Verify it worked:
monvisor knowledge status # should report 231 pairs loaded
monvisor ask "How do I run a scan?"
To leave the activated environment, run deactivate
(or just close the terminal).
To run monvisor
from any shell without activating the venv each time, add an
alias to ~/.bashrc
(or ~/.zshrc
):
alias monvisor="$HOME/.venvs/monvisor/bin/monvisor"
This is preferable to auto-activating the venv on login, which would also change
which python
/pip
the rest of your shell uses. See INSTALL.md for details.
After monvisor init
(see Install above):
monvisor env add prod 192.168.1.0/24 # register a network as 'prod'
monvisor scan prod # discover + fingerprint services
monvisor review prod # approve services to monitor (y/b/n/s/a/q)
monvisor generate prod # build prometheus.yml + rules.yml
monvisor ui prod # optional web review UI (localhost:7373)
monvisor nginx prod # optional reverse-proxy config
Outputs are written under ~/.monvisor/
(reports/
, configs/
).
MonVisor has a built-in assistant that answers from its local knowledge base — both how to use MonVisor and Prometheus/Alertmanager/Grafana questions:
monvisor ask "How do I run a scan?"
monvisor ask "show me a node_exporter scrape config"
monvisor ask "How do I report a bug?"
Answers come only from the bundled knowledge (no internet). If a question isn't
covered, MonVisor says so and points you to the issue tracker rather than
guessing. Add --show-sources
to see which knowledge snippets were used.
| Env var | Purpose | Default |
|---|---|---|
MONVISOR_HOME |
||
| Data directory | ~/.monvisor |
|
MONVISOR_OLLAMA_URL |
||
| Ollama endpoint | http://localhost:11434 |
|
MONVISOR_PORT |
||
| Web UI port | 7373 |
|
MONVISOR_CORPUS |
||
| Override RAG corpus path (dev) | bundled | |
MONVISOR_EXEMPLARS |
||
| Override exemplar dir (dev) | bundled |
Free (CLI): CIDR scan + fingerprinting, terminal + HTML reports, web review UI, Prometheus/Alertmanager/rules generation, blackbox fallback for un-instrumentable hosts, exporter recommendations, RAG knowledge updates.
Professional (planned): SSH config deploy, Grafana dashboard provisioning, AI-generated dashboards, Grafana-native review UI, enterprise auth (LDAP, Duo, AWS IAM, SAML).
pip install -e .
python -m build # build sdist + wheel into dist/
MonVisor (the application) is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later) — see LICENSE.
The bundled knowledge base (monvisor/knowledge/
) comes from the separate MonVisor-Corpus project and is licensed CC BY-SA 4.0. The two licenses apply to their respective parts.