Everything needed to run your own Argus: a GitHub App, Postgres, the Go backend, the Next.js dashboard, and a Clerk instance for dashboard auth. LLM keys are BYOK — added at runtime via the dashboard, never via env.
Argus has no paid tier and no feature gating — every capability is available to every installation, hosted or self-hosted. Deep review, simulation, memory and diagrams are per-repo settings you turn on, not upsells.
SELF_HOSTED=true remains meaningful for one behavioural default: a self-host reviews unconditionally, on every opened/pushed/reopened PR, regardless of the stored auto_run setting (see Auto-run & re-review).
Argus stores everything in one Postgres database and the migrations install two extensions:
- pgvector >= 0.8.2 — required. Migration
057fails fast on anything older (iterative index scans and the parallel-HNSW-build fix are both assumed), so a managed Postgres shipping an oldervectorextension aborts the migration rather than breaking memory search later.docker compose upusespgvector/pgvector:pg16, which satisfies this. - pgcontext — optional. Installed when the server has it, skipped with a NOTICE everywhere else (no managed Postgres can install it).
The migrating role needs CREATE EXTENSION privileges.
Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (use an org account if the app should live under an org).
- App name / slug: anything you like — set the slug as
GITHUB_APP_SLUGon the backend andNEXT_PUBLIC_GITHUB_APP_SLUGon the web app. The slug drives the bot's identity end to end: commands are triggered by mentioning@<your-slug>, posted copy uses that mention, and the backend recognizes its own comments as<your-slug>[bot]. - Homepage URL: your dashboard URL (
DASHBOARD_BASE_URL).
- Webhook URL:
https://<your-backend-host>/webhooks/github - Webhook secret: generate one (
openssl rand -hex 32) and set the same value asGITHUB_WEBHOOK_SECRET.
These match the API calls the backend actually makes:
| Permission | Access | Used for |
|---|---|---|
| Pull requests | Read & write | Posting reviews and inline comments, resolving review threads, editing PR descriptions (enrichment) |
| Issues | Read & write | Posting/editing issue comments (@argus-eye command replies, status comments), reactions |
| Contents | Read & write | Reading files/diffs for review context; write is needed only by @argus-eye fix, which commits suggestion blocks via the Git Data API — use Read-only if you don't want the fix command |
| Metadata | Read | Mandatory baseline for all Apps |
pull_request— triggers reviews and refreshes the graph after a mergepush— refreshes the graph when the default branch movespull_request_review_comment— reply analysis on inline comment threadsissue_comment—@argus-eyecommandsinstallation— tracks installs/uninstalls
Generate a private key on the App page, download the .pem, and point GITHUB_PRIVATE_KEY_PATH at it (or paste the PEM into GITHUB_PRIVATE_KEY). Set GITHUB_APP_ID from the App's App ID field.
GitHub can't reach localhost. For local dev, create a channel at smee.io, set it as the App's webhook URL, and relay:
export SMEE_URL=https://smee.io/your-channel
cd backend && make smee
# or: docker compose --profile dev upcd backend
cp .env.example .env # fill in the REQUIRED section
set -a; source .env; set +a # the Go binaries read the process env, not .env
go run ./cmd/migrate # apply DB migrations
go run ./cmd/argus # start the server.env.example defaults DASHBOARD_BASE_URL / API_BASE_URL to localhost and
GITHUB_APP_SLUG to a placeholder on purpose: unset, the backend falls back to
the hosted argus.reviews origins and the argus-eye slug, and your install
would post GitHub comments linking to a dashboard you don't run.
Or docker compose up from the repo root (Postgres + migrations + server) — Compose loads backend/.env for you, no export needed. Compose mounts backend/secrets/ into the container read-only and expects the GitHub App PEM at backend/secrets/github-app.pem — GITHUB_PRIVATE_KEY_PATH from backend/.env is overridden inside the container.
Deploying on Fly.io: change the app name in backend/fly.toml, then fly deploy from backend/.
Argus uses Clerk for dashboard sign-in and API auth.
- Create a Clerk application (enable GitHub as a social provider for the smoothest install flow).
- Web (
web/.env.local):NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYCLERK_SECRET_KEYNEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in,NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
- Backend: set
CLERK_JWKS_URLto your instance's JWKS endpoint, e.g.https://<your-subdomain>.clerk.accounts.dev/.well-known/jwks.json.
When CLERK_JWKS_URL is unset the backend cannot verify JWTs and every authenticated API route returns 503 authentication not configured — webhooks and reviews still work, but the dashboard API is unusable. There is no auth bypass mode.
-
Set
ENCRYPTION_KEYon the backend (openssl rand -hex 32) — provider keys are encrypted at rest with it. -
Open the dashboard Providers page and add your key: OpenRouter, Vercel AI Gateway, or any OpenAI-compatible endpoint (OpenAI, Azure, Groq, Together, Ollama, vLLM, ...).
For Vercel AI Gateway, model IDs use
creator/modelform (e.g.openai/gpt-5.6-sol). Append?only=<provider>to the base URL — comma-separated for several — to pin which upstream serves the request, e.g.https://ai-gateway.vercel.sh/v1?only=azure. Without it the gateway chooses, and may fall back between your own BYOK credentials and Vercel-billed ones. -
Pick models per pipeline stage on the Settings page.
Reviews fail with an onboarding comment ("configure your API key") until a provider key and model config exist.
cd web
cp .env.local.example .env.local # Clerk keys + NEXT_PUBLIC_API_URL
pnpm install
pnpm devPoint NEXT_PUBLIC_API_URL at your backend and set CORS_ALLOW_ORIGIN on the backend to the dashboard origin.
Diagrams are optional and off by default — leave both MERMAID_VALIDATOR_* vars
unset and the rest of the review works unchanged. Setting only one of the pair is
a startup error (must be configured together), not a warning.
PR diagrams use the dashboard's server-side Mermaid parser before the backend stores a diagram or edits a PR description. Generate one shared value (openssl rand -hex 32) and set it as MERMAID_VALIDATOR_SECRET on both the backend and web deployment. Set MERMAID_VALIDATOR_BASE_URL on the backend to the explicit origin of that web deployment; it must be reachable from the backend. The backend has no validator-origin default and refuses an unpaired URL or secret, so it cannot send private diagram evidence or the shared secret to the vendor dashboard by accident. DASHBOARD_BASE_URL remains the link target for GitHub comments. Diagram generation fails closed when the parser service, shared secret, or deployed Mermaid version is unavailable; the rest of the review still completes.
Auto-run is on by default. Every PR that opens, gets pushed to, or is reopened is reviewed automatically — no checkbox, no manual trigger. A push to an open PR re-reviews only the commits added since the last completed review (the inter-diff), carrying prior findings forward.
Precedence: an explicit per-repo setting wins, else the org default, else on. To
turn auto-run off, set auto_run: false — per repo on the dashboard
Settings page, or org-wide as an org default. When off, a push does not review
silently: Argus posts a one-shot "Trigger Argus review" checkbox comment (with a
token/cost estimate) once per PR; reviewers tick it to run on demand, or use
@<your-slug> review.
SELF_HOSTED=true overrides all of this: a self-host always auto-runs, regardless
of the stored auto_run flag (there is no billing to gate).
Auto-resolve is a separate toggle (auto_resolve_enabled, also on by default).
On every push it closes stale finding threads whose flagged lines the push
modified — but only after an LLM judge confirms the change actually fixed the
finding (proximity alone never resolves). It runs independently of auto-run, so a
manual-review repo still gets stale comments cleared when a fix lands. Set
auto_resolve_enabled: false for manual-only thread control.
Optional: Jev classifier front-runner. Setting TYPESAFE_API_KEY on the
backend puts TypeSafe's System One model in front of five typed-decision
surfaces:
- Addressed judge (auto-resolve on push) — finding text + the inter-diff hunk
- Convention-relation classifier (memory write gate) — candidate + stored conventions
- Intent verification — the extracted PR-intent block (goal, non-goals, acceptance criteria) + file list + finding summaries
- Scoring false-positive pre-filter — PR title, author, up to 1500 chars of PR body, the review-contract summary, and every finding
- Triage shadow (observe-only calibration) — path, status, and up to ~2400 chars of raw diff for up to 40 files, on every review
Confident Jev answers skip or shrink the LLM call; anything uncertain escalates to the configured model unchanged (the triage shadow never changes behavior).
Jev egress requires BOTH gates open:
-
TYPESAFE_API_KEYset on the backend, and -
per-installation opt-in —
installations.feature_flagscontaining"jev_classifier": true. The flag defaults OFF, so the env key alone never sends tenant code to TypeSafe. Opt in per installation (or fleet-wide) via SQL:UPDATE installations SET feature_flags = feature_flags || '{"jev_classifier": true}'::jsonb;
Opting in sends the data listed above to api.typesafe.ai for that
installation only; every other installation's reviews stay fully in-model.
Per-installation BYOK. An installation can instead set its own TypeSafe
key in Settings → Providers ("TypeSafe Jev"). A stored key takes precedence
over TYPESAFE_API_KEY for that installation and does not require the
jev_classifier flag — adding the key is the installation's consent to
egress. A custom base URL can be stored alongside the key.
backend/.env.example— every env var, annotated- docs/architecture.md — pipeline internals
- docs/CONTRIBUTING.md — development workflow