Self-hosting

Run Hookie locally or on your own infrastructure — Clerk, Supabase, Redis, ingest, relay, and web app

Hookie is meant to be cloned and run yourself. This page summarizes what you need; the canonical step-by-step guide is CONTRIBUTING.md in the repository.

Prerequisites

Piece	Role
Node.js (≥ 24) + pnpm	Web app (`apps/web`) and docs
Go	Ingest, relay, CLI
Docker (optional but typical)	Redis and supporting services via Compose
Supabase	Postgres + auth-related data; local via `supabase start` or your own project
Clerk	Sign-in for the dashboard and CLI OAuth-style login flow — create a Clerk app and wire keys to the web app

Services to run

Redis — Used by ingest and relay (see Compose / CONTRIBUTING).
backend/ingest — Webhook HTTP receiver; set INGEST_BASE_URL / public URL as needed for your network.
backend/relay — gRPC relay; CLI connects here (HOOKIE_RELAY_URL or dev defaults).
apps/web — Dashboard; requires Clerk + Supabase env vars (see apps/web/.env.example in the repo).

Web app environment (reference)

Copy apps/web/.env.example to .env.local and fill values. Typical variables include:

Clerk — NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, CLERK_WEBHOOK_SECRET (if using Clerk webhooks)
Supabase — SUPABASE_URL, SUPABASE_SECRET_KEY, SUPABASE_PUBLISHABLE_KEY, and the NEXT_PUBLIC_* mirrors
Ingest — INGEST_BASE_URL / NEXT_PUBLIC_INGEST_BASE_URL so the UI can show correct webhook URLs
App URL — NEXT_PUBLIC_APP_URL for redirects and absolute links in dev

There is no Stripe or billing in this project; ignore any third-party docs that mention paid plans.

CLI against your stack

Build or install the CLI, then:

Set HOOKIE_WEB_APP_URL to the base URL of your running Next app (e.g. http://localhost:3000).
Set HOOKIE_RELAY_URL to your relay gRPC host/port when not using dev defaults.

See CLI overview and Authentication.

npm package `@hookie-sh/hookie`

The published npm package wraps prebuilt binaries. For a fully self-hosted setup you can also build the CLI from source in cli/ so relay defaults match your environment.

If you rely on the npm installer, ensure release binaries still match your OS/arch, or build from source.