How to Set Up Bring-Your-Own-Storage (S3) Sync in Filarr

Quick answer: Filarr can sync your files through an S3-compatible bucket you own and control, instead of Filarr's own servers. Open Settings, go to the Storage Provider section, add a provider (name, endpoint, region, bucket, Access Key ID and Secret Access Key), test the connection, and set it as default. From that point, every file is encrypted on your machine with AES-256-GCM before it leaves, so your bucket only ever holds opaque, unreadable blobs. Works with AWS S3, Backblaze B2, Wasabi, DigitalOcean Spaces, and self-hosted MinIO.

Why you would want your own bucket in the first place

Most people reach for bring-your-own-storage (BYOS) for one of three very practical reasons, and none of them are about cryptography on paper.

The first is cost control. If you already pay for Backblaze B2 or Wasabi, or you have an AWS account for other projects, you are paying per gigabyte at rates that are often far cheaper than a bundled app subscription. Pointing Filarr at that bucket means your notes and files ride on storage you already budget for.

The second is ownership and portability. When your data lives in a bucket with your name on the account, nobody can quietly change the terms, raise the price on your plan, or lock you out. You can download the raw objects any time with standard S3 tooling, move to another provider, or keep a copy on a NAS running MinIO in your own home.

The third is a compliance or policy requirement. Some people genuinely need their data to sit in a specific region, under a specific provider, or on infrastructure they can point an auditor at. A freelancer handling client files, an accountant, or anyone under a data-residency rule often cannot use a generic cloud default. If that sounds like your situation, the companion pieces on protecting client data without an IT department and the broader case for self-hosted, actually-encrypted Notion alternatives are worth a read alongside this one.

The encryption is the reassurance layer underneath all three. You get the control you came for, and because Filarr encrypts everything before upload, you do not trade privacy to get it. Let me walk you through the whole setup, honestly, including the parts that are a bit fiddly.

What BYOS actually does in Filarr (and what it does not)

Before touching any settings, it helps to understand what moves where, because it changes how you think about the bucket.

In BYOS mode, Filarr sends only your file contents to your S3 bucket. Each file is stored under a key shaped like folderId/fileId/fileName. Your folder structure, item metadata, and reminders stay in Filarr's local storage on your machine. So the bucket is a content store, not a full mirror of your workspace's organisation. That is a deliberate design choice, and it is worth knowing because it means your bucket on its own is not a complete, human-browsable copy of your workspace. It is a pile of encrypted objects keyed by internal IDs.

More importantly, every object that lands in your bucket is already encrypted on your device. Filarr encrypts the file content with AES-256-GCM before the upload call runs, so what the S3 API receives is ciphertext plus the authentication tag. Your encryption password and keys never travel to the bucket. If you want the deep version of how per-file keys work, the write-up on why per-file encryption with a KEK and FEK matters covers the exact key hierarchy Filarr uses. The short version: a per-file key encrypts each file, and that key is itself wrapped by a key derived from your password, so one global master key is never the single point of failure.

This is the same zero-knowledge principle Filarr's own optional sync follows. If you are curious how the server (or in this case, your bucket) stays blind to your content, the look inside how Filarr's cloud sync stays zero-knowledge applies almost directly to BYOS: files upload already-encrypted, and the storage layer only ever sees opaque blobs.

One honest caveat up front: BYOS is a feature tied to a paid sync plan (Filarr stays free forever for purely local use, and paid cloud sync starts at 4 euros per month). If the Storage Provider section tells you to upgrade, that is why. You are not paying Filarr for storage in BYOS mode, you are paying for the sync capability that drives your own bucket.

Before you start: what you will need

To complete this guide you need three things ready:

1. An S3-compatible storage account. That means AWS S3, Backblaze B2, Wasabi, DigitalOcean Spaces, or a self-hosted MinIO instance. Anything that speaks the S3 API will work, because Filarr uses the standard AWS SDK under the hood.
2. A bucket created in that account, plus its region.
3. An access key pair for that bucket: an Access Key ID and a Secret Access Key.

That is genuinely all. The rest is filling in a short form inside Filarr. Let me go through the bucket preparation first, because that is where most of the real work and most of the mistakes happen.

Step 1: Create and prepare your bucket

The exact clicks differ per provider, but the shape is always the same: create a private bucket, note its region, and generate a key pair scoped to it.

Create the bucket private. Never make it public. Filarr does not need public read access, and because your objects are encrypted the bucket contents would be useless to anyone anyway, but leaving a bucket public is a bad habit that invites accidental exposure of object listings and metadata. Keep it private.

Pick a region you will remember. You will type this region into Filarr, and for some providers it is baked into the endpoint URL too. Choose a region close to you for lower latency, or one that satisfies any data-residency requirement you have.

