Branch Mirror
Branch mirror continuously exports one project branch into an S3-compatible bucket you control - as real files at their real paths, not Swarmfile's internal content-addressed block format. It's a secondary, one-directional copy: our storage platform stays the primary, authoritative home for your data, and the mirror is a fully-hydrated, browsable duplicate that lives in your own bucket for backup, disaster-recovery, or downstream-pipeline use.
Available on Pro and Enterprise (the s3_mirror entitlement), configured per branch from the dashboard.
How it's different from the alternatives#
- Not
swarmfile-migrate. That tool is a one-shot import that moves data into Swarmfile (from a NAS, S3 bucket, or file list). A branch mirror runs the other direction and keeps running - a continuous export out to a bucket you own, not a single copy-in. - Not Dedicated Storage. Dedicated Storage is about isolating your bytes inside our own infrastructure - a bucket that's physically yours but still one we create and operate. A branch mirror puts a readable copy in your infrastructure entirely, on a provider and account you control.
- Not bring-your-own-storage. Bring-your-own-storage makes your bucket the primary home where the live blocks actually live. A branch mirror is strictly a read-only export copy - the authoritative data still lives on our platform, and the mirror just tracks it.
The key thing a mirror gives you that the block store can't: the files land in your bucket at their natural paths (projectroot/scenes/shot_010.exr, not an opaque content hash), directly readable by anything that speaks S3 - no Swarmfile client, no decryption step, no reassembly.
Where to configure it#
Open the project in the dashboard and go to its Mirror tab. Configuration is per branch - each branch of a project mirrors independently (or not at all), so you can export just main while leaving working branches unmirrored.
The tab is owner/admin-gated and requires a Pro or Enterprise plan. On a plan without the s3_mirror entitlement the tab explains the gate; an existing mirror keeps its last-synced state and can still be turned off, but its configuration can't be changed until the plan includes mirroring again.
Configuration fields#
| Field | Notes |
|---|---|
| Endpoint URL | Your provider's S3-compatible endpoint. Not needed for AWS S3 itself if you use the region-default endpoint; required for Wasabi, Backblaze B2, MinIO, and most others. |
| Region | The bucket's region. |
| Bucket name | The target bucket. It must already exist - Swarmfile writes into it, it doesn't create it. |
| Key prefix | Optional. A sub-path inside the bucket to confine the mirror to (e.g. swarmfile/). Leave blank to write at the bucket root. |
| Access key ID | The S3 access key ID for a credential with write access to the bucket. |
| Secret access key | Stored encrypted at rest (AES-256) and never returned by the dashboard. On an existing mirror, leave it blank to keep the stored credential - you only re-enter it to change it. |
The credential is validated with a real round-trip against your bucket at save time, so a bad endpoint, region, bucket name, or key is caught immediately in the settings screen rather than silently on the first sync.
Behavior and limits#
- Full-fidelity tracking. The mirror reflects the branch as it changes: new and modified files are re-exported, and deletes, restores, and renames propagate to the target bucket. What's in the mirror tracks what's on the branch.
- Asynchronous, up to ~1 hour of lag. Syncing is driven by a periodic maintenance scan that runs roughly hourly, so a change can take up to about an hour to appear in your bucket. This is not a live, write-through copy.
- Fire-and-forget. There's no delivery guarantee, no built-in retry-until-success alerting, and no per-file receipt. A file that fails to sync on one pass is simply left unconfirmed and picked up again on the next scan's fresh diff - the sync self-heals over time rather than escalating a failure to you.
- One oversized file skips; a bad credential fails the whole sync. If a single file trips a size cap (or hits a transient error), that one file is left unsynced and retried next tick - the rest of the batch still goes through. A broken or rotated-away credential, by contrast, fails every file, so the whole sync fails until you fix the credential.
- Status is visible in the tab. The Mirror tab shows the current state - Never synced, Syncing, Synced, or Sync failed - along with the last sync time and, on failure, the last error.
- Turning it off leaves the bucket alone. Disabling a mirror stops future syncs but never deletes what's already been written - that data is yours in your bucket.
End-to-end encrypted projects are not eligible#
A mirror is refused at configuration time for end-to-end (customer-managed) encrypted projects. The hub never holds an E2E project's key, so it structurally cannot decrypt the blocks to hydrate readable files - there's nothing it could write to your bucket but ciphertext. Mirroring is a managed-tier feature; on an E2E project the save is rejected with an explanation rather than producing an unusable export.
Data residency is your bucket's responsibility#
Once a file is written to your bucket, where it physically lives is governed by your provider, account, and region - not by Swarmfile's data residency pinning. Swarmfile can't verify or enforce the residency of an arbitrary customer-supplied endpoint, so for an org with a pinned jurisdiction a branch mirror is refused outright rather than silently allowed to route data outside that jurisdiction. If you're using a mirror, choosing a bucket whose region matches your own residency commitments is on you.
Where to go next#
- Bring-your-own-storage - making your bucket the primary home for live blocks (Enterprise).
- Dedicated Storage Isolation - physical isolation inside our own infrastructure.
- Data Portability & Offboarding - the fuller picture on getting your data out.