Skip to content
Payvy

Deploying

Self-hosting is free under AGPL-3.0-only: no license charge, no per-seat fee, no payment markup. You operate the infrastructure, storage, AI provider and bank relationship. This page describes the shape; the source repo (Dockerfile, docker-compose) is the working reference.

The pieces

Section titled “The pieces”
  • App: one server process (the Dockerfile’s app target). It applies database migrations at startup and serves the API, MCP endpoint, webhooks, and — with PAYVY_WEB_DIR set — the built web app.
  • Database: Postgres. Isolation between organizations relies on row-level security, so the app role must own the database but not be a superuser, or RLS won’t hold.
  • Documents: an S3-compatible bucket you control (see Configuration).
  • Ingress: put the app behind a reverse proxy with TLS. /webhooks/email must be reachable from the internet if you use email intake (a Cloudflare Tunnel also works).

Secrets you must keep

Section titled “Secrets you must keep”

Generate with openssl rand -hex 32 and store in your password manager, not in the repo:

  • PAYVY_API_KEY and PAYVY_INBOUND_SECRET (32+ characters each)
  • PAYVY_SECRETS_KEY — seals bank tokens. Losing it means reconnecting every bank. Losing the database without it pays no one, which is the point.
  • Your S3, model-provider, and mail-sender credentials

Before you pay real bills

Section titled “Before you pay real bills”
  1. Create the first person (payvy person add --email … --name …) and sign in.
  2. Create your inbound address (email.new_address) and send a test bill.
  3. Connect Mercury in request mode first (second sign-off inside Mercury) and pay a small bill end to end; switch to direct only deliberately, with the server IP on the token’s allowlist.
  4. Score your extraction model (payvy extract-eval fixtures/invoices) before letting drafts flow unattended.

Backups & upgrades

Section titled “Backups & upgrades”

Back up Postgres and the document bucket together — bills reference documents by content hash, and either alone is half a record. Retention and access on the bucket are yours, as they were for your filing cabinet. Upgrade by deploying a new build: migrations run at startup, and workflow versions pinned by in-flight bills are unaffected by workflow edits.