Self-Hosting

Vinculum is AGPL v3. This guide gets you from zero to a running self-hosted instance — copy-pasteable and end-to-end.

Self-hosted installs receive the product app (dashboard, MCP server, runner) only — the marketing and pricing pages at vinculum.run are not included and are not needed.

Prerequisites

Docker path (recommended for teams)

• Docker ≥ 24 and Docker Compose v2
• A domain name with TLS termination (Caddy or Traefik work well)
• 1 GB RAM minimum, 2 GB recommended
• A GitHub OAuth app — create one at github.com/settings/developers

Bare-metal path

• Ubuntu 22.04 or 24.04 (or equivalent Linux with systemd)
• Python 3.12+ and uv
• Node.js 22 and pnpm
• PostgreSQL 17 with the pgvector extension

Quick path — Coolify

If you use Coolify for self-hosted app management:

1. Add resource → Docker Compose → from GitHub
2. Repository: whalefall-media/vinculum
3. Set the required env vars (see below)
4. Deploy — Coolify runs docker compose up -d

The compose file includes a PostgreSQL 17 service with pgvector pre-loaded. Migrations run automatically on first boot.

Manual path — Docker Compose

git clone https://github.com/whalefall-media/vinculum.git
cd vinculum
cp env.example .env

Edit .env — at minimum:

VINCULUM_DATABASE_URL=postgresql://vinculum_app:changeme@db:5432/vinculum
VINCULUM_BASE_URL=https://your-domain.example.com
VINCULUM_GITHUB_CLIENT_ID=<your-github-oauth-app-client-id>
VINCULUM_GITHUB_CLIENT_SECRET=<your-github-oauth-app-client-secret>
VINCULUM_JWT_SECRET=$(openssl rand -hex 32)

Then start:

docker compose up -d

The server starts on port 31415. Point your reverse proxy at it.

Caddy reverse proxy

your-domain.example.com {
    reverse_proxy localhost:31415
}

nginx reverse proxy

server {
    listen 443 ssl;
    server_name your-domain.example.com;

    location / {
        proxy_pass http://127.0.0.1:31415;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_buffering off;
    }
}

Manual path — bare metal

git clone https://github.com/whalefall-media/vinculum.git
cd vinculum
uv pip install -e .
cp env.example .env
# edit .env
vinculum migrate
vinculum run

Verify the install is editable:

cat ~/.local/lib/python*/site-packages/vinculum_run-*.dist-info/direct_url.json
# Should show: "dir_info": {"editable": true}

Spawn runner

Spawning is runner-only. spawn_grunt enqueues a spawn_request row that a paired vinculum-runner — a small Go binary on the machine where grunts should execute — claims and runs. The runner long-polls the server over outbound HTTPS (/runner/poll); there is no in-process Popen path, no host-shim, and no daemon to install.

Pair a runner by generating a token (generate_pairing_token MCP tool, or Settings → Runners → Connect a runner in the dashboard) and running the install one-liner it emits:

# Linux / macOS native install (registers a start-at-login unit)
curl -fsSL https://vinculum.run/install.sh | sh

# Or via Docker (any OS)
docker run -d --restart unless-stopped --name vinculum-runner \
  -e VINCULUM_PAIRING_TOKEN=<your-token> \
  ghcr.io/whalefall-media/vinculum-runner:latest

Environment variables

Required

AI intelligence (optional, but recommended)

Server tuning

Auth extras

Billing (hosted tiers only)

Leave unset to disable Stripe entirely. Self-hosted installs don't need these.

Infrastructure tools

All default to false. Enable to unlock MCP tools for inspecting your infrastructure from a Claude session.

Verifying the install

curl http://localhost:31415/healthz
# → {"ok": true, "service": "vinculum"}

curl -X POST https://your-domain.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}'
# → {"jsonrpc":"2.0","result":{"protocolVersion":"2024-11-05",...}}

cd ~/your-project
uvx vinculum-run config --client=claude-code --write -y

After deployment, the dashboard MetricStrip shows live health — branch counts, active sessions, and entry velocity at a glance.

Cross-platform notes

The vinculum-runner ships native installers for Linux, macOS, and Windows, plus a Docker image that runs anywhere. There is no platform-specific daemon — the runner is the single spawn path on every OS.

Backup and restore

# Backup
pg_dump -Fc "$VINCULUM_DATABASE_URL" > vinculum_$(date +%Y%m%d).dump

# Restore to a fresh database
createdb vinculum
pg_restore -d "$VINCULUM_DATABASE_URL" vinculum_20260101.dump

Upgrading

Docker Compose

cd vinculum
git pull
docker compose pull
docker compose up -d

Migrations run automatically on startup.

Bare metal

cd vinculum
git pull
uv pip install -e .
vinculum migrate
systemctl --user restart vinculum-mcp