Engine Config File (config.json)

The Swarmfile engine reads its startup configuration from these sources, in this order of precedence:

1. Environment variables (SWARMFILE_*) - always win, with one exception: data_namespace on a packaged install, where the bundled install config wins even over the env var (see "A note on environment-selection keys" below).
2. A stored OIDC session (applies to oidc_issuer/oidc_client_id only) - after an interactive sign-in, the engine remembers the issuer and client id it signed in against; those beat a hand-edit of oidc_issuer/oidc_client_id in the file. Editing either key on a signed-in install can appear to do nothing until you sign in again.
3. The config.json file - the subset of settings documented below.
4. Built-in defaults - a released build ships pointing at Swarmfile's hosted service, so an unconfigured engine connects to production rather than nothing.

Most people never touch this file: the Desktop App writes the keys it manages for you, and a normal sign-in fills in the rest. You edit config.json directly for headless and unattended setups - a NAS/seed node, a render-farm worker, a VM, or any machine that boots the engine from autostart rather than a signed-in Desktop App session - where there's no UI to click and, on macOS/Windows, no shell environment for the engine to inherit exported variables from.

Where the file lives#

That per-user path is only half the picture. A packaged install also ships its own install config - read-only, written by the installer, and living next to the binary (on macOS, inside the bundle's Contents/Resources/config.json; on Linux's .deb, /etc/swarmfile/config.json). At startup the engine merges the two, generally with the per-user file winning per key - except for a small, fixed set of keys a packaged install manages itself, where the install config wins instead. See "A note on environment-selection keys" below for exactly which keys, and why, before hand-editing any of them.

To point the engine at a specific file instead of this two-file merge - e.g. one config per project on a multi-tenant node - set SWARMFILE_CONFIG=/path/to/config.json. That bypasses the merge entirely and reads only that one file.

Editing safely#

A few things are worth knowing before you hand-edit this file:

• Restart the engine after editing. The file is read once at startup. A handful of values can also be applied to a running engine through the control socket with no restart: cache_max_bytes, readahead_buffer_secs, throttle_enabled and the four office-hours keys, office_id, lan_from_office, and branch. Everything else is read only at startup (including seed_mode, hub_only, ec_lan_placement, changeset_idle_secs, attr_cache_secs, mount_point, read_only, and session_kind). sync_ignore_enabled updates live and then drains and restarts the engine. Either way, a change to the file itself needs a restart to be read.
• A single syntax error discards the whole file - and says so. If the JSON doesn't parse, the engine logs a warning, ignores that file, and keeps going with whatever the other sources provide. On a packaged install that means the bundled install config and environment still apply - but a broken per-user file still drops your org_id and project_id, so the drive has nothing behind it. Instead of a generic "no project" prompt, the Desktop App's status then names the file and the parser's position (for example config.json: expected value at line 1 column 3), because a project picker can't help when the org id lived in the file that failed to parse. (With SWARMFILE_CONFIG, there is no other file, so a bad file leaves the engine on built-in defaults.) A JSON syntax error - a trailing comma, say - silently drops those along with everything else in the file. Validate your JSON before restarting.
• Unknown keys are named, not ignored in silence. A valid file with a misspelled key (say project_idd) loads, but the engine warns - and when there is no project to mount, the Desktop App's status names the unrecognized key(s), because a typo like that is otherwise invisible: the setting simply never applies. The key list is derived from the engine's own parser, so the table above stays current with it.
• A UTF-8 byte-order mark (BOM) is tolerated. Windows Notepad and PowerShell 5.1's -Encoding UTF8 prepend one; the engine strips it. Still, prefer a plain UTF-8 editor.
• Environment variables override the file. If a launcher (systemd unit, Docker -e, a scheduled task) sets SWARMFILE_HUB_URL, editing hub_url in the file will appear to do nothing. Check what actually took effect with --print-env-vars (below).
• Don't fight the Desktop App. For keys the Desktop App or swarmfile CLI manage (mount point, seed mode, hub-only, cache size, read-ahead, throttle, LAN placement, branch), prefer their controls - the Desktop App may rewrite the file and overwrite a manual edit. Hand-editing is for machines with no Desktop App.

