BugViper is configured entirely through environment variables. Copy .env.example to .env in your project root and fill in the values below before starting any service. Required variables must be set for BugViper to start; optional variables enable additional features or override sensible defaults.
Database (Neo4j)
Neo4j is BugViper’s primary data store. Every indexed repository, function, class, variable, and relationship lives in the graph. BugViper works with a local Neo4j instance or a managed Neo4j AuraDB cloud database.
| Variable | Required | Default | Description |
|---|
NEO4J_URI | Yes | bolt://localhost:7687 | Connection URI for your Neo4j instance. Use bolt:// for local or unencrypted connections and neo4j+s:// for AuraDB and other TLS-secured cloud databases. |
NEO4J_USERNAME | Yes | neo4j | Database username. The default Neo4j installation uses neo4j. |
NEO4J_PASSWORD | Yes | — | Password for the Neo4j user. Set during database creation or in your AuraDB dashboard. |
NEO4J_DATABASE | No | neo4j | The database name to connect to. The default Neo4j installation uses a single database named neo4j. Only change this if you have created a dedicated database for BugViper. |
# Local Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j
# Neo4j AuraDB
NEO4J_URI=neo4j+s://abc123.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_aura_password
NEO4J_DATABASE=neo4j
AI / LLM (OpenRouter)
BugViper routes all LLM and embedding calls through OpenRouter, a single API that gives access to hundreds of models from OpenAI, Anthropic, Google, Meta, and others. You only need one OpenRouter key for everything.
| Variable | Required | Default | Description |
|---|
OPENROUTER_API_KEY | Yes | — | Your OpenRouter API key. Used for all LLM calls (code review, synthesis, chat agent) and for generating code embeddings. Get one at openrouter.ai. |
REVIEW_MODEL | No | openai/gpt-4o-mini | The model BugViper’s Explorer and Reviewer nodes use during a pull request review. Accepts any valid OpenRouter model slug. See Configure AI models for recommendations. |
SYNTHESIS_MODEL | No | openai/gpt-4o-mini | The model used by the Summarizer node to produce the structured walkthrough and final summary after the Explorer completes its investigation. Can differ from REVIEW_MODEL to optimize cost. |
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
REVIEW_MODEL=anthropic/claude-sonnet-4-5
SYNTHESIS_MODEL=openai/gpt-4o-mini
GitHub App
BugViper communicates with GitHub through a GitHub App you register under your account or organization. The App is what allows BugViper to receive webhook events, clone repositories, and post inline review comments.
| Variable | Required | Default | Description |
|---|
GITHUB_APP_ID | Yes | — | The numeric App ID shown at the top of your GitHub App’s settings page under General. |
GITHUB_PRIVATE_KEY_PATH | Yes | — | Absolute path to the .pem private key file you downloaded when you created the GitHub App. Keep this file outside your project directory and never commit it. |
GITHUB_WEBHOOK_SECRET | Yes | — | The secret string you entered when configuring your GitHub App’s webhook. BugViper uses this to verify that incoming webhook payloads genuinely originate from GitHub. |
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=/secrets/bugviper-app.private-key.pem
GITHUB_WEBHOOK_SECRET=a1b2c3d4e5f6...
Generate a strong webhook secret with openssl rand -hex 20. Store it in your .env and paste the same value into your GitHub App’s webhook settings — the two must match exactly.
Firebase
BugViper uses Firebase (Firestore) to store user accounts, repository metadata, and pull request review history. You need a Firebase service account JSON file to authenticate the Admin SDK.
| Variable | Required | Default | Description |
|---|
SERVICE_FILE_LOC | Yes | — | Absolute path to your Firebase service account JSON file. Download it from Firebase Console → Project Settings → Service Accounts → Generate new private key. |
SERVICE_FILE_LOC=/secrets/firebase-service-account.json
Never commit your service account JSON to version control. Add the file path to .gitignore and store it outside your repository directory.
Review behavior (optional)
These variables let you tune what BugViper does during a pull request review without changing models or infrastructure.
| Variable | Required | Default | Description |
|---|
ENABLE_PR_DESCRIPTION_UPDATE | No | true | When true, BugViper updates the PR description with a structured summary after the review completes. Set to false if you prefer BugViper to only post comments without modifying the description. |
MAX_TOOL_ROUNDS | No | 8 | Maximum number of graph tool calls the Explorer node can make per file during a review. Lowering this value reduces cost and latency for simple files. Raising it gives the agent more room to investigate complex files. Try 4–5 for most repositories. |
ENABLE_PR_DESCRIPTION_UPDATE=true
MAX_TOOL_ROUNDS=8
Observability (optional)
BugViper supports two observability backends. Both are disabled by default.
Pydantic Logfire
| Variable | Required | Default | Description |
|---|
ENABLE_LOGFIRE | No | false | Set to true to enable Pydantic Logfire tracing. Logfire captures structured traces for every review run, ingestion job, and API request. |
LOGFIRE_TOKEN | No | — | Your Logfire project token. Required when ENABLE_LOGFIRE=true. |
ENABLE_LOGFIRE=true
LOGFIRE_TOKEN=your_logfire_token_here
LangSmith
| Variable | Required | Default | Description |
|---|
LANGCHAIN_TRACING_V2 | No | false | Set to true to enable LangSmith tracing for LangGraph agent runs. |
LANGCHAIN_API_KEY | No | — | Your LangSmith API key. Required when LANGCHAIN_TRACING_V2=true. |
LANGCHAIN_ENDPOINT | No | https://api.smith.langchain.com | LangSmith API endpoint. Only change this if you are running a self-hosted LangSmith instance. |
LANGCHAIN_PROJECT | No | BugViper | The LangSmith project name that traces are grouped under. |
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls__xxxxxxxxxxxxxxxxxxxx
LANGCHAIN_PROJECT=BugViper
Networking
| Variable | Required | Default | Description |
|---|
API_ALLOWED_ORIGINS | Yes | http://localhost:3000 | Comma-separated list of origins that are allowed to make cross-origin requests to the BugViper API. In production, set this to your frontend’s domain (e.g., https://app.yourdomain.com). |
CLONE_DIR | No | System temp directory | Directory where BugViper clones repositories during ingestion. Must be writable by the process running BugViper. Defaults to the OS temp directory if left unset. |
NGROK_DOMAIN | No | — | Your reserved ngrok domain (e.g., your-name.ngrok-free.app). Set this during local development so the ./start.sh script can launch ngrok with a stable, predictable webhook URL. |
API_ALLOWED_ORIGINS=https://app.yourdomain.com,https://staging.yourdomain.com
CLONE_DIR=/var/data/bugviper-repos
NGROK_DOMAIN=your-name.ngrok-free.app