Self-hosted
Self-hosted Qodex runs the Qodex app and agent inside your infrastructure. The simplest deployment is one Docker container connected to Postgres. Larger deployments can split web, worker, and scheduler processes, use S3 for artifacts, and run behind your own load balancer.What you get
Self-hosted Qodex includes the same core product surfaces:- Agent chat for API, UI, security, and PR review work.
- Saved scenarios, scripts, findings, memory, and run history.
- Browser-driven UI testing through Playwright.
- Artifact capture for screenshots, videos, logs, and DOM snapshots.
- GitHub, Slack webhook, generic webhook, email, and BYOK integrations.
- Project-level configuration and access control.
Required pieces
| Requirement | Why it is needed |
|---|---|
| Container runtime | Runs the Qodex image. Docker, Podman, ECS, or another OCI runner works. |
| Postgres 16 or 17 | Stores projects, users, scenarios, findings, runs, chats, and configuration. |
| LLM provider key | Powers agent reasoning when a project does not provide its own BYOK key. |
| Persistent blob storage | Stores screenshots, videos, DOM snapshots, logs, and attachments. |
| Secret key | Encrypts BYOK keys, OAuth credentials, and sensitive auth values at rest. |
3000 for HTTP and WebSocket traffic.
Choose a deployment path
Single-container deploy
Run one Qodex container against an existing Postgres database.
Docker Compose
Run Qodex and Postgres together on one host.
AWS Terraform reference
Use the production AWS shape: ECS Fargate, RDS, ALB, ECR, S3, and CloudWatch.
Environment variables
Configure required keys, storage, database, auth, and integration settings.
Storage and secrets
Qodex separates relational data from artifacts. Postgres stores product state. Blob storage stores files created during testing, such as screenshots and videos. Secrets are encrypted before they are stored in Postgres.Storage backends
Choose local disk, S3, or an S3-compatible service.
Secret management
Understand
QODECLAW_SECRET_KEY, encrypted values, and rotation.Production notes
For production, set a realQODECLAW_SECRET_KEY, use managed Postgres backups, keep artifacts in S3 or another durable store, and put Qodex behind HTTPS.
Redis is optional. Without Redis, the scheduler and agent runner execute in-process. With Redis, worker and scheduler processes can run separately, which is the production-oriented shape.
Roadmap
A Kubernetes Helm chart is planned. Today, the supported documentation paths are Docker, Docker Compose, and the AWS Terraform reference.Next steps
Start with Docker
The fastest self-hosted path.
Go to production on AWS
Follow the reference production deployment.