⟩ Documentation

Vigilus documentation

Everything you need to install, configure, and operate Vigilus in your homelab.

Introduction

Vigilus is a self-hosted, AI-powered homelab operations platform: a web dashboard, a conversational AI orchestrator, user-definable agents (called "Operators"), and an MCP server manager — shipped as a single deployable service.

It runs on your hardware, uses your LLM keys (or local models), and executes within permission boundaries you define. Everything is logged. Nothing runs without your rules.

Vigilus is built for homelab operators — people who run their own infrastructure and want AI assistance without sending their data to third parties or ceding control to a cloud service.

The mental model

Think of it as a four-layer stack:

  1. Orchestrator — the top-level router that receives your requests and dispatches them to the right Operator.
  2. Operators — sub-agents you define, each with its own prompt, model, tools, and permission level.
  3. Tools — the actions an Operator can perform (SSH, Docker, filesystem, etc.), sourced from MCP servers.
  4. RBAC & audit — every tool call passes through the policy engine and is recorded in an append-only log.

Key features

  • Self-hosted — runs on bare metal or Docker, single service.
  • Bring your own models — Anthropic, OpenAI, Google, Ollama, LM Studio, vLLM, OpenRouter, xAI, or any OpenAI-compatible endpoint.
  • User-defined Operators — no YAML, no CLI flags. Configure from the dashboard.
  • MCP-native — auto-discover tools from MCP servers on the host.
  • Just-In-Time (JIT) elevation — scoped, time-limited, signed tokens for write/exec actions.
  • Append-only audit log with secret redaction.
  • Interactive API docs at /docs (Swagger) and /redoc.

Quickstart

Prerequisites

  • A Linux host (bare metal or VM) with Docker, or Python 3.11+ for bare-metal installs.
  • An LLM API key from at least one supported provider.

Docker (recommended)

$ 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

Bare metal

Clone the repo and run the startup script:

$ git clone https://github.com/vigilus-labs/vigilus.git $ cd vigilus $ ./start.sh

The script creates a Python virtual environment, installs dependencies, and starts the FastAPI backend (which also serves the built React frontend). The app binds to 0.0.0.0:3000 by default.

First-run checklist

  1. Open http://localhost:3000 in your browser.
  2. Set a secret — the dashboard prompts you to set VIGILUS_SECRET on first launch. This key encrypts all stored credentials. Keep it safe — if it changes, existing API keys and SSH credentials can't be decrypted.
  3. Add a provider — go to Settings → Providers and add an LLM provider (e.g., Anthropic with your API key).
  4. Add a server — go to Servers and add an SSH host to manage.
  5. Talk to Vigilus — open the chat and ask it to check on your infrastructure.

Configuration

Vigilus is configured primarily through environment variables. The most important one is VIGILUS_SECRET — do not change it after first run, or you will lose access to all encrypted credentials.

