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

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

```bash theme={null}
STORAGE_BACKEND=local
```

or:

```bash theme={null}
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:

```text theme={null}
/data/blobs
```

Mount `/data` as a named volume or host directory:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Environment variables" icon="settings" href="/self-hosted-environment-variables">
    See every storage-related variable.
  </Card>

  <Card title="Single-container deploy" icon="box" href="/self-hosted-single-container">
    Mount `/data` for local storage.
  </Card>

  <Card title="AWS Terraform reference" icon="cloud" href="/self-hosted-aws-terraform">
    Review the production S3 layout.
  </Card>

  <Card title="Secret management" icon="key" href="/self-hosted-secret-management">
    Understand what is encrypted separately from artifacts.
  </Card>
</CardGroup>