# 32 — Configuration reference

## Configuration layers

1. environment/secrets supplied by the operator;
2. validated non-secret instance configuration stored in PostgreSQL;
3. user preferences;
4. request-specific choices.

Server-only environment values never enter client bundles or generated prompts.

## Required environment values

| Variable | Requirement |
|---|---|
| `DATABASE_URL` | PostgreSQL connection string; never logged in full |
| `PUBLIC_BASE_URL` | Absolute externally used URL |
| `SESSION_SECRET` | Random value of at least 32 bytes |
| `INTEGRATION_ENCRYPTION_KEY` | Base64-encoded 32-byte active key |
| `INTEGRATION_ENCRYPTION_KEY_VERSION` | Stable operator-managed version label |
| `CONTENT_ROOT` | Absolute container path to built-in/operator content |
| `ARTIFACT_ROOT` | Absolute container path to generated artifacts |

Optional old integration keys use a versioned secret-map format defined by the implementation and documented in `.env.example`.

## Bootstrap and proxy values

- `BOOTSTRAP_TOKEN` — recommended random single-use setup token.
- `TRUSTED_PROXY_CIDRS` — reserved for a future trusted-proxy implementation;
  it is validated but does not currently authorize forwarded headers. Do not
  rely on it as a security control.
- `MAINTENANCE_MODE` — explicit boolean.

## Default limits

| Setting | Default |
|---|---:|
| Compressed import | 10 MiB |
| Expanded archive | 50 MiB |
| Files per archive | 500 |
| Single imported file | 5 MiB |
| Rendered prompt | 2 MiB |
| Raw repository evidence per composition | 256 KiB |
| Single evidence snippet | 32 KiB |
| Standard Run Pack | 5 MiB |
| API request body excluding import | 2 MiB |
| Gitea file response | 1 MiB per file |
| Gitea files per snapshot | 200 |
| Gitea redirects | 3 |
| External request timeout | 15 seconds |
| Composition timeout | 5 seconds |
| ZIP generation timeout | 30 seconds |

All limits are configurable within hard safety maxima validated by `schemas/instance-config.schema.json`.

## Retention defaults

- binary artifacts: 90 days;
- immutable generated task text: indefinite for personal self-hosting;
- repository snapshots: latest 20 plus any referenced by a profile/run;
- audit events: 180 days;
- operational logs: 30 days;
- failed import staging: immediate deletion after safe error extraction;
- expired invitations/reset tokens: 7-day cleanup grace.

Retention jobs never delete records referenced by immutable audit or generated-task contracts without the explicit documented detachment behavior.

## Gitea network policy

Default is deny for loopback, link-local, metadata and private networks. Self-hosted private Gitea requires:

- `GITEA_PRIVATE_NETWORK_POLICY=allow-explicit-hosts`; and
- exact hostnames in the operator allowlist. CIDR entries are not currently
  implemented.

The application resolves all addresses before connection and after every redirect. Authentication headers never cross host boundaries.

## Registration and telemetry

- `REGISTRATION_MODE=closed` by default.
- Product telemetry is disabled and unsupported in the reference MVP.
- No external error-reporting SaaS is enabled by default.

## Jobs

Reference defaults:

- worker polling interval: 2 seconds when notifications are unavailable;
- lease duration: 60 seconds with heartbeat;
- default max attempts: 3;
- exponential backoff: 5 seconds to 15 minutes with jitter;
- stale job warning: no progress for 5 minutes;
- artifact cleanup and integration health checks: daily.

## Logging

- default level: `info`;
- JSON in production, readable console format in development;
- request IDs accepted only from trusted proxies or regenerated;
- body logging disabled;
- prompt and repository content excluded by default;
- redaction paths include authorization, cookies, tokens, passwords, keys and encrypted envelopes.

## Content and artifacts

- Built-in content root is read-only in production.
- Operator content may be a separate read-only mount imported through an admin action.
- Artifact root must not be web-server static content.
- Download routes set safe content types and `Content-Disposition`.
- Filenames are sanitized metadata; storage keys are opaque random IDs.

## Environment example

`config/env.example` is a non-secret template. Codex must copy its fields into the implemented root `.env.example` and keep it synchronized with typed configuration tests.