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.

Install

Three commands, and there are no prerequisites. No Docker, no Node, no repo checkout, and no database to go find.

curl -fsSL https://vinculum.run/install/server | sh
vinculum init                 # guided setup, ~2 min
vinculum run                  # listens on 127.0.0.1:31415

The first command installs uvif you don't have it, then Vinculum as a uv tool. It resolves the wheel from the published manifest and verifies its SHA-256 before installing — a curl | shthat pulls a binary and doesn't check it is one compromised object away from running someone else's code.

vinculum init sets up a built-in PostgreSQL 16 with pgvector, shipped as a platform wheel. It stores data under ~/.local/share/vinculum/pgdata and listens on a private UNIX socket, so no TCP port is opened for it. Then open http://127.0.0.1:31415/login — it signs you straight in — and connect Claude Code:

vinculum config --client=claude-code --write -y

Using your own PostgreSQL

An option, not a step. Set VINCULUM_DATABASE_URL before init and it uses that instead — 15 or newer, 17 recommended; pgvector is optional and only the semantic-search half needs it. Neon, Supabase, RDS and a local install all work.

export VINCULUM_DATABASE_URL=postgresql://user:pass@host:5432/vinculum
vinculum init

Connect as a superuser or a CREATEROLE role for init: it creates the six vinculum_* roles that background jobs and operator routes SET ROLE into. A least-privilege managed role can run Vinculum afterwards but cannot bootstrap it. Run vinculum doctor after init — it checks for exactly this.

Other paths

Docker and a from-source build are supported, but neither is the recommended route and both are more work than the one-liner. They also need the repository, which is not public yet — so the clone below will not work for you today. It is documented for operators who already have the source.

Docker Compose (from source)

cd vinculum      # the repo is not published yet — see above
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

cd vinculum      # the repo is not published yet — see "Other paths"
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 | bash

Environment variables

Required for a public, multi-user install

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