Skip to content

Latest commit

 

History

History
194 lines (138 loc) · 10.7 KB

self-hosting.md

File metadata and controls

194 lines (138 loc) · 10.7 KB

Self-Hosting Argus

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).

0. Postgres requirements

Argus stores everything in one Postgres database and the migrations install two extensions:

  • pgvector >= 0.8.2 — required. Migration 057 fails fast on anything older (iterative index scans and the parallel-HNSW-build fix are both assumed), so a managed Postgres shipping an older vector extension aborts the migration rather than breaking memory search later. docker compose up uses pgvector/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.

1. Create the GitHub App

Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (use an org account if the app should live under an org).

Basics

  • App name / slug: anything you like — set the slug as GITHUB_APP_SLUG on the backend and NEXT_PUBLIC_GITHUB_APP_SLUG on 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

  • Webhook URL: https://<your-backend-host>/webhooks/github
  • Webhook secret: generate one (openssl rand -hex 32) and set the same value as GITHUB_WEBHOOK_SECRET.

Repository permissions

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

Subscribe to events

  • pull_request — triggers reviews and refreshes the graph after a merge
  • push — refreshes the graph when the default branch moves
  • pull_request_review_comment — reply analysis on inline comment threads
  • issue_comment — @argus-eye commands
  • installation — tracks installs/uninstalls

Private key

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.

2. Local webhook relay (smee)

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 up

3. Backend

cd 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/.

4. Clerk (dashboard auth)

Argus uses Clerk for dashboard sign-in and API auth.

  1. Create a Clerk application (enable GitHub as a social provider for the smoothest install flow).
  2. Web (web/.env.local):
    • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
    • CLERK_SECRET_KEY
    • NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in, NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
  3. Backend: set CLERK_JWKS_URL to 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.

5. LLM provider (BYOK)

  1. Set ENCRYPTION_KEY on the backend (openssl rand -hex 32) — provider keys are encrypted at rest with it.

  2. 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/model form (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.

  3. 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.

6. Web dashboard

cd web
cp .env.local.example .env.local   # Clerk keys + NEXT_PUBLIC_API_URL
pnpm install
pnpm dev

Point 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 & re-review

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:

  1. TYPESAFE_API_KEY set on the backend, and

  2. per-installation opt-in — installations.feature_flags containing "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.

Reference