Installation

Vigo has three components: the server (vigosrv), the CLI (vigocli), and the agent (vigo). The server and CLI ship as a container image. The agent is installed on each managed machine via a bootstrap script.

Server

1. Seed the data directory

sudo mkdir -p /srv/vigo
docker run --rm -v /srv/vigo:/srv/vigo ghcr.io/daniel-alexander4/vigo:latest --seed-only

This populates /srv/vigo/ with everything needed to run the server:

/srv/vigo/
├── docker-compose.yml       # production compose file
├── server.yaml              # server config
├── .env                     # non-secret env vars
├── tls/                     # mTLS certificates (auto-generated)
├── license/                 # license .lic files
├── db/                      # SQLite database
├── secrets/                 # encrypted secret files
├── stockpile/               # edit .vgo config files here
│   ├── modules/
│   ├── roles/
│   ├── envoys/
│   ├── templates/
│   └── vars/
├── .live/                   # published config (do not edit directly)
├── config-history/          # rollback snapshots
├── example-configs/                # example .vgo modules, roles, and nodes
└── docs/                    # browsable documentation

2. Start the server

cd /srv/vigo
docker compose up -d

The server starts on ports 1530 (gRPC, agent check-in) and 8443 (HTTPS — REST API, web UI, metrics, bootstrap). On first access, the web UI shows setup instructions — create an admin account with vigocli webusers create --username admin --role admin and set a password with vigocli secrets set web vigo/web/auth/admin, then sign in at https://localhost:8443/login.

3. Verify

docker compose ps                    # container running
curl -sk https://localhost:8443/healthz # health check
vigocli doctor                     # full diagnostic

Optional services

Edit VIGO_SERVICES in /srv/vigo/.env to enable optional containers:

# In .env, uncomment one of:
VIGO_SERVICES=ollama              # local AI assistant (free, CPU-only)
VIGO_SERVICES=postgres            # Postgres instead of SQLite
VIGO_SERVICES=ollama,postgres     # both

Timezone

The container inherits the host's timezone via a read-only mount of /etc/localtime. All timestamps in the web UI, reports, and audit logs display in the server's local timezone. If you need to override the timezone, set the TZ environment variable in .env:

TZ=America/New_York

Configuration

Edit server.yaml for server settings (check-in interval, TLS paths, spanner, SMTP, webhooks). Edit .env for optional services and environment variables. See Server Configuration for the full reference.

Upgrading

cd /srv/vigo
docker compose pull
docker compose up -d

Your config, database, secrets, and TLS certs persist in /srv/vigo/ across upgrades.

CLI

The container automatically installs vigocli to /usr/local/bin on the host via the /host-bin volume mount. If the mount is not configured, install manually:

docker cp vigo:/usr/local/bin/vigocli /usr/local/bin/vigocli

The CLI auto-detects the server at https://localhost:8443. For remote servers:

export VIGO_SERVER="http://vigo-server:8443"

Agent

The agent runs on managed machines (envoys). It supports Linux, macOS, FreeBSD, OpenBSD, NetBSD, illumos, and Windows.

Linux

curl -sSfk https://<server>:8443/bootstrap | sudo sh

Downloads the agent binary, generates a keypair, registers with the server, and installs a systemd service (vigo-envoy).

macOS

curl -sSfk https://<server>:8443/bootstrap | sudo sh

Detects macOS and installs a launchd plist (com.vigo.envoy).

FreeBSD / NetBSD

curl -sSfk https://<server>:8443/bootstrap | sudo sh

Installs an rc.d service script at /usr/local/etc/rc.d/vigo_envoy.

OpenBSD

curl -sSfk https://<server>:8443/bootstrap | sudo sh

Registers the service via rcctl and enables it at boot.

illumos

curl -sSfk https://<server>:8443/bootstrap | sudo sh

Imports an SMF service manifest and enables it via svcadm.

Windows

# PowerShell 7+
irm https://<server>:8443/bootstrap?os=windows -SkipCertificateCheck | iex

# PowerShell 5
[Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}; irm https://<server>:8443/bootstrap?os=windows | iex

Downloads the agent, registers with the server, and installs a Windows service. The cert-skip flags are the equivalent of curl's -k for the self-signed CA.

See Bootstrap for details on the enrollment flow, token-based authentication, and trusted enrollment patterns.

Ports

Port	Protocol	Purpose
1530	gRPC (mTLS)	Agent check-in, result reporting, streaming
8443	HTTPS	REST API, web UI, metrics, bootstrap

Agent directory layout

/etc/vigo-envoy/            # config + identity
├── envoy.uuid                # registration ID
├── certs/                     # TLS keypair
│   ├── ca.crt
│   ├── tls.crt
│   └── tls.key
└── executors/                 # custom executor scripts

/var/lib/vigo/               # persistent state
├── state/                     # LMDB (policy cache, checksums, traits, pending results)
├── snapshots/                 # file snapshots for rollback
└── flags/                     # flag markers for when: expressions

---