⟩ Documentation

Getting started with Vigilus

Overview

Vigilus is a self-hosted, AI-powered operations platform for homelabs. It runs on your hardware — bare metal or Docker — and uses AI agents to monitor, manage, and operate your infrastructure.

At its core is the Vigilus orchestrator, a routing agent that dispatches tasks to Operators — user-defined sub-agents you configure with a system prompt, a model, a set of tools, and a permission level.

You bring your own models (Anthropic, OpenAI, Google, Ollama, LM Studio, vLLM, OpenRouter, xAI, or any OpenAI-compatible endpoint). You define the Operators. You set the permissions. Vigilus executes within those bounds and logs everything.

Quickstart

The fastest way to get running is Docker:

$ docker run -d \ --name vigilus \ -p 3000:3000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/.vigilus:/data \ ghcr.io/vigilus-labs/vigilus:latest

Or install bare metal with the install script:

$ curl -fsSL https://vigilus.dev/install.sh | sh

Once running, open http://localhost:3000 to access the web dashboard. From there you can configure providers, create Operators, and connect your infrastructure.

Architecture

Vigilus follows a simple hierarchy: Vigilus orchestrator → Operators → Tools.

  • Vigilus is the core orchestrator. It receives tasks, determines which Operator is best suited, and routes accordingly.
  • Operators are sub-agents you define. Each has its own system prompt, model, tool assignments, and permission level. You might have one Operator for infrastructure monitoring, another for security scanning, another for patch management.
  • Tools are the actions an Operator can perform — SSH commands, Docker management, SIEM queries, file operations. Tools come from MCP servers running on the host.

Operators

An Operator is defined by four things:

  1. System prompt — instructions that define the Operator's behavior and scope.
  2. Model — which LLM to use. Any configured provider, local or cloud.
  3. Tools — which MCP server tools the Operator has access to.
  4. Permission level — what the Operator is allowed to do (read-only, read-write with JIT, etc.).

Operators are configured entirely from the web dashboard. No YAML files, no CLI flag salad.

MCP servers

Vigilus is MCP-native. MCP (Model Context Protocol) servers run on the host and expose tools that Vigilus auto-discovers. Once discovered, you assign tools to Operators through the dashboard.

Common MCP servers include:

  • nmap — network scanning and discovery
  • WireGuard — VPN tunnel management
  • filesystem — host file read/write operations
  • Wazuh — SIEM integration (alerts, logs, vulnerabilities)
  • Docker — container and compose stack management

Install an MCP server on the host, restart Vigilus, and its tools appear for assignment.

Permissions and Just-In-Time access

Every tool call is classified by intent:

  • Read — always available. Logs, status, metrics, queries.
  • Write / Exec / Elevate — gated behind JIT. Requires a scoped, time-limited, signed token.

JIT operates in two modes:

  • Strict — every elevation request holds in the dashboard for manual approval. Approve or deny. Nothing runs without you.
  • Lenient — elevation requests are auto-approved and logged. Review after the fact in the action log.

You choose the mode per Operator or globally.

Audit log

Every tool call — allowed or denied — is recorded in an append-only action log. No opt-in, no configuration. Secrets are encrypted at rest and never exposed in logs or the dashboard.

The audit log is the source of truth for what happened, when, and why. Use it to review Operator behavior, investigate incidents, or validate that your permission boundaries are working.

Model providers

Vigilus supports any provider that speaks the OpenAI API format, plus native integrations for:

  • Anthropic
  • OpenAI
  • Google
  • Ollama
  • LM Studio
  • vLLM
  • OpenRouter
  • xAI

Configure providers in the dashboard with an API key and endpoint URL. Assign a different model to each Operator based on the task — a local model for routine checks, a cloud model for complex reasoning.

Infrastructure connections

Vigilus can interact with your infrastructure directly:

  • SSH — run commands on remote servers (e.g. apt update && apt upgrade across Ubuntu hosts).
  • Docker — manage containers, compose stacks, and volumes on the host or remote Docker daemons.
  • Wazuh SIEM — query alerts, logs, and vulnerability data from your Wazuh instance.
  • Host — act directly on the machine Vigilus is running on via the filesystem and shell MCP servers.

Server inventory, SSH credentials, and connection details are all managed from the dashboard.