--- title: Environment Variables description: Learn about the environment variables used in Geistdocs type: reference summary: Environment variables required by Geistdocs for AI chat, Mixedbread retrieval, proxy mode, eve agent session cookies, and production URL configuration. url: /docs/env source: apps/template/content/docs/env.mdx prerequisites: - /docs/getting-started related: - /docs/configuration - /docs/deployment --- # Environment Variables Geistdocs uses environment variables to configure Ask AI, optional Mixedbread retrieval, optional Vertex-backed proxy mode, eve agent session cookie signing, and production URL behavior. Review this Geistdocs project and help me configure the required environment variables. Check whether `AI_GATEWAY_API_KEY`, `MXBAI_API_KEY`, `MXBAI_STORE_ID`, `GEISTDOCS_CHAT_PROXY_URL`, `GEISTDOCS_CHAT_PROXY_TOKEN`, `GEISTDOCS_CHAT_SECRET`, and `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` are needed for the features I enabled, then tell me where to set them locally and on Vercel. ## `AI_GATEWAY_API_KEY` The API key for the AI Gateway. This is used to power the default local AI chat functionality when `GEISTDOCS_CHAT_PROXY_URL` is not set. > This is automatically set when deploying to Vercel. Leave `GEISTDOCS_CHAT_PROXY_URL` unset to use AI Gateway mode. ## `MXBAI_API_KEY` The server-only API key for Mixedbread retrieval. The Mixedbread Vercel Marketplace integration injects this value when you provision a Store and connect it to the consumer site's Vercel project. ## `MXBAI_STORE_ID` The Mixedbread Store used by one consumer site. Set `ai.retrieval` to `"mixedbread"` and configure a unique `siteId` before using this value. Provision the Store by running `vercel integration add mixedbread` from the root of the consumer site's repository, where Vercel CLI is linked to that site's project. Do not run the provisioning command from the Geistdocs package repository. Read [Improve Ask AI answers with Mixedbread](/docs/mixedbread-retrieval) for the complete setup. ## `GEISTDOCS_CHAT_PROXY_URL` An optional URL for a chat proxy. When set, Geistdocs searches the local documentation on the first user message, injects the current page and related docs as context, and forwards the request to this proxy. Use this when routing Ask AI through a central Vertex-backed service. The value should point at the Geistdocs platform proxy and include `/vertex`: ```txt https:///vertex ``` When this variable is set, the site does not need `AI_GATEWAY_API_KEY` for Ask AI requests. The platform proxy calls Vertex and forwards a Vercel OIDC token in `x-vercel-trusted-oidc-idp-token` so the Vertex deployment can validate the caller through Deployment Protection Trusted Sources. ## `GEISTDOCS_CHAT_PROXY_TOKEN` The server-only bearer token that authenticates a Geistdocs site to its chat proxy. The central Geistdocs platform proxy requires this value. Generate a random token containing at least 32 bytes: ```bash title="Terminal" openssl rand -base64 32 ``` Set the generated value as `GEISTDOCS_CHAT_PROXY_TOKEN` on each approved Geistdocs site and as `GEISTDOCS_VERTEX_PROXY_TOKEN` on the platform proxy deployment. Never expose either value with a `NEXT_PUBLIC_` prefix. ## Vertex-backed proxy setup To route Ask AI through Vertex: 1. Generate a random token with `openssl rand -base64 32`. 2. Set the token as `GEISTDOCS_VERTEX_PROXY_TOKEN` on the platform proxy deployment. 3. In the Vertex deployment's Deployment Protection settings, add the Geistdocs platform Vercel project as a Trusted Source. 4. In each approved Geistdocs site, set `GEISTDOCS_CHAT_PROXY_URL` to the platform proxy URL, including `/vertex`. 5. Set the same token as `GEISTDOCS_CHAT_PROXY_TOKEN` on each approved Geistdocs site. The bearer token authenticates each Geistdocs site to the platform proxy. The platform proxy then authenticates to Vertex with Vercel OIDC and Trusted Sources. The `/vertex` route accepts request bodies up to 1,000,000 bytes, up to 200 messages, and only `platform: "vercel"`. ## `GEISTDOCS_CHAT_SECRET` A server-only secret that signs the httpOnly cookie binding each reader's browser to its eve agent session. Set it when `ai.eveAgent` is configured so Ask AI can continue one eve session across turns and prewarm sessions. The chat route only contacts a session named by a cookie that verifies with this secret, so a reader can't point the chat route at another reader's eve session, and page scripts can't read the session ID. The secret must be at least 32 bytes. Generate one with: ```bash title="Terminal" openssl rand -base64 32 ``` Add it to your site's Vercel project environment variables for the Production and Preview environments, and to `.env.local` for local development. Use a separate secret for each docs site. An existing base64-encoded 32-byte secret (44 characters) also works, because Geistdocs uses the value as-is and signs with its own versioned prefix. Rotating the secret invalidates existing session cookies, so each reader's next message starts a new eve session with the conversation inlined. Without this variable, eve agent mode starts a new eve session on every turn with the prior conversation inlined, refuses prewarm requests, and logs a warning. A value shorter than 32 bytes throws when the chat route loads. Pass the `eveAgent.secret` option to `createChatRoute` to supply the secret another way. Never expose it with a `NEXT_PUBLIC_` prefix or put it in `geistdocs.tsx`. Read [Ask AI](/docs/ask-ai#keep-eve-sessions-across-turns-with-geistdocs_chat_secret) for the full behavior. ## `NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL` The production URL of the Geistdocs site. Geistdocs uses it for canonical and Open Graph metadata, product JSON-LD, `sitemap.xml`, `robots.txt`, and RSS links. Vercel sets this variable automatically. Set this variable explicitly when deploying outside Vercel. Use a hostname such as `docs.example.com` or a full `http` or `https` URL. Local development falls back to `http://localhost:3000`. A production build with a missing or malformed value emits a warning and omits default canonical and product JSON-LD URLs. Its `sitemap.xml`, `robots.txt` sitemap directive, RSS links, and generated Open Graph image URLs continue to use the localhost fallback, so treat the warning as a deployment blocker. Geistdocs does not use the deployment-specific `VERCEL_URL` for canonical surfaces.