Generate a scoped key pair. Create an access key that can read, write, list, and delete objects in that one bucket. On AWS this means an IAM user or role with a policy granting s3:GetObject, s3:PutObject, s3:DeleteObject, and s3:ListBucket on the bucket and its contents. On Backblaze, Wasabi, or DigitalOcean, generate the equivalent application key and restrict it to the bucket if the provider lets you. Scoping the key to a single bucket means that even in the worst case, a leaked key cannot touch the rest of your account.

Optional but recommended: enable versioning. Turning on bucket versioning gives you a safety net. If a file is overwritten or deleted, the previous version is still recoverable at the storage layer. This pairs well with a broader backup routine, which I cover in the pitfalls section below and in the guide on backing up encrypted notes without breaking zero-knowledge.

If you prefer the command line and you are on AWS specifically, the repository ships a helper script at scripts/setup-s3.sh that will validate your AWS credentials, create the bucket, enable versioning and server-side encryption, set a lifecycle policy, and run an upload/download test for you. It also knows how to spin up a local MinIO container for testing. It is a convenience, not a requirement, and the in-app flow below does not depend on it.

Step 2: Add the provider inside Filarr

Now the easy part. Open Filarr, go to Settings, and find the Storage Provider section. It is described in the app as "Configure your own S3-compatible storage provider (BYOS, Bring Your Own Storage)."

Click Add provider. You will see a short form with these fields:

• Provider name. A friendly label for your own reference, like "Backblaze home" or "AWS work bucket." This is cosmetic.
• Provider type. The kind of S3-compatible service you are connecting.
• Endpoint URL. The S3 API endpoint. For AWS S3 you can leave this blank, and Filarr will build the standard s3.<region>.amazonaws.com endpoint from the region automatically. For every other provider you must fill it in (examples below).
• Region. The region you chose when creating the bucket, for example us-east-1 or eu-west-1.
• Bucket. The exact bucket name.
• Access Key ID. The public part of your key pair.
• Secret Access Key. The secret part. This is the sensitive one.

Here is a detail that matters for correctness: when you provide a custom endpoint (anything that is not AWS), Filarr automatically switches the S3 client into path-style addressing (endpoint/bucket/key rather than bucket.endpoint/key). You do not have to configure this, but it is why MinIO, Backblaze, Wasabi, and DigitalOcean endpoints work out of the box. Just enter the endpoint and Filarr handles the addressing style for you.

A word on where your secret goes, because this is the question privacy-minded users always ask. When you save the provider, Filarr splits the data: the non-secret config (endpoint, region, bucket, Access Key ID) is written to a local byos-providers.json file, and the Secret Access Key is stored separately, encrypted, in a credentials.enc file with restrictive file permissions. That secret is encrypted with AES-256-GCM using a key derived with PBKDF2-SHA512 over 600,000 iterations from your installation's master key. Your S3 secret is never written to disk in plaintext and never sent anywhere except directly to your own storage provider when a transfer runs.

Step 3: Test the connection

Do not skip this. After saving the provider, click Test connection. Filarr verifies that the stored credential exists and that the endpoint is reachable. A successful test ("Connection successful") and a recorded "Last tested" timestamp mean Filarr can talk to your bucket.

If the test fails, ninety percent of the time it is one of these, in rough order of likelihood:

• A typo in the bucket name or region. These are case- and character-exact.
• A wrong or missing endpoint for a non-AWS provider. Double-check the exact host your provider gives you.
• A key pair that lacks permission on the bucket, or that was scoped to a different bucket.
• A region mismatch, where the bucket lives in one region but you entered another.

Fix the field, save, and test again. It is normal to need one or two tries on your first provider.

Step 4: Set it as default and start syncing

Once the test passes, use Set as default to make this provider the active storage target. Filarr marks the first provider you add as the default automatically, but if you have more than one, you choose. From here, file content you add to your workspace is encrypted locally and uploaded to your bucket, and reading a file downloads the encrypted blob and decrypts it on your machine.

That is the whole loop. Your workspace feels identical to local-only use, but your files now live in storage you own.

Provider-specific notes

The fields are the same everywhere, but the endpoint format trips people up, so here are the common patterns. Always confirm the exact host in your provider's own dashboard, since regions and formats change.

AWS S3. Leave the endpoint blank. Enter the region (for example eu-west-1) and bucket. Filarr constructs the endpoint for you. Create an IAM key scoped to the bucket.

Backblaze B2. Use the S3-compatible endpoint shown in your bucket details, which looks like s3.us-west-004.backblazeb2.com. The region is the matching value such as us-west-004. Generate an application key limited to the bucket.

