BugViper Core Environment Variables Reference Guide

Reference for BugViper’s core environment variables: GitHub App credentials, Firebase service account, LLM provider keys, and frontend URLs.

When self-hosting BugViper, all configuration is done via environment variables in your .env file. Every service — the API, the review pipeline, and the frontend — reads from this single file at startup, so getting it right before you launch is essential.

Start by copying the example file so you have all variables pre-populated with their defaults:

cp .env.example .env

Then open .env and fill in the values for your environment.

Required Variables

These four variables must be set before BugViper can start. Without them, the API will fail to authenticate with GitHub and Firebase.

GITHUB_APP_ID · string · required

Your GitHub App’s numeric ID. You can find this on the General settings page of your GitHub App, listed at the top as App ID.

GITHUB_PRIVATE_KEY_PATH · string · required

The path to the .pem private key file you downloaded when creating your GitHub App. For example: /home/user/bugviper/your-app.private-key.pem. BugViper uses this key to authenticate as the app and post review comments.

GITHUB_WEBHOOK_SECRET · string · required

The secret string you set when configuring your GitHub App’s webhook. GitHub signs every incoming webhook payload with this secret, and BugViper uses it to verify that events are legitimate. Generate a strong value with: openssl rand -hex 20.

SERVICE_FILE_LOC · string · required

The path to your Firebase service account JSON file. BugViper uses the Firebase Admin SDK for user management, PR review storage, and repository metadata. For example: /home/user/bugviper/service-account.json. Never commit this file to version control.

LLM Provider Keys

At least one LLM provider key is required for the AI review agent to function. You can configure one or more providers simultaneously — BugViper will use whichever provider matches the model string you set for each role.

OPENROUTER_API_KEY · string

API key for OpenRouter. OpenRouter acts as a unified gateway to hundreds of models including Claude, GPT-4o, DeepSeek, Mistral, and more. This is the most flexible option and is required when any model string does not begin with gemini/ or MiniMax-.

GEMINI_API_KEY · string

API key for Google Gemini. Required when any model role is configured with a model string beginning with gemini/. Obtain your key from Google AI Studio.

MINIMAX_API_KEY · string

API key for the MiniMax LLM provider. Required when any model role is configured with a model string beginning with MiniMax-.

Frontend Variables

These variables are consumed by the Next.js frontend. Because they are exposed to the browser, they must be prefixed with NEXT_PUBLIC_.

NEXT_PUBLIC_API_BASE_URL · string · default: "http://localhost:8000"

The URL of the BugViper API service. The frontend uses this for all API calls — fetching repos, analytics, review results, and more. In local development, this is http://localhost:8000. In production, point this to your deployed API service URL.

NEXT_PUBLIC_GITHUB_APP_INSTALL_URL · string

The public installation URL for your GitHub App. This is shown as the “Install App” button in the BugViper dashboard so users can connect new repositories. You can find this URL in your GitHub App settings under Public link.

CORS

API_ALLOWED_ORIGINS · string · default: "http://localhost:3000"

A comma-separated list of origins that the BugViper API will accept cross-origin requests from. In local development, this is typically http://localhost:3000. In production, set this to your deployed frontend domain — for example, https://bugviper.yourdomain.com. Multiple origins are supported: https://app.example.com,https://staging.example.com.