GitHub - seoes/proval: Self-Hosted LLM Code Review Agent with a single Docker Image
A Self-hosted LLM code review agent. Connect it to your Git host, bring your own model, and let it review pull requests and issues on your own infrastructure.
demo.mp4Video 3
- **Easy deploy** Proval takes 3 min, less than 10 lines to deploy to your server
- **Bring your own LLM (Even local models)** Proval works with OpenAI-compatible Chat Completions APIs, so you can use OpenAI, local model APIs like Ollama and llama.cpp, or any internal LLM gateway. Anthropic and Gemini support are planned as first-class integrations.
- **GitLab, Forgejo, and GitHub support** Proval supports GitLab, Forgejo, and GitHub. Gitea and Codeberg are also a natural fit through Forgejo-compatible APIs.
- **Run it on your own network** Use Proval inside an internal network, homelab, or privacy-focused environment without depending on an external review SaaS.
Features
[](https://github.com/seoes/proval#features)
- **Pull request review** When a pull request gets a meaningful push (or a draft becomes ready), Proval reads the diff, groups changed files into review units, runs specialist sub-agents to investigate each group, and writes a consolidated review with findings grouped by severity. Each sub-agent explores the codebase on its own, so it can catch cross-file issues and hidden dependencies. Repository settings choose off, first push only, or every push.
- **Issue replies** Works on issues too. Proval leaves a comment when one opens, and can reply when someone comments back. You can set it to respond to every message or only when @mentioned.
- **Inline comments** Findings are posted directly on the affected lines of code. Proval handles single-line and multi-line positions for GitHub, GitLab, and Forgejo.
- **Threaded replies** When someone replies to a Proval comment, it reads the thread context and responds. You can set it to reply only when mentioned or reply to every comment.
- **Activity tracking** Every review, reply, and issue comment is logged with token usage so you can track model costs.
Quick start
[](https://github.com/seoes/proval#quick-start) The easiest way to try Proval is to run it with Docker Compose
Docker Compose (Recommended)
[](https://github.com/seoes/proval#docker-compose-recommended)
services: proval: image: ghcr.io/seoes/proval:latest ports:
- "7900:7900"
- "7901:7901"
volumes:
- ./data:/data
environment:
- ENCRYPTION_KEY=[Encryption Key]
ENCRYPTION_KEY is a random string generated by `openssl rand -base64 32`.
openssl rand -base64 32
LAN HTTP needs no extra setting. When the dashboard is served over HTTPS, set `COOKIE_SECURE=true` so the session cookie is marked Secure. See Quick Start HTTPS.
Docker
[](https://github.com/seoes/proval#docker)
docker run -d \ --name proval \ -p 7900:7900 \ -p 7901:7901 \ -v proval-data:/data \ -e DB_FILE_NAME=/data/app.db \ -e ENCRYPTION_KEY=[Encryption Key] \ # openssl rand -base64 32 ghcr.io/seoes/proval:latest
When the dashboard is served over HTTPS, add `-e COOKIE_SECURE=true`.
Kubernetes example
[](https://github.com/seoes/proval#kubernetes-example) Keep one replica (SQLite on `/data`), use `Recreate`, and pin an image tag. Full notes: Kubernetes example.
apiVersion: v1 kind: Secret metadata: name: proval type: Opaque stringData: encryption-key: "[Encryption Key]" --- apiVersion: v1 kind: PersistentVolumeClaim metadata: name: proval-data spec: accessModes:
- ReadWriteOnce
resources: requests: storage: 10Gi --- apiVersion: apps/v1 kind: Deployment metadata: name: proval spec: replicas: 1 strategy: type: Recreate selector: matchLabels: app: proval template: metadata: labels: app: proval spec: containers:
- name: proval
image: ghcr.io/seoes/proval:latest ports:
- name: dashboard
containerPort: 7900
- name: webhook
containerPort: 7901 env:
- name: ENCRYPTION_KEY
valueFrom: secretKeyRef: name: proval key: encryption-key
- name: DB_FILE_NAME
value: /data/app.db volumeMounts:
- name: data
mountPath: /data readinessProbe: httpGet: path: /api/health port: 7900 livenessProbe: httpGet: path: /api/health port: 7900 volumes:
- name: data
persistentVolumeClaim: claimName: proval-data --- apiVersion: v1 kind: Service metadata: name: proval spec: selector: app: proval ports:
- name: dashboard
port: 7900 targetPort: dashboard
- name: webhook
port: 7901 targetPort: webhook
How it works
[](https://github.com/seoes/proval#how-it-works)
``` Webhook event -> Repository settings -> Git provider API -> LLM agent with code review tools -> Review comments or replies
Pull request review -> Planning agent (group changed files) -> Specialist sub-agents (parallel) -> Writing agent (summary + inline comments) -> Git provider comments ```
Built with
[](https://github.com/seoes/proval#built-with)
- Bun
- Hono
- Sveltekit
- SQLite
Development
[](https://github.com/seoes/proval#development)
git clone git@github.com:seoes/proval.git cd proval bun install cp .env.example .env
fill in your env vars
bun dev
Personal Note
[](https://github.com/seoes/proval#personal-note)
I was looking for a self hosted code review using my own LLM but couldn't find one I liked. As a HomeLab user, I also found only few code review agents that worked with my personal GitLab. That's why I built this self hosted code review agent Proval
It's still early. There are rough edges, missing features. I am actively developing it and feedback is the most useful thing you can give. If you open an issue for feature request or bug report, it'll helps me and everyone else using Proval.
I believe everyone will get their own Local LLM someday. Models keep getting smarter, and they keep getting better at code review. Hardware is quite expensive now but someday it will get cheaper. Hope we can run personal LLMs with better performance, keep our data private and safe.
Planned Features
[](https://github.com/seoes/proval#planned-features)
- Custom User Prompt
- Authentication and authorization
- SSO support
- LLM Provider integration based on OAuth subscriptions
- Enhance review quality
- Reduce False Positives
- Focus on critical issues only
- Rate limit
- Only respond to certain users
- Benchmark by models
License
[](https://github.com/seoes/proval#license) Licensed under the GNU Affero General Public License v3.0.