Skip to main content
BugViper reads its configuration from environment variables. The sections below explain what each variable does and how to find the right value. Required variables must be present before BugViper will start; optional variables enable additional features or override sensible defaults.

​
Neo4j database

BugViper stores your code knowledge graph in Neo4j. You can run Neo4j locally with Docker or use Neo4j AuraDB for a managed cloud instance.
VariableRequiredDefaultDescription
NEO4J_URIYes—Bolt connection string to your Neo4j instance, e.g. bolt://localhost:7687. For AuraDB, use the neo4j+s:// URI from the Aura console.
NEO4J_USERNAMEYes—Neo4j username. Defaults to neo4j for a fresh local instance.
NEO4J_PASSWORDYes—Neo4j password. Set this when you create your local instance or copy it from the Aura console.
NEO4J_DATABASEYesneo4jThe database name inside your Neo4j instance. Leave as neo4j unless you’ve created a named database.
To spin up a local Neo4j instance with Docker: 
docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:5

​
OpenRouter (LLM and embeddings)

BugViper uses OpenRouter as its LLM gateway. A single API key covers both the review agent and the embedding pipeline.
VariableRequiredDefaultDescription
OPENROUTER_API_KEYYes—Your OpenRouter API key. Get one at openrouter.ai/keys. This key is used for all LLM calls (review, synthesis) and for generating embeddings via text-embedding-3-small.
REVIEW_MODELNoopenai/gpt-4o-miniThe OpenRouter model slug used by the Explorer node — the agent that investigates the codebase before writing review comments. Any model available on OpenRouter works here, e.g. anthropic/claude-sonnet-4-5 or google/gemini-flash-1.5.
SYNTHESIS_MODELNoopenai/gpt-4o-miniThe model used by the Reviewer and Summarizer nodes to produce structured findings from the Explorer’s accumulated context. Supports any OpenRouter model — structured output is extracted robustly from the response, so native JSON mode is not required.
Higher-capability models produce more accurate findings but cost more per review. A review with anthropic/claude-sonnet-4-5 costs approximately $0.12 per file. You can set REVIEW_MODEL and SYNTHESIS_MODEL to different models — for example, use a capable model for exploration and a faster model for synthesis.

​
GitHub App

These credentials come from the GitHub App you created during setup. See the GitHub App setup guide if you haven’t created one yet.
VariableRequiredDescription
GITHUB_APP_IDYesThe numeric App ID shown at the top of your GitHub App’s settings page.
GITHUB_PRIVATE_KEY_PATHYesAbsolute path to the .pem private key file you downloaded from your GitHub App settings. The BugViper process must be able to read this file at runtime.
GITHUB_WEBHOOK_SECRETYesThe random string you set as the webhook secret when creating the GitHub App. BugViper uses this to verify that incoming webhook payloads are from GitHub.
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=/path/to/your-app.private-key.pem
GITHUB_WEBHOOK_SECRET=your_webhook_secret_here

​
Firebase

BugViper uses Firebase for user authentication (via Firebase Auth) and for storing repository metadata and PR review results (via Firestore). You need a Firebase project with a service account.
VariableRequiredDescription
SERVICE_FILE_LOCYesPath to your Firebase service account JSON file. Generate one in the Firebase console under Project Settings → Service Accounts → Generate new private key.
SERVICE_FILE_LOC=/path/to/service-account.json
Never commit your service account JSON file to source control. It grants broad access to your Firebase project. The file is already in .gitignore, but double-check if you’ve moved it to a different location.

​
Review agent

These variables control how the AI review agent behaves. All are optional — the defaults work well for most repositories.
VariableDefaultDescription
MAX_TOOL_ROUNDS8Maximum number of Neo4j tool calls the Explorer node can make per file before moving to synthesis. Reducing this lowers cost per review; increasing it gives the agent more time to investigate complex files.
ENABLE_PR_DESCRIPTION_UPDATEtrueWhen true, BugViper updates the pull request description with a structured summary including a walkthrough table, impact analysis, and positive findings. Set to false to post findings as comments only.

​
CORS

VariableDefaultDescription
API_ALLOWED_ORIGINShttp://localhost:3000Comma-separated list of origins that are allowed to make cross-origin requests to the BugViper API. In production, set this to your frontend’s public URL. Example: https://bugviper.yourcompany.com.

​
Optional: observability

BugViper supports Logfire for structured observability. When enabled, traces for every review run, ingestion job, and database query are sent to your Logfire project.
VariableDefaultDescription
ENABLE_LOGFIREfalseSet to true to enable Logfire tracing.
LOGFIRE_TOKEN—Your Logfire project token. Required when ENABLE_LOGFIRE=true.

​
Optional: repository cloning

VariableDefaultDescription
CLONE_DIRSystem temp directoryDirectory where BugViper clones repositories before parsing. Set this if you want clones to go to a specific path with enough disk space for large repositories.

​
Optional: ngrok

If you’re running BugViper locally, ngrok lets GitHub deliver webhook events to your machine. Reserve a domain in the ngrok dashboard for a stable webhook URL.
VariableDescription
NGROK_DOMAINYour reserved ngrok domain (e.g. your-name.ngrok-free.app). When set and you run ./start.sh, BugViper starts ngrok automatically on this domain.

​
Optional: LangSmith tracing

BugViper emits LangChain/LangGraph traces that you can view in LangSmith. Useful for debugging the review agent’s tool calls and reasoning steps.
VariableDefaultDescription
LANGCHAIN_TRACING_V2falseSet to true to enable LangSmith tracing.
LANGCHAIN_API_KEY—Your LangSmith API key.
LANGCHAIN_PROJECTBugViperThe LangSmith project name where traces are sent.