Get started
Deploy Keyring to Unkey Deploy
This guide puts Keyring on Unkey Deploy (Unkey's docs also call it Unkey Compute), connected to a Postgres database you host elsewhere. At the end, Keyring runs at an unkey.app URL and your auth provider sends it every sign-up.
You need:
- An Unkey account with a Compute plan. Unkey needs a plan before it deploys anything.
- A Postgres database. Unkey Deploy has no managed database and no persistent disk.
- For the GitHub path, a GitHub account and your own fork of
unkeyed/keyring.
1. Create the database
Create a Postgres database with any managed provider, such as Neon, Supabase, PlanetScale Postgres, or Amazon RDS. Pick a region close to the Unkey region you plan to use. Unkey runs in us-east-1 by default.
Copy the connection URL. Most managed providers require TLS, so keep sslmode=require if the provider includes it:
postgres://keyring:secret@ep-example-123.us-east-1.aws.neon.tech/keyring?sslmode=require
Keyring creates its tables the first time it starts. You do not run any SQL yourself.
2. Create the Unkey project
In the Unkey dashboard, open Projects and click Create project. Note the project's slug. The CLI path in step 4 uses it.
3. Set the environment variables
Unkey stores variables per environment. Set these on the production environment of your project. Mark every secret as Sensitive.
| Variable | Value |
|---|---|
DATABASE_URL |
The connection URL from step 1. Sensitive. |
ENCRYPTION_KEY |
32 random bytes from openssl rand -base64 32. Sensitive. Keep a copy elsewhere: Unkey cannot show a write-only value again, and Keyring cannot read its stored secrets without it. |
CLIENT_IP_HEADER |
X-Forwarded-For. Unkey replaces that header with the client's address, so Keyring throttles each client on its own instead of everyone behind Unkey's gateway at once. |
MIGRATION_DATABASE_URL |
Optional. Only if the role in DATABASE_URL cannot create tables, as with PlanetScale Postgres's read/write role: a URL for a role that can. Sensitive. Or leave it out and run keyring migrate with it yourself before each deploy that adds a migration. See Configuration. |
PUBLIC_URL |
Your deployment's URL from step 6, such as https://keyring-acme.unkey.app. Set it after the first deploy and redeploy. |
SETUP_TOKEN |
32 or more random characters, for example from openssl rand -hex 32. Sensitive. You open the setup link with it in step 6. |
CONTEXT_DEV_API_KEY |
Optional. Your context.dev key, which turns on enrichment. Sensitive. |
ENRICHMENT_DAILY_LIMIT |
Optional. The most context.dev lookups per day, 200 by default. |
UNKEY_ROOT_KEY |
Optional. See Store API keys in Unkey. Sensitive. |
UNKEY_API_ID |
Optional. Set it together with UNKEY_ROOT_KEY. |
Do not set PORT. Unkey sets it, and Keyring listens on it.
Unkey applies a variable change only to the next deployment. After you change a variable, redeploy. Configuration describes each variable in full.
4. Deploy Keyring
Choose one of the two paths. The GitHub path rebuilds on every push. The image path deploys a published release and needs no fork.
Deploy from GitHub
- Fork
unkeyed/keyringon GitHub. - In your Unkey project, deploy a new app from a GitHub repository. Install the Unkey GitHub App when Unkey asks, and pick your fork.
- In the app's build settings, set the Dockerfile path to
Dockerfile. Without a path, Unkey tries to detect the build on its own instead of using Keyring's Dockerfile. - Deploy.
From now on, each push to your fork's default branch deploys to production. Pushes to other branches create preview deployments.
Preview deployments use the preview environment and its own variables. If you set DATABASE_URL on preview, use a separate database. A preview that points at the production database applies its migrations to production data.
Deploy the prebuilt image
The image ghcr.io/unkeyed/keyring is public. Each release is tagged with its version, for example 0.1.0, and the newest release is also latest.
Install the Unkey CLI and log in:
npm install -g unkey unkey loginDeploy the image to production. Replace
<project-slug>with the slug from step 2:unkey deploy ghcr.io/unkeyed/keyring:latest --project=<project-slug> --env=productionWithout
--env=production, the CLI deploys to the preview environment.
To upgrade later, run the same command with a newer version tag.
5. Add the health check
In the environment's runtime settings, add a health check with method GET and path /healthz. Unkey then sends traffic to an instance only after /healthz answers 200, and restarts an instance that stops answering.
/healthz checks only that the process runs. It does not query the database, so a database outage does not restart every instance.
You can also set the health check through Unkey's API. Replace keyring and default with your project and app slugs:
curl -X POST https://api.unkey.com/v2/environments.updateSettings \
-H "Authorization: Bearer $UNKEY_ROOT_KEY" \
-H "Content-Type: application/json" \
-d '{"project":"keyring","app":"default","environment":"production","healthcheck":{"method":"GET","path":"/healthz"}}'
Redeploy after you add the health check.
6. Create the first account
Find your deployment's URL. Unkey shows it on the deployment page. It has the form https://<project>-<workspace>.unkey.app, or https://<project>-<app>-<workspace>.unkey.app when the app slug is not default. If PUBLIC_URL is not that URL yet, set it and redeploy, because passkeys only work at the URL in PUBLIC_URL.
Open <PUBLIC_URL>/setup/<SETUP_TOKEN>. Enter your name and email and register a passkey. You are the first user, and the link stops working. The deployment logs print the same link. Sign-in explains how to add Google, GitHub, or your own identity provider.
If the page does not load, open the deployment's logs. Keyring logs the name of any missing or invalid variable and exits, for example DATABASE_URL is required.
7. Connect your auth provider
In Keyring, open Settings > Providers and pick your provider. Each provider sends its webhooks to https://<your-domain>/webhooks/<provider>:
| Provider | Webhook URL | Guide |
|---|---|---|
| Clerk | https://<your-domain>/webhooks/clerk |
Clerk |
| WorkOS AuthKit | https://<your-domain>/webhooks/workos |
WorkOS AuthKit |
| Better Auth | https://<your-domain>/webhooks/better-auth |
Better Auth |
| Supabase Auth | https://<your-domain>/webhooks/supabase |
Supabase Auth |
| Auth0 | https://<your-domain>/webhooks/auth0 |
Auth0 |
| Stytch | https://<your-domain>/webhooks/stytch |
Stytch |
Send a test event from the provider. Settings > Providers shows the delivery, or the reason it failed, within a few seconds.
Recover a locked-out account
If someone loses their only passkey, run keyring recover from your machine with the database URL and the deployment's URL. It prints a one-time link, valid for an hour, that registers a new passkey for that account:
DATABASE_URL='postgres://...' PUBLIC_URL=https://keyring-acme.unkey.app go run ./cmd/keyring recover ada@example.com
Store API keys in Unkey
By default, Keyring stores the API keys that agents use in its own database. To manage them in Unkey's API key product instead:
- In the Unkey dashboard, create an API for Keyring's keys and copy its ID. It starts with
api_. - Create a root key with these permissions on that API:
create_key,read_key,read_api,verify_key, anddelete_key. - Set
UNKEY_ROOT_KEYto the root key andUNKEY_API_IDto the API ID, then redeploy.
Keys created before the switch stop working. Create new keys in Settings > API keys.
If the dashboard differs from this guide
This guide follows Unkey's documentation as of November 2026. Two points could not be checked against a live dashboard:
- The exact labels of menus and buttons, such as Create project and the Dockerfile build setting, may differ. Look for the setting with the same purpose.
- Unkey may ask you to deploy before it lets you set variables. If so, let the first deployment fail, set the variables from step 3, and redeploy.