32 — Configuration reference

Configuration layers

environment/secrets supplied by the operator;
validated non-secret instance configuration stored in PostgreSQL;
user preferences;
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.

4.3 KiB Raw Blame History