Connect S3-compatible storage
Add AWS S3, Cloudflare R2, MinIO, Backblaze B2, Wasabi, and other S3-compatible providers to BucketMate for macOS with endpoints and access keys.
BucketMate connects to S3-compatible storage by using the same values you would use with an S3 SDK: endpoint, region, access key, secret key, and optionally a limited bucket list.
Supported providers
- AWS S3
- Google Cloud Storage
- Cloudflare R2
- Backblaze B2
- DigitalOcean Spaces
- Wasabi
- Supabase Storage
- Hetzner Object Storage
- Tigris
- MinIO
- Other S3-compatible endpoints
Connection fields
| Field | How to use it |
|---|---|
| Connection Name | Optional label shown in the sidebar. Use names like Production R2 or Backups MinIO. |
| Provider | Select the closest provider. Use Other for custom S3-compatible endpoints. |
| Authentication Method | Shown for AWS S3 only. Choose Access Key or AWS Profile. Other providers use access keys. |
| Endpoint | Required for every provider except AWS S3. AWS S3 can leave this empty. |
| Use virtual-hosted style | Shown for MinIO and Other. Puts the bucket name in the hostname instead of the path. See Virtual-hosted style. |
| Access Key ID | Provider access key, HMAC key, application key ID, or token access key. |
| Secret Access Key | Matching secret for the access key. |
| Custom domain | Shown for Cloudflare R2 only. Optional public domain used for Copy URL (custom domain). |
| Region | Provider region. Choose Custom... to type a region that is not in the list. Cloudflare R2 uses auto. MinIO and Other default to us-east-1. |
| Load all buckets | Keep on when credentials can call ListBuckets. Turn off when credentials are scoped to specific buckets. |
General connection steps
- Open BucketMate.
- Choose Add connection in the sidebar.
- Select the provider.
- Enter the endpoint, region, and credentials.
- Use Test Connection.
- Choose Connect.
- Select a bucket from the sidebar and start managing files.
BucketMate stores the access key and secret key in the macOS Keychain on your Mac. macOS may ask you to allow BucketMate to access them.
To change a connection later, right-click it in the sidebar and choose Edit, then choose Save.
Import from rclone, Cyberduck, or s3cmd
If your connections are already set up in another app, import them instead of typing keys again.
- Choose Import from another app at the top of the connection form, or choose File > Import Connections… (⇧⌘I).
- Choose the app you're importing from, then choose Choose file….
- Pick the file in the file picker. BucketMate reads only what you choose, and nothing is read before you choose Open.
- Review the list. Select the connections to import, and expand a row to rename it, change the provider, or choose Test connection.
- Choose Import.
| App | What to pick | Where it usually is |
|---|---|---|
| rclone | rclone.conf | ~/.config/rclone/rclone.conf |
| Cyberduck and Mountain Duck | One or more .duck bookmark files, or the whole Bookmarks folder | ~/Library/Group Containers/G69SCX94XU.duck/Library/Application Support/duck/Bookmarks |
| s3cmd | .s3cfg | ~/.s3cfg |
The file picker opens in the usual folder and shows hidden files, so you can find .config and .s3cfg.
Imported keys are saved to the macOS Keychain, like connections you add by hand. Nothing is uploaded.
Cyberduck secret keys
Cyberduck keeps secret keys in its own Keychain item, not in the bookmark files. For each Cyberduck connection, paste the secret key in the row, or choose Look up in Keychain and allow access when macOS asks. If BucketMate can't find it, copy the secret key from Cyberduck or your provider's console and paste it.
What can't be imported
| Badge | Meaning |
|---|---|
| Already added | A connection with the same endpoint and access key is already in BucketMate. |
| Not supported | The connection has no access key, for example an rclone remote with env_auth = true. Add AWS connections like this with AWS Profile instead. |
BucketMate imports S3 connections only. Other rclone remotes, such as Google Drive or SFTP, and other Cyberduck protocols are skipped.
With the free plan, you can import one connection. Upgrade to Pro to import all of them.
AWS profiles and SSO
For AWS S3, choose AWS Profile when you already use profiles from ~/.aws/config or ~/.aws/credentials. BucketMate lists the profiles it finds on your Mac in a searchable picker. SSO profiles show (SSO) after the name and a Login with SSO button.
Use AWS Profile when:
- You already manage credentials through the AWS CLI.
- Your team rotates short-lived credentials.
- You use AWS SSO and do not want to paste access keys into the app.
See AWS S3 for the full SSO flow.
Limited bucket permissions
Some credentials can access objects inside a bucket but cannot list all buckets in the account. BucketMate supports this setup.
- Turn off Load all buckets.
- Enter one or more bucket names in Buckets.
- Press Space or Enter after each bucket name.
- Test the connection.
BucketMate will show only the buckets you entered.
Single-bucket endpoints
If the endpoint already contains a bucket name, BucketMate shows Endpoint restricted to single bucket and turns off Load all buckets automatically.
Examples:
| Provider style | Example |
|---|---|
| Path-style endpoint | https://storage.example.com/my-bucket |
| AWS virtual-hosted endpoint | https://my-bucket.s3.us-east-1.amazonaws.com |
| Google Cloud Storage virtual-hosted endpoint | https://my-bucket.storage.googleapis.com |
This is useful for locked-down credentials, self-hosted storage, and providers that issue bucket-specific endpoints.
Virtual-hosted style
S3 requests can address a bucket in two ways:
| Style | Request URL |
|---|---|
| Path-style | https://storage.example.com/my-bucket/photo.jpg |
| Virtual-hosted style | https://my-bucket.storage.example.com/photo.jpg |
BucketMate uses path-style for custom endpoints by default. Most S3-compatible servers accept it, and it works without wildcard DNS or certificates.
Some providers accept only virtual-hosted style. They reject path-style requests with errors such as SecondLevelDomainForbidden, Please use virtual hosted style, or 403 Access denied. Alibaba Cloud OSS is one example.
To use virtual-hosted style:
- Select MinIO or Other as the provider.
- Enter the endpoint without a bucket name, such as
https://oss-ap-southeast-1.aliyuncs.com. - Turn on Use virtual-hosted style.
- Test the connection.
Turn it on only when your provider requires it:
- Your provider's DNS and TLS certificate must cover
<bucket>.<endpoint host>. Some providers, such as Hetzner, issue certificates that do not cover bucket subdomains, so keep the option off for them. - Bucket names that contain dots may fail over HTTPS because they do not match a wildcard certificate.
- For self-hosted MinIO, set
MINIO_DOMAINon the server first.
Copied object URLs follow the style you choose.
HTTP endpoints
MinIO and Other connections can use http:// endpoints. BucketMate shows a warning because HTTP traffic is not encrypted. Use HTTP only on trusted networks, such as a local development server. Use https:// for everything else.
Endpoint examples
| Provider | Endpoint |
|---|---|
| AWS S3 | Leave empty, or use https://s3.<region>.amazonaws.com |
| Google Cloud Storage | https://storage.googleapis.com |
| Cloudflare R2 | https://<account-id>.r2.cloudflarestorage.com |
| Backblaze B2 | https://s3.<region>.backblazeb2.com |
| DigitalOcean Spaces | https://<region>.digitaloceanspaces.com |
| Wasabi | https://s3.<region>.wasabisys.com |
| Supabase Storage | https://<project-ref>.storage.supabase.co/storage/v1/s3 |
| Hetzner Object Storage | https://<location>.your-objectstorage.com |
| Tigris | https://t3.storage.dev |
| MinIO | https://<your-minio-endpoint> |
BucketMate checks that provider endpoints contain the expected domain. For example, a Cloudflare R2 endpoint must contain r2.cloudflarestorage.com.
Manage connections in the sidebar
Right-click a connection to:
- Add bucket
- Edit the connection
- Refresh its bucket list
- Pin or Unpin it
- Show hidden buckets or Hide hidden buckets when the connection has hidden buckets
- Show QR for mobile
- Delete the connection
Drag a connection onto another connection to change the order in the sidebar.
Add a connection to iPhone or iPad
You can copy a connection to the BucketMate iOS app without typing credentials again.
- Right-click the connection in the sidebar.
- Choose Show QR for mobile.
- Scan the QR code from the BucketMate app on your iPhone or iPad.
The QR code contains the connection credentials, so show it only to devices you trust. Quick connect does not support AWS SSO connections.
After connecting
- Pin important connections so they stay near the top.
- Hide buckets you rarely use.
- For Cloudflare R2, add a Custom domain in the connection form when you want BucketMate to copy custom-domain URLs.
- Use workspaces to separate personal, client, staging, and production storage setups.
- Use the refresh action when bucket contents changed outside BucketMate.
Troubleshooting
Test Connection fails
Check that the endpoint includes the right scheme, the region matches the bucket, and the access key has permission for the bucket you are testing. Choose View logs in the connection form to see each request and error. See Troubleshooting for more.
Buckets do not appear
If credentials cannot call ListBuckets, turn off Load all buckets and enter bucket names manually.
MinIO or local endpoint does not connect
Check whether the server uses HTTP or HTTPS and enter the matching scheme. HTTPS endpoints need a certificate that macOS trusts.
Provider rejects path-style requests
If the test fails with SecondLevelDomainForbidden or a message asking for virtual hosted style, turn on Use virtual-hosted style. See Virtual-hosted style.
Import says the rclone config is encrypted
BucketMate can't read encrypted rclone configs. Run rclone config show to print a plain copy, save it to a file, and import that file. Delete the plain copy afterwards.
Import finds no S3 connections
The file has no S3 remotes or S3 bookmarks. In rclone, S3 remotes have type = s3. Backblaze B2 remotes that use type = b2 aren't S3 remotes, so add them by hand with your B2 S3 endpoint.
Cloudflare R2 region fails
Use auto for Cloudflare R2.
Large bucket search is incomplete
Large buckets need to load all items before search is available. Choose Load all items when BucketMate asks.