Environment Variable Index
Almost every engine setting has an environment-variable form, and some settings exist only as environment variables. This page is the index: what each SWARMFILE_* variable does, its default, and whether the same setting can be put in config.json instead.
Use environment variables when a launcher can set them (systemd, Docker, a scheduled task, a CI job). Use config.json when it can't - notably macOS launchd agents and Windows services, which don't inherit a shell environment. See Engine Config File for the file's precedence rules and the list of keys a packaged install manages itself.
To see what a running install actually resolved - secrets redacted - run swarmfile-engine --print-env-vars.
Conventions#
- Booleans accept
true/1to enable; anything else (including an empty string) is false. A few "disable with" flags are the reverse: onlyfalse/0disables them. - Empty strings are treated as unset for credentials, ids, paths, and tool commands.
- Values set here beat the
config.jsonfile; both beat built-in defaults. - Variables marked advanced are safe but rarely needed - reach for them while diagnosing, not as standard configuration.
- Variables marked diagnostic only are for support sessions and are noisy.
Credentials, identity, and routing#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_HUB_URL | https://hub.swarmfile.com on a packaged install | Hub API base URL. | hub_url |
SWARMFILE_ORG_ID | (unset) | Org whose hub routes are called. | org_id |
SWARMFILE_PROJECT_ID | (unset) | Project every metadata operation is scoped to (required for headless nodes). | project_id |
SWARMFILE_BRANCH | project main | Branch this mount starts on. | branch |
SWARMFILE_OFFICE_ID | default | Peer-grouping label for same-office LAN behavior. | office_id |
SWARMFILE_OIDC_ISSUER | https://id.swarmfile.com on a packaged install | Identity provider the engine signs in against. | oidc_issuer |
SWARMFILE_OIDC_CLIENT_ID | swarmfile-desktop on a packaged install | OIDC client id. | oidc_client_id |
SWARMFILE_OIDC_REFRESH_TOKEN | (unset) | Non-interactive sign-in for headless engines; the rotated token is persisted under the cache dir. | - |
SWARMFILE_API_KEY | (unset) | Project-scoped sf_key_… credential; wins over a refresh token if both are set. | - |
SWARMFILE_SWARM_KEY | (unset) | Extra deployment-wide entropy for the private peer-to-peer swarm. | - |
SWARMFILE_USER_ID | $USER/$USERNAME, else anonymous | Identity recorded for locks and presence. | - |
SWARMFILE_MACHINE_ID | OS hostname (tray: hash of hostname + data dir) | Machine identity for locks and presence. | - |
SWARMFILE_NODE_AUTH | false | Start the P2P peer allow-list fail-closed until the hub confirms the approved roster (for orgs that enforce node auth). | node_auth |
SWARMFILE_LAN_FROM_OFFICE | false | Treat same-office peers discovered through the hub as LAN peers when mDNS is blocked. | lan_from_office |
Paths and local data#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_CONFIG | (unset) | Explicit single config.json path; bypasses the install + per-user merge. | - |
SWARMFILE_DATA_NAMESPACE | (empty) | Suffixes the data dir, mount, socket, and lock so a staging/second install can coexist. | data_namespace |
SWARMFILE_CACHE_DIR | ~/.cache/swarmfile (macOS/Linux), %LOCALAPPDATA%\swarmfile (Windows) | Block/metadata cache, auth token, control socket, logs. | - |
SWARMFILE_CACHE_MAX_BYTES | 10737418240 (10 GiB) | Local block-cache cap. | cache_max_bytes |
SWARMFILE_MOUNT_POINT | /tmp/swarmfile (Unix), S: (Windows) | Where the boot mount attaches. | mount_point |
SWARMFILE_IROH_DIR | <cache_dir>/iroh | Peer-to-peer node identity and blob store. | - |
SWARMFILE_READ_ONLY | false | Force a kernel read-only mount (guest sessions). | read_only |
SWARMFILE_SESSION_KIND | owner | Session role (owner/member/guest). | session_kind |
SWARMFILE_HUB_ONLY | false | Cloud-only mode: no QUIC, no mDNS, no peer traffic. An org policy can also force it on. | hub_only |
Networking and peer discovery#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_IROH_BIND_ADDR | OS-assigned ephemeral port | Fixed QUIC bind address, for a firewall that needs a predictable port. | iroh_bind_addr |
SWARMFILE_IROH_PUBLIC_ADDR | (unset) | Public address advertised to the hub when behind NAT. | - |
SWARMFILE_IROH_PEER_BUDGET_SECS | 30 | Aggregate time budget for peer fetches on interactive paths. Advanced | - |
SWARMFILE_IROH_PEER_BUDGET_BACKGROUND_SECS | 10 | Same budget for background prefetch. Advanced | - |
SWARMFILE_HEALTH_PORT | (unset - health server off) | Port for the /healthz and /livez endpoints. | - |
SWARMFILE_MDNS_INTERFACES | auto-selected LAN interfaces | Comma-separated allowlist mDNS must use exclusively. | - |
SWARMFILE_MDNS_EXCLUDE_INTERFACES | (unset) | Comma-separated interfaces mDNS must never use. | - |
SWARMFILE_MDNS_SERVICE_TYPE | _swarmfile._udp.local. | Override the mDNS service type so an engine stays off the shared type (lab/staging isolation). Must be a valid _<name>._udp.local. type; an invalid value fails startup rather than falling back. Advanced | - |
SWARMFILE_WORKSHARING_FAIL_CLOSED | false | Refuse (rather than degrade to advisory) an exclusive-open check when the hub is unreachable. | - |
Encryption and erasure coding#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_ENCRYPTION_ENABLED | true | Master switch for block encryption. | - |
SWARMFILE_ENCRYPTION_KEY | (unset) | Hex 32-byte static master key (no hub key fetch). | - |
SWARMFILE_ENCRYPTION_PROJECT_ID | falls back to SWARMFILE_PROJECT_ID | Project whose hub-managed key is fetched. | encryption_project_id |
SWARMFILE_EC_ENABLED | auto | Erasure coding: on/true, off/false, or auto (adapt per save). | - |
SWARMFILE_EC_LAN_PLACEMENT | false | Deliberately spread erasure shards across LAN peers. | ec_lan_placement |
SWARMFILE_EC_LAN_PLACEMENT_REPLICATION | 3 | Replication factor K per shard. Advanced | - |
SWARMFILE_EC_LAN_PLACEMENT_POLL_INTERVAL | 300 (seconds) | Placement reconcile interval. Advanced | - |
Seed mode and CI runner#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_SEED_MODE | false | Run as a NAS/seed node: pin all blocks, mirror to cloud storage, no mount. | seed_mode |
SWARMFILE_SEED_POLL_INTERVAL | 60 (seconds) | How often a seed polls the hub for metadata changes. | - |
SWARMFILE_SEED_UPLOAD_CONCURRENCY | 8 | Concurrent cloud uploads from a seed. | - |
SWARMFILE_RUNNER_MODE | set by swarmfile-runner | Headless CI runner; watches SWARMFILE_BRANCH for commits/tags matching .swarmfile/runner.yml. Refuses to execute the rule file on a branch without an effective branch protection unless SWARMFILE_RUNNER_ALLOW_UNPROTECTED=1 is set (trusted/dev runners only). | - |
Create queue, streaming, and mount I/O#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_PENDING_CREATE_WAIT_SECS | 8 (0-120; 0 refuses immediately) | How long an operation on a still-syncing file waits before answering 409 pending_create. | - |
SWARMFILE_CREATE_DISPATCH_CONCURRENCY | 8 (1-64) | Creates sent to the hub at once. Advanced | - |
SWARMFILE_CREATE_COALESCE | on (0/false/off disables) | Attach the first save to a create instead of sending the create empty. Advanced kill switch | - |
SWARMFILE_CREATE_HOLD_SECS | 2 (0-10; 0 disables holding) | Max wait for the first save of an open-but-unsaved file. Advanced | - |
SWARMFILE_CREATE_HOLD_UPLOADING_SECS | 60 (0-600) | Same, when that first save is already uploading. Advanced | - |
SWARMFILE_CREATE_BATCH | on (0/false/off disables) | Batch creates through the hub's batch route. Advanced kill switch | - |
SWARMFILE_STREAM_BUFFER_SECS | 30 (seconds) | Read-ahead a fetch --follow job keeps buffered. Advanced | - |
SWARMFILE_STREAM_READ_WAIT_SECS | 15 (seconds) | How long one mount read waits for in-flight bytes before a retryable error. Advanced | - |
SWARMFILE_STREAM_WAIT_CONCURRENCY | 4 (1-64) | How many reads may be waiting at once. Advanced | - |
SWARMFILE_MOUNT_ATTEMPT_TIMEOUT_SECS | 120 (0 disables the bound) | Wall-clock bound on a mount attempt so a wedged driver can't hang the app. Advanced | - |
SWARMFILE_MOUNT_OPEN_WAIT_SECS | 20 (0 = don't wait) | How long mounts open waits for the platform mount to settle. Advanced | - |
SWARMFILE_PACK_AND_GO_POLICY | allowed; any unrecognized value disables Pack & Go (fail-closed, and logged at startup - plus a swarmfile-doctor warning) | Operator gate for bulk offline reservation - see Working Offline. | - |
SWARMFILE_GIT_ACCEPT_PROVISIONAL | false | The swarmfile:// remote helper accepts provisional (derived-but-unconfirmed) commit ids when resolving a shallow clone's boundary - needed for --depth on a project whose commits only one person derives. Unset, a boundary id must be confirmed. Advanced | - |
Bandwidth, QoS, and sync behavior#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_THROTTLE_ENABLED | false | Enable bandwidth throttling; set a site bandwidth first. | throttle_enabled |
SWARMFILE_SITE_DOWNLOAD_BANDWIDTH_MBPS | (unset) | Site download capacity. | site_download_bandwidth_mbps |
SWARMFILE_SITE_UPLOAD_BANDWIDTH_MBPS | (unset) | Site upload capacity. | site_upload_bandwidth_mbps |
SWARMFILE_OFFICE_HOURS_START | 08:00 | Start of the office-hours window (local HH:MM). | office_hours_start |
SWARMFILE_OFFICE_HOURS_END | 18:00 | End of the office-hours window. | office_hours_end |
SWARMFILE_OFFICE_HOURS_WAN_PCT | 20 | WAN percentage allowed during office hours. | office_hours_wan_pct |
SWARMFILE_OFF_HOURS_WAN_PCT | 80 | WAN percentage allowed outside them. | off_hours_wan_pct |
SWARMFILE_DSCP_INTERACTIVE | 34 | DSCP marking for interactive traffic. Advanced | - |
SWARMFILE_DSCP_BACKGROUND | 0 | DSCP marking for bulk traffic. Advanced | - |
SWARMFILE_XREF_PREFETCH | true | Prefetch .dwg/.max external references on open. | - |
SWARMFILE_SYNC_IGNORE_ENABLED | true | Honor .gitignore/.swarmfileignore exclusion. | sync_ignore_enabled |
SWARMFILE_CHANGESET_IDLE_SECS | 300 (0 disables session minting) | Idle timeout before a staged changeset commits. | changeset_idle_secs |
SWARMFILE_AUTO_OPEN_CHANGELIST_FOR_PREFERENCE | false | Open a changelist on boot when the user's commit-mode preference asks for it. | auto_open_changelist_for_preference |
SWARMFILE_ATTR_CACHE_SECS | 2 (0 keeps FUSE-T's own default) | macOS/Linux attribute-cache ceiling. | attr_cache_secs |
SWARMFILE_MERGETOOL_CMD | (unset - git config fallback) | External merge-tool command template. | mergetool_cmd |
SWARMFILE_MERGETOOL_NAME | (unset) | Display name for that tool. | mergetool_name |
Diagnostics and telemetry#
| Variable | Default | Purpose | File key |
|---|---|---|---|
SWARMFILE_DOCTOR_PERIOD_SECS | 300 (0 disables) | Period of the engine's background connectivity self-check. | - |
SWARMFILE_OTEL_ENDPOINT | (unset - OpenTelemetry off) | OTLP collector endpoint for engine traces. Operator builds only - the otel feature is not compiled into shipped desktop installs, so this is inert there. | - |
SWARMFILE_OTEL_SERVICE_NAME | swarmfile-engine | Service name reported to that collector (same operator-build caveat). | - |
SWARMFILE_UPLOAD_TRACE | off (1/true on) | Promote per-attempt upload logging to warn, including the hub's refusal body. Diagnostic only | - |
SWARMFILE_USER_KEY_PRIVATE_B64 / SWARMFILE_USER_KEY_PUBLIC_B64 / SWARMFILE_USER_KEY_ID | on-disk device key | Pre-enroll a device user key and skip sign-in (base64 private/public plus key id). Diagnostic only - development and tests; never set these on a real install. | - |
SWARMFILE_FUSE_DEBUG | off | libfuse protocol tracing (macOS). Diagnostic only | - |
SWARMFILE_WINFSP_DEBUG | off | WinFsp protocol tracing (Windows). Diagnostic only | - |
SWARMFILE_UPDATER_ENDPOINT | installed config | Update manifest endpoint that swarmfile-doctor --repair repairs from. | tray config |
Installers and the git-LFS agent#
These are consumer/operator knobs rather than engine settings.
| Variable | Default | Purpose |
|---|---|---|
SWARMFILE_FW_PROFILES | 3 (Domain + Private; bitmask: 1 Domain, 2 Private, 4 Public) | Windows MSI property controlling which firewall profiles get the LAN rules, e.g. msiexec /i Swarmfile-x64.msi SWARMFILE_FW_PROFILES=7 /qn. |
SWARMFILE_LFS_VERSION | latest release | Pin the git-LFS agent version installed by the agent installer. |
SWARMFILE_LFS_BINDIR | ~/.local/bin (Unix), %LOCALAPPDATA%\Swarmfile\bin (Windows) | Where the LFS agent installer puts the binary. |
SWARMFILE_LFS_REPO | swarmfile/swarmfile-lfs | Release repo the installer pulls from. |
SWARMFILE_LFS_DOWNLOAD_BASE | provider default | Mirror/CDN base for agent downloads. |
SWARMFILE_LFS_API_URL | provider default | Release-listing API override for a mirror. |
SWARMFILE_LFS_ALLOW_UNVERIFIED | unset (1 = allow) | Proceed when a mirror strips .sha256 checksums. Security-relevant - only for a mirror you trust. |
Standard environment variables the product honors#
| Variable | Effect |
|---|---|
RUST_LOG | Log filter for the engine, CLI, and Desktop App backend (for example RUST_LOG=swarmfile_engine=debug). |
HOME / XDG_CONFIG_HOME | Base for the cache dir and the per-user config.json on macOS/Linux. |
LOCALAPPDATA / USERPROFILE | Base for the data dir and config discovery on Windows. |
USER / USERNAME | Fallback identity when SWARMFILE_USER_ID is unset. |
NO_COLOR | Disable ANSI color in swarmfile-doctor output. |
Where to go next#
- Engine Config File - the file form of these settings, precedence, and live vs restart-required keys.
- Network Requirements - what the networking variables above connect to.
- Diagnostics & Error Reference - the doctor checks that read these values.