Environment Variables

Purpose and Scope

This page explains the configuration OpenWiki expects before you run it locally or deploy it to Vercel. OpenWiki is a hosted Next.js application backed by an eve agent, a Postgres database, Vercel Blob artifacts, and GitHub repository reads. The environment variables are not just deployment decoration: they decide where durable metadata is stored, where generated wiki output is written, how repository fetches behave under GitHub API limits, and whether a public deployment can create new repository records on demand.

Sources: README.md, agent/lib/github-repo.ts

The first-party README presents the happy path as a Vercel deployment that provisions Neon Postgres and Vercel Blob, then lets a user visit a repository route such as /vercel/next.js. That flow is intentionally simple because most required service credentials come from the Vercel integration environment. For local development, the recommended path is to link the Vercel project, pull environment variables into .env.local, and then start the app with pnpm dev. If you are not using the deploy flow, you need to provide equivalent storage services yourself before expecting wiki generation, repository pages, and chat state to work.

Relevant Source Files

• README.md - Defines the deployment flow, local setup commands, storage setup, and the complete visible environment-variable tables used by this page.
• agent/lib/github-repo.ts - Shows how repository URLs are parsed, how GitHub metadata and file inventories are prepared, and why GitHub access and public-repository constraints matter to configuration decisions.

Required Runtime Services

OpenWiki requires a Postgres connection string and an artifact store. The required DATABASE_URL points at Postgres and is used for repository metadata, indexing jobs, revisions, and chat sessions. The README names Neon Postgres as the storage integration provisioned by the one-click Vercel deployment, so the default deployment story assumes a serverless Postgres database managed through Vercel. Without this connection string, the application cannot persist the repository records or job state that connect a route request to generated wiki content.

Sources: README.md

The required BLOB_STORE_ID identifies the Vercel Blob store used for generated wiki artifacts. The generated wiki is not described as transient render output; it is published as navigable documentation artifacts that must be retrievable after the indexing agent completes. In the Vercel flow, the Blob store is provisioned alongside Neon, and vercel env pull .env.local --yes brings the relevant values into local development. That makes local development mirror production storage unless you deliberately opt into the local artifact mode described later.

Sources: README.md

The storage settings form a pair. Postgres stores the structured state that says which repository exists, which indexing job ran, which revision is current, and which chat sessions belong to the repository. Blob stores the generated wiki artifacts themselves. A deployment that points the database at one environment and Blob at another can create confusing behavior because the metadata and files no longer describe the same generated wiki. Treat DATABASE_URL and BLOB_STORE_ID as an environment-specific pair for production, preview, and local development.

Configuration Reference

The local-only artifact mode is useful for smoke tests because it lets a developer run the app without writing generated wiki files to Vercel Blob. The README warns that this mode should be used only with an isolated local database. That warning matters because shared deployments cannot read files from a developer machine. If a shared database records a wiki artifact that was written only to local disk, other environments may believe the wiki exists while being unable to serve the artifact.

Sources: README.md

GitHub Access and Public Repository Constraints

GITHUB_TOKEN is recommended but not required. Its purpose is to raise GitHub API limits for public repositories, which is important because the indexing agent fetches repository metadata, lists tree files, and reads selected source files before generating documentation. The repository access code parses only GitHub repository URLs, normalizes them into https://github.com/{owner}/{repo}, and rejects owner or repository names that contain characters outside letters, numbers, dots, dashes, and underscores. That parsing behavior keeps the agent focused on predictable public GitHub repository inputs.

Sources: README.md, agent/lib/github-repo.ts

The same GitHub preparation code also explains why API limits and repository size matter. It creates a snapshot containing the commit SHA, default branch, description, homepage URL, topics, and a file inventory. It limits seeded files and skips oversized files, then writes selected files and a manifest into the eve sandbox workspace. This means configuration that improves GitHub read capacity, especially GITHUB_TOKEN, directly supports reliable indexing for larger public repositories. It does not change the public-deployment policy: the README says OpenWiki intentionally rejects private repositories on public deployments, and recommends using a token without private repository access there.

Sources: README.md, agent/lib/github-repo.ts

Deployment and Local Setup Flow

For Vercel deployment, start with the one-click deploy path from the README. It provisions Neon Postgres for metadata and Vercel Blob for artifacts, then exposes the environment-variable setup through the deploy flow. After deployment, the app can be opened and tested by navigating to a repository route. This route-driven behavior is important operationally: a repository URL or owner/repository route can trigger lookup and generation behavior, so production deployments should decide whether public repository creation is acceptable before opening the app broadly.

Sources: README.md

For local development, install dependencies, link the Vercel project, pull the Vercel environment into .env.local, and run the development server. The README’s sequence is intentionally ordered: dependency installation prepares the Next.js app, vercel link associates the local checkout with the deployed project, vercel env pull .env.local --yes copies service credentials, and pnpm dev starts the application. When these steps are followed, the local app uses the same Postgres and Blob configuration supplied by Vercel unless you override it.

pnpm install
vercel link
vercel env pull .env.local --yes
pnpm dev

If you need a local-only smoke test, set OPENWIKI_LOCAL_ARTIFACTS=1 while running the development server. Pair that setting with an isolated local database so no shared environment records artifacts that only exist on your machine. If you are testing behavior that depends on generated pages being available to other users, previews, or deployed routes, prefer Blob-backed artifacts instead of local artifacts. The local mode is best for verifying that generation can complete, not for validating a shared hosted wiki lifecycle.

OPENWIKI_LOCAL_ARTIFACTS=1 pnpm dev

Operational Choices and Next Steps

The most important production choice after storage setup is public repository creation. By default, OpenWiki is designed so a user can paste a GitHub repository URL or visit a repository route directly. Setting OPENWIKI_DISABLE_REPOSITORY_CREATION=1 changes that posture: existing indexed wikis remain readable, but unknown or unindexed repository routes will not create database rows or start generation. This is useful when you want a read-only public wiki catalog, tighter cost control, or a launch phase where administrators pre-index repositories before exposing them.

Sources: README.md

Model tuning is another cost and quality control point. The README identifies OPENWIKI_INDEX_MODEL as the model used for outline and page generation, with openai/gpt-5.5 as the default in the visible table. Because OpenWiki generates source-grounded pages and page-level citations, the index model affects planning, synthesis, and output quality. Treat model changes as deployment configuration: verify cost, latency, and generated output quality in a preview or local environment before applying them to a public deployment.

Sources: README.md

Next, configure storage first, then GitHub access, then public creation policy, and finally model tuning. A practical checklist is: confirm DATABASE_URL, confirm Blob access with BLOB_STORE_ID or local Blob credentials, decide whether GITHUB_TOKEN is needed for your expected repository sizes, decide whether new repositories may be created publicly, and run a repository route as an end-to-end smoke test. For the surrounding setup path, continue with the deployment, local development, storage, and indexing pipeline pages.