Self-Hosting

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

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
• systemd (for the spawn daemon)

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-mcp migrate
vinculum-mcp run

Verify the install is editable:

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

Spawn daemon

The spawn daemon watches spawn_requests rows in the database and launches grunt sessions on your machine. Required when spawn_grunt needs to start a claude process on a workstation separate from the MCP server.

export VINCULUM_DATABASE_URL="postgresql://..."
./hooks/install-spawnd.sh

The installer auto-detects your platform:

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
# → {"status":"ok"}

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-mcp config --client=claude-code --write -y

Cross-platform notes

The spawn daemon runs on Linux and macOS via hooks/install-spawnd.sh. For Windows, use WSL2 — the daemon runs inside WSL2 and launches claude in WSL2 terminal panes. A native Windows path is tracked in issue #2839.

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-mcp migrate
systemctl --user restart vinculum-mcp