Bring Your Own Storage
Bring-your-own-storage (BYOS) makes a customer-supplied S3-compatible bucket the primary block storage for an organization. Instead of your data's blocks living in a bucket on our storage platform, they live in a bucket on your account, on your provider (AWS S3, Wasabi, Backblaze B2, MinIO, and other S3-compatible targets) - with our hub still running the control plane, metadata store, and coordination as usual.
BYOS is an Enterprise-only option (the byos_storage entitlement).
How it's different from the alternatives#
- Not Dedicated Storage. Dedicated Storage gives your org its own bucket inside our own infrastructure - physically isolated, but still a bucket we create and operate on our cloud account. BYOS moves the bucket out to infrastructure you own and control.
- Not a branch mirror. A branch mirror is a read-only export copy of one branch into your bucket, alongside the authoritative data that still lives on our platform. BYOS is the opposite relationship: your bucket is where the live blocks are read from and written to - there's no second copy on our side.
- Not full self-hosting. BYOS relocates only the block storage. The hub, metadata store, and coordination still run on our infrastructure. If your requirement is that everything, control plane included, runs on infrastructure you operate, that's the self-hosted Enterprise control plane (talk to us; fully air-gapped operation is on the roadmap), not BYOS.
Think of it as a spectrum of "where do the bytes live": shared bucket (Free-plan and pre-default orgs) → your dedicated bucket on our infra (Dedicated Storage, the default for new paid orgs) → your bucket on your infra (BYOS) → your entire deployment on your infra (self-hosted).
Requesting and provisioning it#
BYOS is provisioned by the org owner through Enterprise onboarding. Because it makes an external bucket the org's primary storage, it's a deliberate, owner-gated action - not a self-serve toggle a member could flip.
You supply a bucket that already exists plus a credential that can read and write it; Swarmfile validates the credential with a real write-read-delete round-trip against your bucket before switching anything over, so a bad endpoint, region, bucket, or key is caught immediately rather than surfacing on the org's first real read or write.
Configuration fields#
| Field | Notes |
|---|---|
| Endpoint URL | Your provider's S3-compatible endpoint. |
| Region | The bucket's region. |
| Bucket name | The target bucket. It must already exist. |
| Key prefix | Optional sub-path inside the bucket to confine Swarmfile's objects to (e.g. swarmfile/). |
| Access key ID | The S3 access key ID for a credential with read/write access to the bucket. |
| Secret access key | Stored encrypted at rest (AES-256) under a dedicated key, and never returned. |
The endpoint must be an https:// URL on a real remote host. A cleartext http:// endpoint would put your secret key on the wire, so it's refused unless your deployment operator has explicitly opted in for a trusted on-prem target; loopback, link-local, and cloud-metadata addresses are always refused. A self-hosted operator can additionally pin which hosts are allowed.
Content is encrypted at rest exactly as it is on our own storage for private, managed projects (see Security) - the objects that land in your bucket are the same encrypted blocks, just hosted by you. Public projects are unencrypted by design (they have to be, to be served anonymously), so a public project's blocks land in your bucket as plaintext.
Public projects and streaming from your bucket#
If your org publishes a public project, visitors can play its video and audio and view large images straight away, without downloading the whole file first. For a BYOS org that streaming is served from your bucket, so the requests and the data transferred out are billed to your storage provider account, not ours.
Because anyone on the internet can trigger those reads, anonymous streaming from a BYOS bucket is off by default. The org owner turns it on in Settings, Storage with Allow anonymous streaming from my bucket, and can turn it off again at any time. It takes effect on the next request.
- While it's off: public visitors can't stream media from your bucket. On the public project page the audio, video, or image falls back to the sign-in gated download, which needs a Swarmfile account. Thumbnails, small previews, and readmes are not affected, and neither is anything for signed-in members of your org.
- While it's on: anyone who can see one of your public projects can stream its media directly from your bucket. Expect your provider to bill for the requests and egress. Swarmfile applies per-IP rate limits and byte budgets to public streaming, but it cannot cap what your provider ultimately charges you.
- Shared and Swarmfile-managed dedicated buckets stream by default; the setting only appears for BYOS.
Known limitations today#
- New/empty orgs only. BYOS is set at provisioning time, before the org has uploaded any content. There is no live migration of an existing org's blocks into a BYOS bucket in this version - switching an org that already holds data is rejected. Decide on BYOS before adding content, not after.
- No fallback if your bucket is unavailable. This is the real operational tradeoff to understand. Your bucket is the only home for the blocks - there's no shadow copy on our side to fall back to (a silent fallback would defeat the entire point of BYOS). If your bucket has an outage, or its credential is rotated/revoked out from under Swarmfile, reads and writes for the org fail synchronously until you restore access. Storage availability and credential lifecycle become your responsibility.
- Credential rotation is re-provisioning. When you rotate the access key, re-run provisioning with the new credential for the same bucket. (Re-pointing a non-empty org at a different bucket is refused for the same reason a live migration is - it would orphan the existing content.)
- Set the incomplete-multipart lifecycle rule on your bucket. A large git-LFS push (≥ 64 MiB, via the desktop app's transfer agent) is one S3/R2 multipart upload that goes straight to your bucket; a client killed mid-push can't abort its own upload, and your provider bills the uploaded parts until they're aborted or expired. Add an
AbortIncompleteMultipartUploadrule - 7 days is the value we use. Swarmfile applies this automatically to buckets it creates; a BYOS bucket is yours to configure. - Data residency is yours to enforce. Swarmfile can't verify the physical region of an arbitrary customer endpoint, so BYOS is refused for an org with a pinned jurisdiction. If you have a residency requirement, choosing a bucket in the right region - and keeping it there - is on you.
- Enterprise-only, owner-gated. BYOS requires the Enterprise plan, and only the org owner can provision it.
Where to go next#
- Dedicated Storage Isolation - physical isolation inside our own infrastructure.
- Branch Mirror - a read-only export copy into a bucket you control.
- Deployment Topologies - the fully self-hosted Enterprise option.