Self-hosting CodeBeaver

CodeBeaver runs entirely in your own Cloudflare account: the Worker (webhook receiver + review pipeline), a KV namespace, a Vectorize index, six Queues, three Durable Objects, and the dashboard as a static SPA. Your LLM keys stay in your Cloudflare secrets; review data stays in your account.

Prerequisites

• A Cloudflare account (Workers Paid recommended — Queues and Workers AI have free allocations, but production review volume exhausts them quickly);
• Node.js 22+, pnpm 11, Git;
• pnpm exec wrangler login completed;
• a zone in that account, only if you pass --domain.

Quick start

From the repository root:

pnpm install --frozen-lockfile
pnpm selfhost:init

The installer:

1. reads your Cloudflare account id from wrangler whoami and fills both wrangler.toml files;
2. creates the KV namespace codebeaver-review-cache, the Vectorize index codebeaver-codebase (768 dims, cosine), and the six queues the Worker consumes;
3. comments out the [[routes]] and [[services]] blocks unless you pass --domain <zone> (see below);
4. builds and deploys the Worker, prompts for secrets (see below), health checks /health, then builds and deploys the dashboard with its API base URL pointed at your Worker.

Re-run --dry-run first to see what it would do:

node scripts/selfhost-init.mjs --dry-run

Flags: --domain <zone> serve on codebeaver.<zone>; --skip-secrets set secrets yourself afterwards; --skip-deploy provision and configure only.

Custom domain

By default the Worker serves on https://codebeaver.<your-subdomain>.workers.dev and the dashboard on its own workers.dev URL. To serve on your own zone:

node scripts/selfhost-init.mjs --domain example.com

This routes the Worker at codebeaver.example.com/api/* and the dashboard at codebeaver.example.com, and disables the workers.dev endpoints. The zone must already exist in the same Cloudflare account.

Secrets

The installer prompts for these and stores them with wrangler secret put (values never touch the shell history; the private key may be pasted as one line with \n between PEM lines):

Secret	Required	Purpose
GITHUB_APP_ID	yes	your GitHub App
GITHUB_APP_WEBHOOK_SECRET	required	webhook HMAC verification
GITHUB_APP_PRIVATE_KEY	required	signing App API calls
REVIEW_MODEL	optional	primary model (default deepseek-v4-flash)
REVIEWER_API_KEY	optional	OpenRouter-compatible fallback key
REVIEWER_API_KEY_ZAI	optional	Z.ai Coding key (preferred GLM provider)

Provider resolution order and every other variable are documented in .env.example. Model routing without hosted keys:

export CODEBEAVER_API_KEY=your-provider-key
codebeaver review --local

Local mode performs a single model pass against your key with no hosted pipeline (see the CLI guide).

GitHub App

Create the App as described in the GitHub App guide:

• webhook URL: your Worker URL;
• events: pull_request, issue_comment, pull_request_review, pull_request_review_comment, merge_queue_entry;
• permissions and configuration per the guide;
• download the .pem and store it as GITHUB_APP_PRIVATE_KEY.

Then install the App on the repositories it should review and add a .codebeaver.yaml to those repositories when the defaults do not fit.

Dashboard

The dashboard is a static SPA served by the Worker deploy in apps/dashboard. The installer sets VITE_CODEBEAVER_API_BASE_URL to your Worker URL before building. Put the dashboard behind Cloudflare Access before sharing it — it is an admin UI, and its browser API assumes an Access-authenticated caller (dashboard guide).

CLI authentication

Self-host does not deploy an api-admin worker (the installer comments out the API_ADMIN binding). Two supported CLI setups:

• set API_ADMIN_BASE_URL to a service that can exchange GitHub OAuth codes for pr-reviewer auth login; or
• skip hosted CLI auth entirely and use --local mode.

Operational runbook

Health checks, logs, provider routing, recovery, and live evals are covered in Operations — written for the hosted reference deployment, but the local checks and health endpoints apply unchanged to self-hosted instances.

Uninstall

pnpm exec wrangler delete                      # Worker
pnpm --dir apps/dashboard exec wrangler delete # dashboard
wrangler kv namespace delete codebeaver-review-cache
wrangler vectorize delete codebeaver-codebase
# queues: wrangler queues delete <name> for each of the six

Queue contents (review history, learning rules) are deleted with the namespaces; there is no export tool yet — see the roadmap for what is planned.

Licensing

Self-hosting CodeBeaver is free for your own organisation's internal business purposes under the Business Source License 1.1 (see LICENSE). Operating CodeBeaver for organisations other than your own — as a hosted or managed service, or by reselling access — requires a commercial license from the Licensor (see LICENSE-COMMERCIAL.md).