Environment variables

Citadel runtime settings use CITADEL_ followed by uppercase words separated by single underscores. Standard tool settings such as RUST_LOG, DOCKER_HOST and PG_* retain their names. The .env downloaded in the installation guide contains the settings needed to start Citadel. Add optional settings from this reference as needed. The defaults are for local HTTP; configure TLS before sharing an installation.

The sections below cover Core and its Compose deployment, followed by Direct Agent and Edge Agent configuration. Set each variable on the process or container it belongs to; Core's .env does not configure remote Agents.

Instance controls and deployment overridesCopy Anchor Link

Administrators can manage the 26 controls described in Instance settings. MFA applies on save; the other controls apply at the next Core start. An explicitly supplied environment value overrides the saved choice even when it equals the default. The page shows deployment-managed fields and pending restarts. Remove the override from every deployment environment source and restart/recreate Core to manage that field through the UI. Existing overrides are not removed automatically. CITADEL_MFA_POLICY remains a minimum; release-check deployment restrictions remain in Updates. RUST_LOG module filters remain deployment managed.

Installation and transportCopy Anchor Link

For explicit PostgreSQL maintenance, PG_IMAGE selects an official PostgreSQL image digest and PG_DATA selects its data directory (default /var/lib/postgresql/18/docker). These are Compose controls, not application settings. Changing the major image version alone does not upgrade the data. The optional maintenance overlay uses PG_UPGRADE_IMAGE for the locally built helper and PG_SOURCE_DATA for its source directory.

CITADEL_IMAGE, COMPOSE_PROJECT_NAME, and host port settings control Compose. The application settings must reach the Core container; the supplied Compose file reads .env for this purpose. Recreate Core after editing it:

docker compose up -d server

Keep the installation's project and overlay options on that command. A container restart alone does not load a changed Compose environment.

Update checksCopy Anchor Link

No Citadel telemetry or instance data is sent. GitHub receives normal connection information, including the outbound IP address. See update checks and privacy for details and how to turn checks on or off.

Database and persistent pathsCopy Anchor Link

Core chooses its database connection in this order:

1. CITADEL_DATABASE_URL, if set: a PostgreSQL URI (postgres:// or postgresql://). A blank or malformed selected URI fails startup.
2. Otherwise, PG_HOST, PG_PORT, PG_USER, PG_PASSWORD, and PG_DATABASE; credentials are escaped when constructing the URI.

Remove unused overrides instead of leaving them blank. The supplied Compose PostgreSQL service still requires its PG_* credentials. Changing the initial database password in .env does not reset the password of an existing database.

Preserve original keys and verify the database target before control-plane recovery. A new Compose project does not isolate an external database configured by an override.

Jobs and diagnosticsCopy Anchor Link

These settings do not override resource permissions, enabled states, or license requirements. Resource schedules are configured on the resource itself.

For first-run password-file bootstrap, use the complete unattended setup procedure. For common configuration changes, see Docker Compose configuration.

Concurrency limitsCopy Anchor Link

Core prepares and tracks work; the execution host admits the expensive operation. Scripts run on Core or an Agent according to their Run on setting.

A small installation can keep these defaults. Three independent Agents with two build slots and two heavy-work slots each can execute six builds while Core prepares at most two contexts. Set a pool's Maximum concurrent builds high enough for the intended workload; the effective limit is the smallest of the pool policy, Agent build capacity and Agent shared heavy-work capacity. Aliases of one Docker daemon share its capacity.

Tracking slots do not launch extra Docker work when a host is full. A multi-volume backup processes its items sequentially and reserves the host for each item. Repository, source and restore-destination locks remain held for the protected operation. These locks renew during execution; expiry alone never permits a second operation to use storage whose cleanup is uncertain. A source-contention retry retains the resolved source plan.

Core-local builds, backup helpers and system-backup staging share two local heavy-work slots. Edge contexts have a separate 32 MiB transfer budget, charged for raw and encoded payloads; output has its own 32 MiB budget. Control commands retain independent headroom. These are bounded implementation limits, not extra configuration knobs.

More slots do not make one job faster or provide CPU/memory isolation. Increase capacity only when the executing hosts have spare resources. Lowering a pool policy prevents new over-limit admission while accepted work drains. Agent capacities are startup settings: let active work finish before recreating an Agent to change them.

Builds wait when a host is offline or busy. A known pre-execution refusal retries with a 5–15 second backoff, preserving a commit once resolved. All queued builds, including those waiting for pool capacity, expire after 24 hours. Ambiguous execution is never automatically replayed. All script runs, including manual runs and tests, queue when their selected execution hosts are full or offline. Closing a progress sheet does not cancel its run.

After changing Core variables, recreate Core with docker compose up -d server, retaining the project's overlay options. Set Agent capacities on each Agent and recreate it to apply them. The old lifecycle-wide build/backup worker variables are no longer read.

Core also persists remote build reservations per Docker daemon, so aliases do not multiply capacity. Failed or interrupted execution retains its reservation unless the same Agent confirms cleanup. Core stores that evidence before releasing capacity with the final run result; restarting an Agent is not cleanup evidence. Core also rechecks terminal reservations in batches of 16, with five-second Agent checks and 30 seconds between batches. Confirmed cleanup releases capacity without retrying the build or changing its outcome. Unreachable Agents, changed Agent identities and uncertain execution remain held. Administrators can resolve terminal holds from the build run sheet after verifying cleanup and restarting the original Agent on the same Docker daemon. Their acknowledgment is audited without retrying the build. These reconciliation bounds are not additional .env settings.

HTTP listeners and runtime limitsCopy Anchor Link

Host-published ports above are separate from the container listeners. The supplied Compose packages use the listen-port settings for container port targets and the health check reads the same HTTP port. Bare binaries have no static-root default; the packaged image sets CITADEL_STATIC_ROOT=/app/wwwroot and accepts an override.

In the development overlay, CITADEL_DEV_DOCKER_SOCKET selects the host socket mount source; Core and the entrypoint both use /var/run/docker.sock inside the container. The launcher derives this source from its native CITADEL_DOCKER_SOCKET.

Identity and bootstrapCopy Anchor Link

Keep generated keys in jwtsecret and secret-encryption-key under the persistent data root. Routine configuration changes do not require copying them into .env. If you explicitly configured CITADEL_JWT_KEY or CITADEL_SECRETS_ENCRYPTION_KEY, preserve those values across upgrades and recovery. Offline recovery never generates replacement keys.

Execution tools, paths and schedulingCopy Anchor Link

Core connections to AgentsCopy Anchor Link

Direct Agent settingsCopy Anchor Link

A Direct Agent is the Agent connector in the Platform form, also called a regular or inbound Agent in these guides. Core initiates the connection to it; this connection type is separate from Core's TLS mode.

Set these on the Agent container. The generated setup command supplies its identity and Core public key; follow the Direct Agent guide and TLS configuration.

Edge Agent settingsCopy Anchor Link

Set these on the Edge Agent container. Use the command generated by Citadel; see the Edge Agent guide. Edge mode does not read the Direct-only identity, Core public-key, or listener TLS settings above.

Preserve the Agent's data volume. Dedicated Build Pool setup commands can select profile-specific key and identity paths; keep those generated values. Core also supplies Swarm node bootstrap and identity variables automatically.

Script execution capacityCopy Anchor Link

All triggers enter the durable queue. A busy host defers work; the Core local limit does not prevent execution on a free Agent. Increase Agent capacity only when that host has enough memory and CPU for scripts alongside builds and backups. Remote scripts use Core's public HTTPS origin, not Core's loopback API address.