Running token custody with Nango

Self-hosting can sound heavier than it is. In this architecture, it means the credential-bearing system runs where you choose: a VM, a VPC, or the same cloud environment where the rest of your product already lives.

This is the practical setup path for the Nango layer CybrLink expects.

What you need before you start

• A small VM with a public IP. 1 vCPU / 2 GB RAM is fine for tens of thousands of connections.
• Postgres. Use whatever you already have — Supabase, RDS, the Postgres your app already uses.
• A subdomain you can point at the VM. We'll use nango.example.com.
• Docker. That's it.

Step 1 — pull Nango

mkdir nango && cd nango
curl -L https://nango.dev/install.sh | bash

This drops a docker-compose.yml, an .env.template, and an nginx.conf into the directory.

Step 2 — wire your .env

NANGO_DB_HOST=your.postgres.host
NANGO_DB_USER=nango
NANGO_DB_PASSWORD=<generate-something-real>
NANGO_DB_NAME=nango
NANGO_DB_SSL=true
NANGO_SERVER_URL=https://nango.example.com
NANGO_SECRET_KEY=<generate-something-real>

Generate the two secrets with openssl rand -hex 32. Write them down somewhere your future self will find them.

Step 3 — point DNS, get TLS

A plain Caddy block does both:

nango.example.com {
  reverse_proxy localhost:3003
}

Caddy will fetch a Let's Encrypt cert on the first request. Don't fight it.

Step 4 — boot

docker compose up -d

Watch the logs once (docker compose logs -f) until you see Nango listening. Then close the SSH session and never look at it again.

Step 5 — connect CybrLink

In your CybrLink dashboard (or your .env if you're self-hosting both):

NEXT_PUBLIC_NANGO_API_URL=https://nango.example.com
NEXT_PUBLIC_NANGO_CONNECT_URL=https://nango-connect.example.com
NANGO_SECRET_KEY=<the-secret-from-step-2>

Now mint a session token from a CybrLink API call and the Connect UI redirects users through your Nango setup, meaning provider credentials land in your database.

What happens when you upgrade

git pull
docker compose pull
docker compose up -d

That's it. Migrations run automatically; sessions don't drop because Nango is stateless behind the load balancer; the database does the persistence.

What happens when it breaks

Two things break, in our experience:

1. OAuth callback URL mismatch. Every provider needs to know your exact redirect URL. Nango logs the mismatch in plain English — read the log, fix the URL on the provider side.
2. Clock drift. If your VM's clock drifts more than a minute, JWT signatures fail. Run chronyd. Don't argue with it.

That's the whole runbook. The point is not drama; it is custody. Your team can now answer where provider credentials live and who operates that layer.

Browse the integrations catalog, or skip ahead to the SDK quickstart.