Variable Default Description
VIGILUS_SECRET required Encryption key for all stored secrets (API keys, SSH credentials). Must remain stable across restarts.
VIGILUS_DATA_DIR ~/.vigilus Directory for the SQLite database, logs, and MCP config. Mapped to /data in Docker.
VIGILUS_HOST 0.0.0.0 Bind address for the HTTP server.
VIGILUS_PORT 3000 Bind port.
VIGILUS_DATABASE_URL SQLite SQLAlchemy async connection string. Use a PostgreSQL URL for production-like setups (e.g. postgresql+asyncpg://user:pass@host/vigilus).
VIGILUS_CORS_ORIGINS same-origin Comma-separated list of allowed CORS origins. Lock this down in production.

SQLite vs PostgreSQL

SQLite is the default and fine for single-user homelab use. The database file lives in your data directory. For setups with concurrent writes or if you want WAL-mode resilience, switch to PostgreSQL by setting VIGILUS_DATABASE_URL.

Database migrations run automatically via Alembic on startup — no manual migration steps needed.

Core concepts

Orchestrator

The Vigilus orchestrator is the core routing agent. When you send a message through the chat, the orchestrator determines which Operator is best suited for the task and dispatches it. You don't pick the Operator manually — the orchestrator reads each Operator's system prompt and tool assignments and routes accordingly.

The orchestrator itself is not configurable — it's the fixed top layer of the system. You control behavior by defining Operators and their capabilities.

Operators

An Operator is a user-defined sub-agent. Each Operator has:

  1. System prompt — instructions that define the Operator's behavior, scope, and personality.
  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 — the maximum privilege ceiling for this Operator's tool calls.

Configure Operators entirely from the web dashboard. No YAML files, no CLI flag salad. You might have one Operator for infrastructure monitoring, another for security scanning, another for patch management — each with different models and permission levels.

Tools

Tools are the actions an Operator can perform — SSH commands, Docker management, file operations, network scans, and more. Tools come from two sources:

  • MCP servers — external tool servers running on the host, auto-discovered by Vigilus.
  • Native tools — built-in tools shipped with Vigilus (SSH exec, Docker management, etc.).

You assign tools to Operators through the dashboard. An Operator can only use tools that are explicitly assigned to it.

Memory & Soul

Each Operator maintains conversational memory within a chat session. The Operator's "soul" — its system prompt — is always prepended to context, ensuring consistent behavior across interactions.

Permission levels & RBAC

Every tool call is classified by intent and checked against the Operator's permission level. Permission levels are hard ceilings — an Operator can never exceed its assigned level.

  • Read — always available. Logs, status, metrics, queries. No elevation required.
  • Write — modifies state. Requires JIT elevation.
  • Exec — runs commands. Requires JIT elevation.
  • Elevate — grants elevated access. Requires JIT elevation.

Write, Exec, and Elevate actions are gated behind the JIT system. They never execute silently without passing through the policy engine.

JIT & trust modes

JIT (Just-In-Time) elevation is the only path to exceed read-only permissions. When an Operator needs to perform a write or exec action, it requests a JIT token — scoped to a specific resource and action, time-limited, and HMAC-signed.

You choose the trust mode per Operator or globally:

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

JIT tokens are short-lived (configurable TTL), revocable, and resource-scoped — a token for restarting a Docker container can't be used to SSH into a server.

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.

Providers

Vigilus supports any provider that speaks the OpenAI API format, plus native integrations for Anthropic, OpenAI, Google, Ollama, LM Studio, vLLM, OpenRouter, and xAI. Configure providers in the dashboard with an API key and endpoint URL.

You can mix and match — a local Ollama model for routine checks, a cloud model for complex reasoning. Each Operator can use a different model from a different provider.

Servers & credentials

Vigilus can interact with your infrastructure via SSH and Docker. You manage server inventory, SSH credentials, and connection details from the dashboard. Credentials are encrypted at rest with AES via Fernet.

Scheduled tasks

You can schedule recurring tasks using cron expressions. Vigilus uses APScheduler to run tasks on schedule — for example, nightly security scans, weekly patch checks, or hourly health probes. Scheduled tasks are created from the dashboard and are subject to the same RBAC and JIT rules as interactive tasks.

Audit log

Every tool call — allowed or denied — is recorded in an append-only audit log. No opt-in, no configuration. Secrets are redacted before logging. The audit log is the source of truth for what happened, when, and why.

Guides

Connect your first server

  1. Generate an SSH key pair on the Vigilus host (if you don't already have one):
    $ ssh-keygen -t ed25519 -f ~/.ssh/vigilus_key -N ""
  2. Add the public key to the target server's authorized_keys:
    $ ssh-copy-id -i ~/.ssh/vigilus_key.pub user@your-server

    The key must be in ~/.ssh/authorized_keys on the target server, and the file must have correct permissions (600 for the file, 700 for ~/.ssh/).

  3. Add the server in Vigilus — go to Servers → Add Server. Enter the hostname, port, username, and paste the private key. Vigilus stores it encrypted.
  4. First connection — Vigilus uses trust-on-first-use (TOFU) for host keys. On the first SSH connection, the server's host key is pinned. If the host key ever changes, future connections will fail — this protects against MITM attacks.

Add an LLM provider

  1. Go to Settings → Providers → Add Provider.
  2. Select the provider type (e.g., Anthropic, OpenAI, Ollama).
  3. Enter your API key and (if applicable) a custom endpoint URL.
  4. Save. The provider is now available for Operators.

For local providers like Ollama or LM Studio, use the base URL (e.g., http://localhost:11434). No API key is required for most local providers.

Create an operator

  1. Go to Operators → Create Operator.
  2. Give it a name and a system prompt describing its purpose (e.g., "Monitor all infrastructure servers and report anomalies").
  3. Select a model from a configured provider.
  4. Assign tools from your MCP servers and native tool set.
  5. Set the permission level (read-only, read-write with JIT, etc.).
  6. Choose a JIT trust mode (strict or lenient).
  7. Save. The Operator is now available for the orchestrator to route tasks to.

Add an MCP server

You can add MCP servers in three ways:

  • npm package — provide the package name (e.g., @vigilus/mcp-nmap). Vigilus installs and runs it.
  • Command — provide a shell command that starts the MCP server. Useful for custom or local servers.
  • GitHub + JSON import — paste a GitHub repo URL or a JSON config block. Vigilus pulls and configures the server.

After adding an MCP server, restart Vigilus (or click "Rescan" in the dashboard). New tools from the server appear in the tool assignment panel.

Schedule a task

  1. Go to Scheduled Tasks → Create Task.
  2. Select an Operator to handle the task.
  3. Write the prompt (e.g., "Check disk usage on all servers and report any above 85%").
  4. Set a cron expression for the schedule (e.g., 0 2 * * * for 2 AM daily).
  5. Save. The task runs on schedule, subject to the same permissions and JIT rules as interactive tasks.

Use the chat

The chat is your primary interface to Vigilus. Type a natural-language request and the orchestrator routes it to the appropriate Operator.

  • Markdown — responses render as Markdown, including code blocks, tables, and lists.
  • @mentions — prefix a message with @operator-name to route it to a specific Operator instead of letting the orchestrator choose.
  • Stopping tasks — use the Stop button to cancel a running task. You can also view and manage running tasks from the running-tasks panel.
  • Restoring tasks — cancelled or completed tasks can be inspected and re-run from the task history.

Reference

Native tools catalog

Tool Required permission Description
ssh.exec Exec Execute a command on a remote server via SSH.
docker.list Read List containers on a Docker host.
docker.restart Write Restart a Docker container.
docker.logs Read Fetch logs from a Docker container.
docker.compose Write Manage Docker Compose stacks (up, down, pull).
filesystem.read Read Read a file from the Operator's working directory on the host.
filesystem.write Write Write a file to the Operator's working directory on the host.
shell.exec Exec Run a shell command on the Vigilus host, confined to the Operator's working directory.
nmap.scan Exec Run a network scan against a target range (via MCP nmap server).
wazuh.query Read Query Wazuh SIEM for alerts, logs, or vulnerability data.

Permission levels

Level Description JIT required?
Read Query state, read logs, list resources. No
Write Modify state — restart containers, write files, update configs. Yes
Exec Execute commands — SSH, shell, network scans. Yes
Elevate Grant elevated access beyond the current scope. Yes

Supported providers

  • Anthropic (Claude)
  • OpenAI (GPT-4, GPT-4o, etc.)
  • Google (Gemini)
  • Ollama (local models)
  • LM Studio (local models)
  • vLLM (local models)
  • OpenRouter (multi-provider gateway)
  • xAI (Grok)
  • Any OpenAI-compatible endpoint

Interactive API docs

Vigilus auto-generates an interactive API reference from the FastAPI schema. Access it at:

  • http://localhost:3000/docs — Swagger UI (try endpoints live)
  • http://localhost:3000/redoc — ReDoc (readable reference)

Security

Vigilus is designed to minimize trust and maximize observability. Here's how each layer is protected:

Layer Mechanism
Secrets at rest All stored credentials (API keys, SSH private keys) are encrypted with AES via Fernet. The encryption key is VIGILUS_SECRET — keep it stable and keep it safe.
RBAC policy engine Every tool call passes through the RBAC policy engine. Permission levels are hard ceilings — no Operator can exceed its assigned level. JIT is the only elevation path.
Audit log Append-only log of every tool call (allowed and denied). Secrets are redacted before logging. No opt-out.
JIT tokens HMAC-signed, short-lived (configurable TTL), revocable, and resource-scoped. A token for one action on one resource cannot be reused for another.
SSH host keys Trust-on-first-use (TOFU). Host keys are pinned on the first connection. If a host's key changes, connections fail. This prevents man-in-the-middle attacks.
Host filesystem / shell Host tools are confined to the Operator's working directory. Symlink- and traversal-safe — Operators cannot break out of their assigned directory.
CORS Locked to configured origins via VIGILUS_CORS_ORIGINS. Default is same-origin only.

Troubleshooting / FAQ

"SSH authentication failed"

Check the following:

  • The SSH public key is in the target server's ~/.ssh/authorized_keys.
  • File permissions are correct: 700 ~/.ssh/ and 600 ~/.ssh/authorized_keys.
  • The private key you entered in Vigilus matches the public key on the target.
  • The target server's SSH daemon is running and allows key-based auth.

"Host key verification failed"

This means the target server's SSH host key has changed since the first connection (Vigilus uses trust-on-first-use). If this is expected (e.g., you reinstalled the OS), remove the old host key from Vigilus's known hosts and reconnect. If it's unexpected, investigate potential MITM interference before proceeding.

"Stored API key can't be decrypted"

This happens when VIGILUS_SECRET has changed since the credential was stored. The encryption is one-way — you can't recover the old key. Re-enter the API key in the provider settings with the current secret.

"A task is running away"

Use the chat Stop button to cancel the task immediately. You can also open the running-tasks panel from the dashboard to view and cancel active tasks.

"MCP server tools aren't appearing"

  • Make sure the MCP server process is running on the host.
  • Click "Rescan" in the MCP servers section of the dashboard, or restart Vigilus.
  • Check that the server's command/path is correct and executable.