Skip to main content

Nix Flake — Clone and Start Guide

This repo is a reproducible development environment (Nix flake) with Supabase, Vercel, GitHub CLI, and ConsentKeys OAuth pre-configured. Clone it, run one command to enter the environment, follow the interactive setup, and start coding. The guide below is the complete path from zero to a running app.

Clone and get started: nix-flake-guide — clone, add your ConsentKeys and Supabase credentials, and run.

Best for: Developers and AI coding assistants (e.g. VibeCoder, Cursor, Claude) who want to clone once and get a working stack with ConsentKeys login.

Quick start (TL;DR)​

# 1. Clone the repo
git clone https://git.consentkeys.com/flowstate/nix-flake-guide
cd nix-flake-guide

# 2. Enter environment — Nix installs Supabase CLI, Node 20, Yarn, etc.
nix develop

# 3. When prompted, run interactive setup (Y)
# 4. Create .env from env.example and fill in Supabase + ConsentKeys credentials
# 5. Start the app
yarn dev

Then open http://localhost:5173, click Continue with ConsentKeys, and sign in. The rest of this doc is the full step-by-step and reference.

Table of Contents​

Prerequisites​

Before cloning and running, have these ready:

RequirementWhat to do
GitInstall from git-scm.com. Run git --version. Set user.name and user.email.
Supabase accountSign up at supabase.com. You'll link or create a project during setup.
Vercel accountSign up at vercel.com. You'll link or create a project during setup.
GitHub accountSign up at github.com. You'll link or create a repo during setup.
ConsentKeys OAuth appCreate an OAuth application in the ConsentKeys Developer Portal and save Client ID and Client Secret. See Step 0.
Nix (with flakes)Install from nixos.org/download. Run nix --version. If nix is not found, add to ~/.zshrc: export PATH="/nix/var/nix/profiles/default/bin:$PATH" and source the Nix profile script, then restart the terminal.
OSmacOS, Linux, or NixOS.
Optional: DockerOnly needed for local Supabase (supabase start).

Step 0: Create ConsentKeys OAuth Application​

You need a ConsentKeys OAuth application before Supabase setup so you can paste the Client ID and Client Secret when prompted.

  1. Open ConsentKeys — Log in at the Developer Portal.
  2. Developer Portal — Go to the Developer Portal (e.g. OAuth Applications / Applications).
  3. Create application — New OAuth/Web application. Set:
    • Application name (e.g. "My App - Development").
    • Redirect URI(s) — must match exactly:
      • Local: http://localhost:5173/auth/callback
      • Production: https://YOUR_PROJECT_REF.supabase.co/functions/v1/consentkeys-callback
    • Scopes: openid, profile, email.
  4. Save credentials — After creation you get:
    • Client ID (e.g. ck_...) — used in frontend and edge function.
    • Client Secret — shown only once. Store in a password manager or env; never commit.
  5. Check status — Application should be "Active" or "Enabled".

ConsentKeys endpoints (for reference):

  • Authorization: https://api.consentkeys.com/auth
  • Token: https://api.consentkeys.com/token
  • UserInfo: https://api.consentkeys.com/userinfo
  • Discovery: https://api.consentkeys.com/.well-known/openid-configuration

Before Step 1: You should have Client ID and Client Secret ready to paste during setup.

Step 1: Clone and Enter the Repository​

git clone https://git.consentkeys.com/flowstate/nix-flake-guide
cd nix-flake-guide
nix develop

What happens: Nix downloads and installs Supabase CLI, Vercel CLI, GitHub CLI, Node.js 20, Yarn, Git, jq, and curl. On first run you'll be prompted to run interactive setup.

Step 2: Run Initial Setup​

When you enter nix develop, you'll see:

Run interactive setup for Supabase, Vercel, GitHub, and Frontend? (Y/n):

Type Y and press Enter.