Wasabi. The endpoint looks like s3.eu-central-1.wasabisys.com (the region segment varies). Wasabi's flat per-terabyte pricing makes it popular for exactly this use case.

DigitalOcean Spaces. The endpoint looks like nyc3.digitaloceanspaces.com, where nyc3 is the region. Generate Spaces access keys from the API section of your DigitalOcean dashboard.

Self-hosted MinIO. Point the endpoint at your own server, for example http://192.168.1.50:9000 on a home network or an HTTPS URL if you have put MinIO behind a reverse proxy. Use the access key and secret you configured on the MinIO side. This is the most private option of all, since the storage never leaves hardware you physically control. If you want to test MinIO quickly, the bundled scripts/setup-s3.sh can launch a local MinIO container for you.

Pitfalls and best practices

A few things that will save you grief, learned the honest way.

Your recovery phrase is the whole ballgame. Because files are encrypted before upload, your bucket is worthless to an attacker, but it is equally worthless to you if you lose your password and your 24-word BIP-39 recovery phrase. There is no "reset password" that can read your data, because Filarr never had your key. Write the recovery phrase down and store it somewhere safe and offline. This is the direct trade-off of real zero-knowledge encryption, and it is the same trade every serious encrypted tool makes. The broader guide on how to encrypt your notes goes deeper on why recovery keys matter.

BYOS is sync, not backup. A synced bucket and a backup are different things. If you delete a file and the deletion propagates, it is gone from the bucket too. Enable bucket versioning (Step 1) so the storage layer keeps old versions, and keep at least one independent copy. Sync protects against a dead laptop. It does not protect against you deleting the wrong thing.

Scope your keys tightly, and rotate them. Use a key limited to the single bucket. If you ever suspect a key is compromised, generate a new pair at the provider, update the provider in Filarr, and delete the old key. Because the secret is stored encrypted locally and nowhere else, rotation is a two-minute job.

Mind your region for latency and compliance. A bucket on the other side of the world will feel slow on large files. Pick a near region unless a residency rule forces otherwise.

Keep the config file, protect the machine. Your byos-providers.json holds non-secret config and credentials.enc holds the encrypted secret. Both live in your user data folder. Full-disk encryption on your machine is still worth having as a second layer, for reasons laid out in the comparison of local encryption versus classic cloud when data leaks.

Test after any change. Changed a key, moved regions, renamed a bucket? Run Test connection again. It takes seconds and tells you immediately whether transfers will work.

FAQ

Does Filarr see my files when I use my own bucket? No. Files are encrypted with AES-256-GCM on your device before upload. Filarr's servers are not in the path at all in BYOS mode, and your own bucket only ever stores opaque encrypted blobs. Your keys never leave your machine.

Which providers are supported? Any S3-compatible storage: AWS S3, Backblaze B2, Wasabi, DigitalOcean Spaces, and self-hosted MinIO are the common ones. Filarr uses the standard AWS S3 SDK, so if a provider speaks the S3 API, it will work. For AWS leave the endpoint blank, and for everything else set the endpoint explicitly.

Is BYOS free? Filarr is free forever for local-only use. BYOS runs through a paid sync plan (paid cloud sync starts at 4 euros per month). You do not pay Filarr for storage in BYOS mode, you pay for the sync capability, and you pay your storage provider separately for the bucket itself.

What happens if I lose my password? Your encrypted files in the bucket become unrecoverable, because no one, including Filarr, holds a copy of your key. This is the point of zero-knowledge encryption. Your 24-word recovery phrase is the only fallback, so store it offline and safe.

Does my folder structure get uploaded too? In BYOS mode, only file content goes to your bucket, stored under internal keys of the form folderId/fileId/fileName. Folder organisation, item metadata, and reminders stay in local storage on your device. The bucket is a content store, not a browsable mirror of your workspace.

Can I switch providers later or run more than one? Yes. You can add multiple providers and choose which one is the default. To move, add the new provider, test it, and set it as default. Because objects are standard S3 blobs, you can also copy them between buckets with any S3 tool if you want to migrate the underlying storage.

Wrapping up

Setting up BYOS in Filarr comes down to four moves: prepare a private bucket with a scoped key pair, add it under Settings in the Storage Provider section, test the connection, and set it as default. Do that once and your workspace syncs through storage you own, at the price you already negotiated with your provider, with no vendor holding your data hostage.

The encryption is what lets you do all of that without giving anything up on privacy. Your files are sealed with AES-256-GCM before they ever reach the bucket, so ownership and confidentiality stop being a trade-off. Create the bucket, paste in the keys, run the test, and you are done. If you are still deciding whether local-first ownership fits how you work, the ranked overview of the best local-first apps in 2026 is a good next stop.