Connecting to the hosted service#

A released build ships pointing at Swarmfile's production service, so you do not need to configure the hub or identity provider by hand. With nothing set, the engine defaults to:

A headless machine on the hosted service therefore only needs to say which org and project it serves and supply a credential - org_id, project_id, and one of SWARMFILE_API_KEY or SWARMFILE_OIDC_REFRESH_TOKEN (see below). Set hub_url, oidc_issuer, or oidc_client_id only when you run a self-hosted or Enterprise hub on your own domain.

Keys you can set in the file#

Every key is optional. Booleans are JSON booleans (true / false) in the file - the true/1 string form is only for the environment-variable equivalents.

Additional mounts aren't configured here. One engine process can hold several full mount points open at once against the same project/org - see swarmfile mounts - but that's an entirely runtime, CLI/Desktop-App-driven operation with no config-file or env-var equivalent: there's no mount_point_2 key or similar, and no way to declare a second mount up front for the engine to open at boot. mount_point/mount_point_auto above describe the boot mount specifically, whether or not anything else is opened later in the session. You don't need to edit this file to get a free drive letter for an additional mount: swarmfile mounts open auto (or the Desktop App's Open mount form, which defaults to it on Windows) picks one.

A note on environment-selection keys#

hub_url, oidc_issuer, oidc_client_id, site_url, updater_endpoint, and data_namespace are handled differently from every other key in the table above. A packaged install (the macOS .app, the Windows installer, the Linux .deb) ships its own read-only install config that sets these - that's how an install stays on the environment it was packaged for, and why one signed binary set can serve different environments without drifting. When the install config sets one of these six keys, it wins over whatever you put in your per-user config.json - a hand-edit of hub_url or oidc_issuer at the per-user path documented above will silently appear to do nothing on a normal packaged install. Your per-user value is only used as a fallback for a key the install config left unset - which is the normal case for a from-source/dev build, or an older single-file-layout install. Every other key in this file follows the ordinary env-var-then-file precedence at the top of this page; only these six are install-config-first.

Settings that are environment-variable-only#

Many settings can be tuned via SWARMFILE_* env vars but are not readable from config.json - the file supports only the keys in the table above. Environment Variable Index is the full list; the notable ones include:

• Credentials: SWARMFILE_OIDC_REFRESH_TOKEN (non-interactive OIDC), SWARMFILE_API_KEY (project-scoped headless key - takes precedence over a refresh token), SWARMFILE_ENCRYPTION_KEY, SWARMFILE_SWARM_KEY. Credentials are deliberately kept out of the file.
• Paths & identity: SWARMFILE_CACHE_DIR, SWARMFILE_IROH_DIR, SWARMFILE_USER_ID, SWARMFILE_MACHINE_ID.
• Encryption toggle/mode: SWARMFILE_ENCRYPTION_ENABLED, SWARMFILE_EC_ENABLED (on/off/auto).
• Networking: SWARMFILE_IROH_PUBLIC_ADDR, SWARMFILE_HEALTH_PORT. SWARMFILE_MDNS_INTERFACES (comma-separated interface names) restricts LAN discovery to exactly those interfaces and skips the built-in VPN/virtual-interface filter. SWARMFILE_MDNS_EXCLUDE_INTERFACES removes more interfaces from it. See Network Requirements. (SWARMFILE_IROH_BIND_ADDR/iroh_bind_addr is file-settable - see the table above.)
• QoS: SWARMFILE_DSCP_INTERACTIVE, SWARMFILE_DSCP_BACKGROUND, SWARMFILE_SITE_DOWNLOAD_BANDWIDTH_MBPS / SWARMFILE_SITE_UPLOAD_BANDWIDTH_MBPS. The office-hours schedule keys (SWARMFILE_OFFICE_HOURS_START / _END, SWARMFILE_OFFICE_HOURS_WAN_PCT, SWARMFILE_OFF_HOURS_WAN_PCT) are file-settable - see office_hours_*/off_hours_wan_pct in the table above.
• LAN shard placement tuning: SWARMFILE_EC_LAN_PLACEMENT_REPLICATION (default 3) is the replication factor K - each erasure shard is deliberately assigned to this many LAN peers. SWARMFILE_EC_LAN_PLACEMENT_POLL_INTERVAL (default 300) is the reconciler's safety-net pass interval in seconds, run alongside the reactive pass that fires on a peer-roster change. Both only matter when ec_lan_placement is on.
• Seed tuning: SWARMFILE_SEED_POLL_INTERVAL (default 60, seconds), SWARMFILE_SEED_UPLOAD_CONCURRENCY (default 8, concurrent cloud uploads).
• Runner (headless CI): SWARMFILE_RUNNER_MODE - watches SWARMFILE_BRANCH for commits/tags matching a rule in .swarmfile/runner.yml and runs it. Env-only by design, no config.json key or Desktop App toggle - see Runner (Headless CI). Mutually exclusive with seed_mode.
• Streaming an upload in progress: SWARMFILE_STREAM_BUFFER_SECS, SWARMFILE_STREAM_READ_WAIT_SECS, SWARMFILE_STREAM_WAIT_CONCURRENCY - env-only, no config.json key. STREAM_BUFFER_SECS (default 30) is how many seconds of playback a fetch --follow job keeps buffered ahead of the reader; it is seconds rather than bytes because 30 s of a proxy and 30 s of a full-resolution master are wildly different byte counts and one figure would be wrong for both. STREAM_READ_WAIT_SECS (default 15) is how long a read of a not-yet-uploaded range waits before giving up - see below. STREAM_WAIT_CONCURRENCY (default 4, clamped 1-64) caps how many reads may be waiting at once, so a burst returns the retryable "try again" promptly instead of parking every operation thread; it is sized when the mount starts, so a change needs a remount.
• Peer-to-peer budgets: SWARMFILE_IROH_PEER_BUDGET_SECS (default 30) and SWARMFILE_IROH_PEER_BUDGET_BACKGROUND_SECS (default 10) cap how long a peer connection attempt may take for interactive and background work respectively.
• Durable create queue tuning: SWARMFILE_CREATE_DISPATCH_CONCURRENCY (default 8, 1-64 - creates sent to the hub at once), SWARMFILE_PENDING_CREATE_WAIT_SECS (default 8, 0-120 - how long a lock/ACL/share/comment on a not-yet-confirmed file waits before answering 409 pending_create), and the coalescing/batching knobs (SWARMFILE_CREATE_COALESCE, _HOLD_SECS, _HOLD_UPLOADING_SECS, _BATCH). See Coding Agents.
• Worksharing refusal mode: SWARMFILE_WORKSHARING_FAIL_CLOSED (Windows only) makes a native worksharing open refuse when the hub can't be reached.
• mdNS service type: SWARMFILE_MDNS_SERVICE_TYPE overrides the _swarmfile._udp.local. service type - for isolated test networks, not for normal use.
• Upload diagnostics: SWARMFILE_UPLOAD_TRACE=1 promotes per-attempt upload logging to warn, including the hub's status and response body when a block upload or commit is refused - the first thing to set when a save isn't landing and you need to know why. Off by default; the lines are noisy for ordinary work.
• Misc: SWARMFILE_XREF_PREFETCH, SWARMFILE_DOCTOR_PERIOD_SECS, SWARMFILE_OTEL_ENDPOINT, SWARMFILE_OTEL_SERVICE_NAME.

How streaming an in-progress upload behaves#

Always on: a file that has never finished uploading can be opened through the mount - it appears at its full eventual size and reads work, waiting briefly where the bytes have not landed. Worth knowing how it behaves, because a read into a range that has not been uploaded yet has to wait, and this runs on a filesystem operation thread. An operation that waits too long does not stall one read - it takes the whole drive with it. The wait is therefore strictly bounded (SWARMFILE_STREAM_READ_WAIT_SECS, default 15 s, and 0 does not mean "forever" - it falls back to the default), and a read that outruns the upload returns a retryable "not yet" rather than an I/O error, because an application that sees an I/O error part way through a file will usually conclude the file is damaged and discard your document.

Different NLEs and DCC tools react differently to a delayed read; the bound is tuned to release the drive before an editing application gives up on it. Two consequences worth knowing: only so many reads may be waiting at once (a burst beyond that gets the "try again" immediately rather than parking every operation thread), and only a file with no committed version streams - a re-save of an existing file is readable once it commits, never mid-save.

Scope worth knowing:

• It applies only to files with no committed version yet - a new file landing for the first time. A file you are already reading never changes size or content because somebody started a new save.
• A file that is streaming reports the size it is going to be, not 0. Without that, nothing could read it: no application asks for bytes past the end of an empty file.
• If the uploading machine is on the same LAN, it serves those blocks directly from its own disk, before they reach the cloud. Over a WAN it does not - that would carry every block twice on the same contended uplink.

And the limit that no setting changes: this decides which bytes arrive first, not how fast the link is. A 4 TB file on a 100 Mbit/s uplink delivers about 12 MB/s however well it is ordered.

Project-local files (.swarmfile/)#

Some configuration lives inside a project - committed like any other file, so it versions with the branch and every contributor gets the same behavior - instead of in the engine's config.json:

The runner, merge and cache files are read from the branch the operation runs against, so they can differ per branch; .swarmfile/publicignore.yml is read from the tree of the tag being published. A .swarmfile/merge.yml that is missing or unparseable is treated exactly like diff3: false - never as "turn extra automatic behavior on".

For example, to make text-conflict auto-resolve the default for a project:

# .swarmfile/merge.yml
diff3: true

Engine command-line flags#

Beyond reading config.json, the swarmfile-engine binary takes a handful of one-shot flags - useful on a headless node where there's no Desktop App to click.

Answered immediately - about this binary, or a running engine:

Lifecycle - against a running engine:

--help and --version answer before the engine reads any config, so they work on a broken or unconfigured install. For day-to-day version-control and mount operations, use the swarmfile CLI - it drives the same engine over its control socket - rather than these flags.

The engine's own --help also lists offline/pinning flags (--pin, --prepare-offline, and related). These currently run only while the engine is stopped, so they can't be driven against a live mount and aren't part of the normal headless workflow. To force a scope resident for offline or render-farm use against a running engine, use swarmfile hydrate instead.

Verifying what actually took effect#

Because several sources feed the final config, print the resolved values the engine will use - with secrets redacted, and a footer naming the install-config and per-user files that fed the merge (or the SWARMFILE_CONFIG path):

swarmfile-engine --print-env-vars

swarmfile doctor (or the standalone swarmfile-doctor) then confirms the resolved hub URL, org, and credentials actually reach the hub. See CLI: swarmfile-doctor.

Example: a headless seed node#

On the hosted service the hub and IdP are already the defaults, so a seed node only names its org and project:

{
  "org_id": "org_abc123",
  "project_id": "proj_xyz789",
  "seed_mode": true,
  "cache_max_bytes": 107374182400
}

(On a self-hosted or Enterprise hub, add hub_url, oidc_issuer, and oidc_client_id for your own domain.)

Pair this with a credential in the environment - SWARMFILE_API_KEY=sf_key_… for a project-scoped key, or SWARMFILE_OIDC_REFRESH_TOKEN=… - since credentials aren't stored in the file. See Deployment Topologies and Self-Hosted Seed Nodes for the full headless-node walkthrough, Network Requirements for exactly what a machine using this file needs to reach, and Deploying to Your Team for pre-staging this file across a fleet.