Handbook

Configuration and environment variables

Fleet reads environment variables at process start. Production installs often set them in forge-fleet.env (see systemd/environment.example in the repo).

Updated

Values are case-sensitive. Empty/unset usually means “use default” where a default exists.

Core server

Variable Purpose
FLEET_DATA_DIR Directory for fleet.sqlite and etc/ layout (default .fleet-data or CLI --data-dir).
FLEET_BEARER_TOKEN Shared secret for Authorization: Bearer on /v1/* when policy requires it.
FLEET_ENFORCE_BEARER If 1/true/yes, require bearer even on loopback when token is set.

Git / version metadata

Variable Purpose
FLEET_GIT_ROOT Checkout used for self-update and SHA resolution.
FLEET_GIT_SHA / SOURCE_GIT_COMMIT Override recorded git SHA for /v1/version.
FLEET_SELF_UPDATE_INSTALL_PROFILE system suppresses user-install self-update button behavior.
FLEET_SELF_UPDATE_POST_GIT_COMMAND Custom command after git pull for self-update.

Integrations (admin snapshot, compose)

Variable Purpose
FLEET_FORGE_CONSOLE_URL Optional Forge Console URL in snapshot meta.integrations.
FLEET_FORGE_LLM_ROOT Auto-migration hint for Forge LLM compose trees; snapshot integration.
FLEET_FORGE_LLM_COMPOSE_FILES Optional override for compose file list when migrating services.

Telemetry and cooldown

Variable Purpose
FLEET_TELEMETRY_INTERVAL_S Minimum seconds between throttled samples (default 60, floor 5).
FLEET_ENVIRONMENT_TELEMETRY_CACHE_TTL_S Cache for docker stats / compose ps rows shared by admin snapshot and GET /v1/environments/telemetry (default 8, floor 5). On Granite with Studio dock polling, 60 reduces duplicate docker work.
FLEET_TELEMETRY_RETENTION_DAYS Prune old telemetry + cooldown rows (0 may mean no prune — see store.py).
FLEET_COOLDOWN_EVENT_MAX_S Max recorded duration_s per cooldown event (default 86400).

Workspace and template uploads

Variable Purpose
FLEET_WORKSPACE_UPLOAD_MAX_BYTES Max gzip tarball size for PUT .../workspace.
FLEET_TEMPLATE_PACKAGE_UPLOAD_MAX_BYTES Max uploaded template package bytes.
FLEET_TEMPLATE_PACKAGE_MAX_UNCOMPRESSED_BYTES Extracted size guard for template packages.
FLEET_TEMPLATE_PACKAGE_MAX_FILES File count guard.
FLEET_TEMPLATE_PACKAGE_MAX_PATH_DEPTH Path depth guard.
FLEET_DOCKER_BUILDKIT Pass-through for docker build BuildKit preference.
FLEET_MIGRATION_SCRATCH_RETENTION_HOURS Hours to keep bundle scratch after a failed extract step before GC (default 24).
FLEET_MIGRATION_ABANDONED_HOURS Hours before GC removes ready bundles whose extract steps never started (default 24).
FLEET_DOCKER_BUILDER_PRUNE_HOURS Prune Docker BuildKit layers older than this many hours at Fleet startup (0 = off; default 168).
FLEET_ROLLOUT_BACKUP_KEEP_COUNT Default minimum rollout pg_dump files to keep per service when using POST /v1/admin/cleanup (default 3).
FLEET_ROLLOUT_BACKUP_KEEP_DAYS Default age floor for rollout backups (days); newer dumps are never removed (default 14).
FLEET_ROLLOUT_BACKUP_ROOT Override rollout backup parent directory (default {FLEET_DATA_DIR}/backups or ~/.local/state/forge-fleet/backups).

Runner / Docker

Variable Purpose
FLEET_DOCKER_BIN Explicit docker binary path.
FLEET_INJECT_HOST_METRICS_ENV_IN_DOCKER If set, inject host metrics URL/token into job env (see HTTP API reference).
FLEET_HOST_METRICS_BASE_URL Base URL reachable from inside containers for health polling.
FLEET_LENSES_WORKSPACE_ROOT Doc/test fleet integration path (see test_fleet.py / README).
FLEET_LENSES_REPO_ROOT Optional Lenses repo hint (containers.py).
FLEET_EMPTY_CONTAINER_IMAGE / FLEET_TEST_CONTAINER_IMAGE Image defaults for internal helpers.

Thermal / advisory (LLM)

Variable Purpose
FLEET_THERMAL_CPU_DEFAULT Policy default tier behavior (thermal_llm_policy.py).
FLEET_ARM_SOC_TJMAX_C SoC thermal ceiling hint on ARM.

Space and Memory guardians

Variable Purpose
FLEET_SPACE_GUARDIAN Enable Space Guardian scheduler (default 1).
FLEET_SPACE_INTERVAL_S Tier 0 interval seconds (default 21600).
FLEET_SPACE_PRESSURE_FREE_PCT / FLEET_SPACE_PRESSURE_FREE_GB Disk pressure thresholds.
FLEET_VOLUME_QUARANTINE_DAYS / FLEET_VOLUME_SNAPSHOT_MAX_GB Orphan volume quarantine TTL and snapshot cap.
FLEET_LEGACY_BACKUP_ROOTS Colon-separated Tier 1 legacy backup roots.
FLEET_VOLUME_ALLOWLIST Comma-separated Docker volume names never quarantined.
FLEET_MEMORY_GUARDIAN Enable Memory Guardian thread (default 1).
FLEET_MEMORY_INTERVAL_S Memory pass interval (default 3600).

Request guard and app gateways

Variable Purpose
FLEET_GUARD_MODE enforce (default) or observe for request guard.
FLEET_BEARER_DIRECT Direct bearer mint policy (mint-only, etc.).
FLEET_TRUSTED_PROXY_CIDRS CIDRs allowed to set forwarded client IP.
FLEET_APP_GATEWAY_CORS_ORIGINS Comma-separated CORS origins for app gateway proxy.
FLEET_APP_GATEWAY_PROXY_TIMEOUT_SEC Upstream proxy timeout for app gateways.

Lifecycle and upgrade

Variable Purpose
FLEET_LIFECYCLE_QUEUED_BLOCK_MAX_AGE_SEC Stale queued jobs no longer block cooperative upgrade.
FLEET_STOP_GRACE_SEC Dependent drain grace (default 25).
FLEET_LIFECYCLE_EXTRA Extra loopback lifecycle dependents JSON.
FLEET_REMOTE_UPGRADE_REQUIRE_APT When set, remote upgrade paths prefer apt channel.

See also

  • SECURITY.md — sensitivity and threat notes
  • README.md — install-specific forge-fleet.env examples