> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosted

> Run Qodex in your own infrastructure with the same agent, scenarios, findings, and PR review workflows as Qodex Cloud.

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

The container exposes port `3000` for HTTP and WebSocket traffic.

## Choose a deployment path

<CardGroup cols={2}>
  <Card title="Single-container deploy" icon="box" href="/self-hosted-single-container">
    Run one Qodex container against an existing Postgres database.
  </Card>

  <Card title="Docker Compose" icon="layers" href="/self-hosted-docker-compose">
    Run Qodex and Postgres together on one host.
  </Card>

  <Card title="AWS Terraform reference" icon="cloud" href="/self-hosted-aws-terraform">
    Use the production AWS shape: ECS Fargate, RDS, ALB, ECR, S3, and CloudWatch.
  </Card>

  <Card title="Environment variables" icon="settings" href="/self-hosted-environment-variables">
    Configure required keys, storage, database, auth, and integration settings.
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="Storage backends" icon="hard-drive" href="/self-hosted-storage-backends">
    Choose local disk, S3, or an S3-compatible service.
  </Card>

  <Card title="Secret management" icon="key" href="/self-hosted-secret-management">
    Understand `QODECLAW_SECRET_KEY`, encrypted values, and rotation.
  </Card>
</CardGroup>

## Production notes

For production, set a real `QODECLAW_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

<CardGroup cols={2}>
  <Card title="Start with Docker" icon="box" href="/self-hosted-single-container">
    The fastest self-hosted path.
  </Card>

  <Card title="Go to production on AWS" icon="cloud" href="/self-hosted-aws-terraform">
    Follow the reference production deployment.
  </Card>
</CardGroup>