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
The container exposes port
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.