App~/docsmenu+close×
01Quickstart/start02Environment/start03Architecture/system04API Map/reference05Migrations/data06Custom Tools/extend07Customization/extend08Licence/legal
Back to App
~/docs
01Quickstart→02Environment→03Architecture→04API Map→05Migrations→06Custom Tools→07Customization→08Licence→
AgentZero / docs
v0.1 · built in SA

Environment Setup

Version: 0.1.0 Last Updated: May 2026

end

This is the full reference for every environment variable AgentZero reads, what it does, where to get it, and whether it's required.

For a guided walk-through, see the Quickstart. This page is the table you bookmark.

end

Required to boot

These four must be set or the app won't start.

NEXT_PUBLIC_SUPABASE_URL

Your Supabase project URL. The NEXT_PUBLIC_ prefix is intentional — this is safe to expose to the browser.

  • ›Where: Supabase dashboard → Project Settings → API → Project URL
  • ›Format: https://<project-ref>.supabase.co

SUPABASE_SECRET_KEY

The service_role key. Never commit this. Never expose it to the browser. It bypasses Row-Level Security.

  • ›Where: Supabase dashboard → Project Settings → API → service_role key
  • ›Format: eyJ... (a long JWT)

AUTH_SECRET

Used by Auth.js to sign JWT session tokens. If this changes, every existing session is invalidated.

  • ›Generate: openssl rand -base64 32
  • ›Format: 32+ random characters

NEXTAUTH_URL

The canonical URL of your deployment. Auth.js uses this for redirect callbacks.

  • ›Local: http://localhost:3000
  • ›Production: https://yourdomain.com (no trailing slash)
end

AI inference

AI_GATEWAY_API_KEY

A single key that routes inference requests to Claude, GPT, DeepSeek, and other models. The codebase chats through @ai-sdk/gateway and embeddings through NVIDIA NIMs separately (see below).

  • ›Where: Vercel dashboard → AI Gateway → Tokens → Create
  • ›Required for: every agent run
  • ›Models enabled by default: see lib/ai/model-registry.ts

NVIDIA_NIMS_API_KEY

Used by the RAG pipeline for generating embeddings via nvidia/llama-nemotron-embed-1b-v2.

  • ›Where: build.nvidia.com → NIMs → API Catalog → Generate API key
  • ›Required for: knowledge base / RAG features
  • ›Note: the DB vector columns are locked to 1024 dimensions to match this model. If you swap embedding providers, you must also rerun the embedding migration with the new dimension count.
end

Tools (opt-in)

These power individual agent tools. Each tool is independently toggleable from the agent settings UI — you only need the key if you want that tool enabled.

TAVILY_API_KEY

Powers the webSearchTool.

  • ›Where: tavily.com → API Keys
  • ›Free tier: 1,000 searches/month
  • ›Skip if: you don't need agents to search the web

RESEND_API_KEY + RESEND_FROM_EMAIL

Powers the emailAutomateTool and outbound transactional emails (waitlist confirmations, future magic-link auth).

  • ›Where: resend.com → API Keys
  • ›RESEND_FROM_EMAIL format: Your Brand <noreply@yourdomain.com>
  • ›DNS: you must verify your sending domain with Resend before email works
end

Billing (opt-in)

Only needed if you're using AgentZero to sell agents to paying customers. For internal tooling, skip this entire section.

LEMONSQUEEZY_API_KEY

Server-side API key for creating checkouts and reading orders.

  • ›Where: lemonsqueezy.com → Settings → API
  • ›Scope: full read/write

LEMONSQUEEZY_STORE_ID

The numeric store ID where your products live.

  • ›Where: lemonsqueezy.com → Store URL contains it, or Settings → Stores

LEMONSQUEEZY_WEBHOOK_SECRET

Used to verify incoming webhook signatures. Without this, anyone could POST fake "order completed" events to your endpoint.

  • ›Where: lemonsqueezy.com → Settings → Webhooks → Add endpoint → reveal signing secret
  • ›Webhook URL to register: https://yourdomain.com/api/webhooks/lemonsqueezy
  • ›Events to subscribe to: order_created, subscription_created, subscription_updated, subscription_cancelled

LEMONSQUEEZY_FOUNDING_VARIANT_ID / LEMONSQUEEZY_PRO_VARIANT_ID

The variant IDs for your founding-member and pro products. The credit-grant logic reads these to match orders to tiers.

  • ›Where: lemonsqueezy.com → Products → click product → Variant ID (numeric)
end

Tuning knobs

These have sensible defaults — only change if you know what you're doing.

RAG_MATCH_THRESHOLD

The cosine-similarity cutoff for retrieving knowledge-base chunks. Lower = more results, more noise. Higher = fewer results, more precise.

  • ›Default: 0.1
  • ›Range: 0.0 – 1.0
  • ›Tune up if: agents are pulling irrelevant context
  • ›Tune down if: agents say "no relevant context found" too often
end

Local-only

NEXTAUTH_DEBUG

Verbose Auth.js logs. Helpful when debugging session/JWT issues.

  • ›Default: unset
  • ›Set to: true for verbose output
end

.env.example template

Here's a starter .env.example covering everything:

$  snippetread-only
# ─── Required ─────────────────────────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=
SUPABASE_SECRET_KEY=
AUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000

# ─── AI inference ─────────────────────────────────────────────
AI_GATEWAY_API_KEY=
NVIDIA_NIMS_API_KEY=

# ─── Tools (opt-in) ───────────────────────────────────────────
TAVILY_API_KEY=
RESEND_API_KEY=
RESEND_FROM_EMAIL=

# ─── Billing (opt-in) ─────────────────────────────────────────
LEMONSQUEEZY_API_KEY=
LEMONSQUEEZY_STORE_ID=
LEMONSQUEEZY_WEBHOOK_SECRET=
LEMONSQUEEZY_FOUNDING_VARIANT_ID=
LEMONSQUEEZY_PRO_VARIANT_ID=

# ─── Tuning ───────────────────────────────────────────────────
RAG_MATCH_THRESHOLD=0.1
end

Validating your config

Run this once you've filled in .env.local:

$  snippetread-only
pnpm dev

Then check:

  • ›Landing page loads → Supabase URL + Auth secret are good
  • ›/signup creates a user → Supabase service-role key is good
  • ›Creating an agent + running a prompt → AI Gateway key is good
  • ›Uploading a PDF + querying it → NIMs key is good

If any of those fail, the error log will name the missing or wrong variable specifically.

end

Security notes

  • ›SUPABASE_SECRET_KEY, AI_GATEWAY_API_KEY, and webhook secrets should never appear in client-side code or in your git history. The error sanitiser in agent-actions.ts strips them from streamed error messages — but the best defence is not committing them in the first place.
  • ›Use a different AUTH_SECRET per environment (dev / staging / production).
  • ›Rotate keys if you've ever pasted them in a screenshot, Discord channel, or AI chat. They are recoverable from those logs forever.