Quickstart
From git clone to running glasses app + companion site, both signed in and billing-ready, in about 20 minutes.
This guide gets you to a fully functional local instance (the Vite glasses app, the Next.js companion, and the shared Convex backend) with real Clerk auth wired across both surfaces. ~10 minutes for the base setup. Add-ons (Payments, Email, AI Showcase) are optional and enabled with a single CLI command each.
GlassKit ships no interactive setup wizard. The first-time
walkthrough is AI-driven: open the repo in Claude Code,
Cursor, or Codex, point it at the root AGENTS.md, and your AI
agent collects the keys conversationally, runs the right commands,
writes the env files, and walks you through webhook registration.
The manual walkthrough below is also fully sufficient if you'd
rather not use an AI tool.
Before you start: open these tabs
You'll be asked for each value below as you go. Paste each into a scratch file as you grab it: about 5 minutes of prep, then ~10 minutes of guided setup.
Node 22+ · pnpm 9+
Easiest path: corepack enable (Node 22 ships with corepack; it auto-resolves the pinned pnpm version from package.json).
Always needed (Clerk + Convex)
| Service | What to grab | Where |
|---|---|---|
| Clerk | Publishable + Secret key | API keys |
| Clerk | JWT Issuer URL | JWT Templates → create one named exactly convex → Issuer |
| Clerk | Webhook signing secret | Webhooks → Add Endpoint (URL is <your-deployment>.convex.site/clerk-users-webhook) |
| Convex | Deployment URL | Printed by pnpm exec convex dev (your AI tool or Step 3 below runs this for you) |
That's it for the base. The three opt-in add-ons (Payments,
Email, AI Showcase) toggle with one command each later:
pnpm run addon enable <id> or disable <id> (<id> ∈
payments | email | ai).
Add-on prerequisites (each optional)
Default is off for all three. The base boilerplate boots, deploys, and serves a working dashboard without any of these configured. Enable each as your product actually needs it.
If you're ready to charge users, Payments add-on wires Stripe checkout + customer portal + webhook sync + the pricing UI. Grab:
If you want transactional sends (welcome email + your own custom mail), Email add-on wires Resend through the official Convex component. Grab:
If you want the AI integration + the six sensor/AI demo apps in the launcher, AI Showcase add-on wires Anthropic + OpenAI through the Vercel AI SDK. Grab:
| Service | What to grab | Where |
|---|---|---|
| Anthropic | API key (sk-ant-...) | Console → API keys |
| OR OpenAI | API key (sk-...) | Same |
One provider is enough; swap with one env var.
Clone and install
git clone https://github.com/GlassKitApp/glasskit-boilerplate my-app
cd my-app
pnpm installOne install, three workspaces: app/, companion/, packages/backend/.
Drive setup with your AI coder (recommended)
Open the repo in Claude Code,
Cursor, or Codex
and ask it to do first-time setup. The full instructions live in the
repo's root AGENTS.md; your AI tool reads them automatically
and walks you through: collecting your Clerk creds, linking the
Convex deployment, pushing Convex env vars with
pnpm exec convex env set …, registering the Clerk webhook,
writing both .env.local files.
~10 minutes for the base
AGENTS.md tells the AI exactly what to name the Clerk JWT
template (the #1 community footgun: convex, lowercase, no
spaces) and how to compute the Convex HTTP-actions origin for
webhook URLs. You can interrupt at any step; the work is
resumable via the env state on disk.
If you prefer wiring each service by hand, step 3 below documents the same setup manually.
Manual setup (alternative)
Skip this if you let your AI coder drive setup. Each subsection here is what AGENTS.md tells the AI to do.
3a: Stand up the Convex backend
First non-skippable step
Convex generates typed client code
(packages/backend/convex/_generated/) that the apps import.
Until you do this once, the apps don't typecheck.
cd packages/backend
pnpm exec convex devThe CLI walks you through linking the workspace to a new Convex deployment. Keep it running while you develop; it hot-reloads your backend functions and regenerates types on every change.
It prints the deployment URL (looks like
https://<name>.convex.cloud). Copy it for the next step.
Commit convex/_generated/ once it appears; your CI typechecks
won't pass without it.
3b: Wire Clerk (auth)
GlassKit uses Clerk on both apps, with the same session shared through Convex.
Sign in to clerk.com → Create application.
Copy the Publishable key (pk_test_...) and Secret key
(sk_test_...).
In Clerk, go to JWT Templates → New template → Convex. The
template must be named exactly convex. Save and copy the
Issuer URL (your Clerk JWT issuer domain).
Webhooks → Add Endpoint: URL
https://<deployment>.convex.site/clerk-users-webhook, events
user.created, user.updated, user.deleted. Copy the signing
secret.
Then drop the values into three places; pick the tab that matches where you are.
dashboard.convex.dev → your deployment → Settings → Environment Variables:
CLERK_JWT_ISSUER_DOMAIN=https://your-app-12.clerk.accounts.dev
CLERK_SECRET_KEY=sk_test_...
CLERK_WEBHOOK_SECRET=whsec_...cp companion/.env.example companion/.env.localFill in:
NEXT_PUBLIC_CONVEX_URL=https://<your-deployment>.convex.cloud
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...cp app/.env.example app/.env.localFill in:
VITE_CONVEX_URL=https://<your-deployment>.convex.cloud
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...3c: Add-ons (optional)
The base boilerplate is now wired. Three opt-in add-ons live
behind separate docs; enable each when your product needs it
(pnpm run addon enable <id> from the repo root):
Run everything
From the repo root:
pnpm devThat fans out across the three workspaces:
app/→http://localhost:5173(Vite, the 600×600 app)companion/→http://localhost:3000(Next.js companion)packages/backend/→convex dev(already running)
Verify
- Companion:
localhost:3000renders the marketing home. - Sign-up on the companion via Clerk.
- Checkout from
/pricingwith test card4242 4242 4242 4242redirects through Stripe and back to/dashboard?checkout=success. - Dashboard shows the plan as
pro/team(this isentitlements.getMyPlanderiving live from the Stripe component). - Glasses: open
localhost:5173; it picks up the same Clerk session and shows the six-app launcher. - An example app: open Tour Guide, allow location, press What's here?, and an AI response renders.
Pair the glasses locally during dev
The production pairing path is same-network device pairing:
the glasses register a session tagged with their network's egress
IP, the user's phone sees that Display on the companion's /pair
page and taps it, and the wearer approves on the glasses. A Clerk
Sign-In Ticket is minted only after that on-glasses Yes. See
Pairing for the mechanism.
For local dev there are three faster paths, in order of effort:
Browser preview: open http://localhost:5173 in the same
browser you signed into the companion with. The Clerk session is
shared because both apps point at the same
NEXT_PUBLIC_/VITE_CONVEX_URL and *_CLERK_PUBLISHABLE_KEY, so you
rarely need to pair at all. Arrow keys simulate the D-pad; Chrome
DevTools Sensors panel overrides GPS / motion / orientation when
a demo needs them.
Exercise the real pairing flow locally: tap Start Pairing
in the glasses app, then open http://localhost:3000/pair on the
same machine. Both surfaces share the same egress IP (localhost),
so your Display shows up on /pair immediately. Tap it, then tap
Yes on the glasses to approve. No tunnel needed; discovery just
works because the egress IP matches.
Tunnel + real glasses: the Meta AI app needs HTTPS, so expose
localhost:5173 with cloudflared tunnel --url http://localhost:5173
(or ngrok http 5173) and paste the returned
https://*.trycloudflare.com URL into the Meta AI app's Add Web
App flow. That just launches the app on the glasses; to sign
in, tap Start Pairing and approve from your phone's /pair
page on the same network. Browser-side sensor simulation is
replaced by the real GPS, IMU, and Neural Band.
Different network? Use the code fallback
If your phone or laptop isn't on the same network as the glasses
(phone on cellular, glasses on guest Wi-Fi), same-network
discovery won't list the Display on /pair. Use the code
fallback instead: type the short code the glasses show on their
waiting screen into the "Not on the same network?" field on
/pair, then confirm that the 2-digit number the companion shows
matches the one on the glasses. See Pairing.
What's next
Customize the companion
Edit the @theme tokens in companion/app/globals.css to rebrand. The styles are vanilla Tailwind v4.
Fork an example app
app/src/apps/ has six showcases. Copy one, rename it, and replace the launcher entry in app/src/App.tsx.
Build a custom glasses screen
The typed component library reference.
Ship to production
Three deploy targets: Convex, companion on Vercel, glasses app static.
Pull future updates
How to merge upstream GlassKit changes into your fork.