Storage backends

Choose where Qodex stores screenshots, videos, DOM snapshots, logs, attachments, and other test artifacts.

Storage backends

Qodex stores product state in Postgres and stores large artifacts in a blob backend.

Artifacts include screenshots, videos, DOM snapshots, console logs, network logs, uploaded attachments, and large tool-call payloads. These files are important for debugging failed tests and reviewing findings.

Backend choices

Backend	Best for	Notes
Local disk	Development and small single-host deployments.	Store files under /data/blobs and mount /data persistently.
S3	Production AWS deployments.	Durable storage, presigned URLs, IAM-based access.
S3-compatible service	On-premise or non-AWS deployments.	Works with MinIO, Cloudflare R2, Backblaze B2, Wasabi, and similar services.

Qodex chooses the backend at boot with:

STORAGE_BACKEND=local

or:

STORAGE_BACKEND=s3

If unset, production defaults to s3 and development defaults to local.

Local storage

Local storage writes artifact files to disk.

In the Docker image, the default state directory is /data, so artifacts land under:

/data/blobs

Mount /data as a named volume or host directory:

docker run -v qodex-data:/data ...

Use local storage when the deployment is small and the host disk is backed up. Do not use an ephemeral container filesystem for production artifacts.

S3 storage

S3 storage is the recommended production backend.

Set:

STORAGE_BACKEND=s3
S3_BUCKET=qodex-blobs
AWS_REGION=us-east-1

Qodex uses the normal AWS SDK credential chain. On ECS Fargate, the preferred setup is an IAM task role with permissions to put, get, and delete objects in the artifact bucket.

Qodex uses presigned URLs for direct upload and download flows, so large files do not need to pass through the application server.

S3-compatible storage

For MinIO, Cloudflare R2, Backblaze B2, Wasabi, or another compatible service, set an endpoint and credentials:

STORAGE_BACKEND=s3
S3_BUCKET=qodex-blobs
AWS_REGION=us-east-1
AWS_ENDPOINT_URL=http://minio:9000
AWS_ACCESS_KEY_ID=minio
AWS_SECRET_ACCESS_KEY=...

The service must support SigV4 presigned URLs.

What Qodex stores

Prefix	Typical content
screenshots/	Per-step screenshots from UI runs and PR review checks.
video/	Scenario-level recordings when capture is enabled.
dom/	DOM snapshots, especially on failure.
logs/	Console and network logs.
attachments/	Uploaded files before Qodex disperses them into product objects.
tool-calls/	Tool payloads too large for chat transcripts.

API-only runs usually write fewer artifacts. UI runs with video enabled can write much more.

Retention and lifecycle

Artifacts are often the evidence behind findings. If you expire them too early, the finding still exists but evidence links may no longer open.

A reasonable starting point:

• Keep recent screenshots and videos hot for 90 days.
• Expire temporary attachment staging paths after 7 days.
• Expire or archive logs after 180 days.
• Move older high-volume artifacts to cheaper storage when supported.

Tune this based on how long your team needs to audit failures.

Moving from local to S3

There is no built-in migration command. To move existing artifacts:

1. Stop Qodex.
2. Sync the local blob directory to S3.
3. Set STORAGE_BACKEND=s3 and the S3 variables.
4. Start Qodex again.

Because artifact keys are stored in Postgres, keep the same key paths when syncing.

Next steps

Environment variables

See every storage-related variable.

Single-container deploy

Mount /data for local storage.

AWS Terraform reference

Review the production S3 layout.

Secret management

Understand what is encrypted separately from artifacts.