Supabase setup (setup-supabase)​

  1. Auth — If not logged in, you'll be sent to the browser to log in to Supabase.
  2. Project — Link to an existing Supabase project or create a new one (browser).
  3. Edge function — The ConsentKeys callback lives at supabase/functions/consentkeys-callback/. JWT verification is already disabled in config.toml.
  4. Secrets — You'll be prompted for:
    • CONSENT_KEYS_TOKEN_URL (default: https://api.consentkeys.com/token)
    • CONSENT_KEYS_USERINFO_URL (default: https://api.consentkeys.com/userinfo)
    • CONSENT_KEYS_CLIENT_ID (from Step 0)
    • CONSENT_KEYS_CLIENT_SECRET (from Step 0)
    • APP_URL (default: http://localhost:5173/auth/callback)
  5. Deploy — Option to deploy the edge function now. If yes, it runs: supabase functions deploy consentkeys-callback --no-verify-jwt

Manual secrets (if setup doesn't prompt):

supabase projects list   # get PROJECT_REF
supabase secrets set CONSENT_KEYS_TOKEN_URL="https://api.consentkeys.com/token" --project-ref PROJECT_REF
supabase secrets set CONSENT_KEYS_USERINFO_URL="https://api.consentkeys.com/userinfo" --project-ref PROJECT_REF
supabase secrets set CONSENT_KEYS_CLIENT_ID="your_client_id" --project-ref PROJECT_REF
supabase secrets set CONSENT_KEYS_CLIENT_SECRET="your_client_secret" --project-ref PROJECT_REF
supabase secrets set APP_URL="http://localhost:5173/auth/callback" --project-ref PROJECT_REF

Vercel setup (setup-vercel)​

Log in to Vercel in the browser, then link an existing project or create a new one.

GitHub setup (setup-github)​

Authenticate with GitHub, then link an existing repo or create a new one.

Frontend setup (setup-frontend)​

Checks package.json, installs dependencies if needed, and helps create .env from env.example.

Step 3: Configure Environment Variables​

Create and fill your .env in the project root:

cp env.example .env

Edit .env with your values:

# From Supabase: Dashboard → Your Project → Settings → API
VITE_SUPABASE_URL=https://your-project-id.supabase.co
VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your-anon-key-here

# ConsentKeys (Client ID from Step 0; redirect = your Supabase functions URL)
VITE_CONSENT_KEYS_AUTHORIZE_URL=https://api.consentkeys.com/auth
VITE_CONSENT_KEYS_CLIENT_ID=ck_your_client_id_here
VITE_CONSENT_KEYS_REDIRECT_URI=https://your-project-id.supabase.co/functions/v1/consentkeys-callback

Supabase credentials: Dashboard → Settings → API → Project URL and anon public key.

Important: VITE_CONSENT_KEYS_REDIRECT_URI must be exactly https://YOUR_PROJECT.supabase.co/functions/v1/consentkeys-callback. Restart the dev server after changing .env.

Step 4: Verify Edge Function Configuration​

The ConsentKeys callback runs with JWT verification disabled (OAuth code flow, not JWT).

Check locally:

cat supabase/functions/consentkeys-callback/config.toml

Expected:

[functions.consentkeys-callback]
verify_jwt = false

When deploying, always use:

supabase functions deploy consentkeys-callback --no-verify-jwt

In Supabase Dashboard → Edge Functions → consentkeys-callback → Settings, "Verify JWT with legacy secret" should be OFF.

Step 5: Start Development​

yarn dev
# or: npm run dev

App runs at http://localhost:5173.

Test login: Open the app → click Continue with ConsentKeys → sign in at ConsentKeys → you should be redirected back and see the dashboard.

Environment Variables Reference​

Frontend (.env)​

VariableDescription
VITE_SUPABASE_URLSupabase project URL
VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEYSupabase anon public key
VITE_CONSENT_KEYS_AUTHORIZE_URLConsentKeys auth endpoint
VITE_CONSENT_KEYS_CLIENT_IDConsentKeys client ID
VITE_CONSENT_KEYS_REDIRECT_URISupabase edge function URL for callback

Variables must be prefixed with VITE_ for Vite to expose them to the client.

Edge function secrets (Supabase Dashboard or CLI)​

SecretDescription
CONSENT_KEYS_TOKEN_URLToken endpoint
CONSENT_KEYS_USERINFO_URLUserInfo endpoint
CONSENT_KEYS_CLIENT_IDConsentKeys client ID
CONSENT_KEYS_CLIENT_SECRETConsentKeys client secret
APP_URLFrontend callback URL (e.g. http://localhost:5173/auth/callback)

SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are provided by Supabase automatically.

Edge Function Configuration​

Why JWT is disabled​

ConsentKeys uses the OAuth 2.0 authorization code flow. The edge function receives a code in the query string, not a JWT. It exchanges the code for tokens and then creates/finds the user and issues a magic link. Enabling JWT verification would block this flow — keep it disabled for consentkeys-callback.

Flow summary​

  1. User clicks "Continue with ConsentKeys" → redirect to ConsentKeys.
  2. User signs in → ConsentKeys redirects to the edge function with ?code=....
  3. Edge function exchanges code for access token, fetches userinfo, creates/finds user in Supabase, generates magic link.
  4. User is redirected to the magic link → frontend /auth/callback sets the session → user is logged in.

Available Commands​

Run these inside nix develop:

Setup

  • setup-all — Re-run full setup (Supabase, Vercel, GitHub, Frontend).
  • setup-supabase — Supabase only (auth, project, edge function secrets).
  • setup-vercel — Vercel only.
  • setup-github — GitHub only.
  • setup-frontend — Deps and .env check.
  • verify-edge-function — Check edge function layout and config.

Development

  • yarn dev / npm run dev — Start Vite dev server.
  • supabase start — Local Supabase (needs Docker).
  • supabase stop — Stop local Supabase.
  • vercel dev — Vercel dev server.
  • vercel --prod — Deploy to production.

Supabase

  • supabase functions deploy consentkeys-callback --no-verify-jwt — Deploy callback.
  • supabase functions list — List functions.
  • supabase secrets list — List secrets.

Troubleshooting​

nix: command not found​

  • Ensure Nix is installed and on your PATH. Add the Nix profile to ~/.zshrc (see Prerequisites) and run source ~/.zshrc or restart the terminal.

Edge function not working / 401​

  • Confirm verify_jwt = false in supabase/functions/consentkeys-callback/config.toml.
  • Deploy with --no-verify-jwt.
  • In Dashboard → Edge Functions → consentkeys-callback → Settings, turn OFF "Verify JWT with legacy secret".
  • Check Edge Function Secrets (Client ID, Client Secret, token/userinfo URLs, APP_URL).
  • Ensure redirect URI in ConsentKeys app matches: https://YOUR_PROJECT.supabase.co/functions/v1/consentkeys-callback.

Frontend env vars not loading​

  • Use the VITE_ prefix for all frontend vars.
  • Restart the dev server after editing .env.
  • Keep .env in the project root (next to package.json).

Supabase connection issues​

  • No trailing slash on VITE_SUPABASE_URL.
  • Use the anon public key for VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY, not the service role key.
  • Confirm the project is active in the Supabase dashboard.

redirect_uri_mismatch​

  • The redirect URI in the ConsentKeys app must exactly match the one used in the frontend and in the token exchange (same scheme, host, path, no trailing slash).

Reproducibility and What's Included​

Reproducible (same for everyone):

  • Tools and versions (Nix: Supabase CLI, Node 20, Yarn, etc.).
  • Setup scripts, frontend structure, edge function code and config.toml, env.example.

User-specific (not in git):

  • .env (gitignored).
  • Supabase/Vercel/GitHub project links and edge function secrets.

To get the same environment on another machine: Clone → nix develop → run setup → add .env and secrets → yarn dev.

Included in the flake:

  • Supabase CLI, Vercel CLI, GitHub CLI, Node.js 20, Yarn, Git, jq, curl.
  • React + Vite + TypeScript frontend with Supabase and ConsentKeys OAuth, protected routes, and auth context.
  • ConsentKeys callback edge function (code exchange, userinfo, Supabase user + magic link).

Use cases: Full-stack apps with Supabase, React/Vite or similar frontends, deployment to Vercel, AI-assisted coding (VibeCoder, Cursor, etc.), and ConsentKeys OAuth login.

Customization​

To add more tools, edit flake.nix and add packages, for example:

packages = with pkgs; [
  python3
  postgresql
  redis
  # ...
];

Contributing and License​

Contributions are welcome (issues and PRs). License: MIT.