# Connect S3-compatible storage

> Add AWS S3, Cloudflare R2, MinIO, and other S3-compatible providers to BucketMate

Canonical: https://docs.bucketmate.app/macos/features/connect-s3-compatible-storage

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
- MinIO
- Supabase Storage
- Custom 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 | AWS S3 can use **Access Key** or **AWS Profile**. Other providers use access keys. |
| Endpoint | Required for S3-compatible providers. AWS S3 can usually leave this empty. |
| Access Key ID | Provider access key, HMAC key, application key ID, or token access key. |
| Secret Access Key | Matching secret for the access key. |
| Region | Provider region. Cloudflare R2 uses `auto`. MinIO defaults to `us-east-1`. |
| Bucket list permission | Keep enabled when credentials can call `ListBuckets`. Disable it when credentials are scoped to specific buckets. |

## General connection steps

1. Open BucketMate.
2. Choose **Add Connection**.
3. Select the provider.
4. Enter the endpoint, region, and credentials.
5. Use **Test Connection**.
6. Save the connection.
7. Select a bucket from the sidebar and start managing files.

## AWS profiles and SSO

For AWS S3, choose **AWS Profile** when you already use profiles from `~/.aws/config` or `~/.aws/credentials`. BucketMate detects local profiles and shows SSO profiles with a **Login with SSO** action when needed.

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.

## Limited bucket permissions

Some credentials can access objects inside a bucket but cannot list all buckets in the account. BucketMate supports this setup.

1. Turn off **Credentials have permission to list buckets**.
2. Enter one or more bucket names.
3. Press Space or Enter after each bucket name.
4. Test the connection.

BucketMate will show only the buckets you entered.

## Single-bucket endpoints

If the endpoint already contains a bucket name, BucketMate treats it as a single-bucket connection and disables automatic bucket listing.

Examples:

| Provider style | Example |
| --- | --- |
| Path-style endpoint | `https://storage.example.com/my-bucket` |
| Virtual-hosted endpoint | `https://my-bucket.storage.example.com` |

This is useful for locked-down credentials, self-hosted storage, and providers that issue bucket-specific endpoints.

## 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` |
| MinIO | `https://<your-minio-endpoint>` |

## After connecting

- Pin important connections so they stay near the top.
- Hide buckets you rarely use.
- Add a custom domain to a bucket 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 `https://`, the region matches the bucket, and the access key has permission for the bucket you are testing.

### Buckets do not appear

If credentials cannot call `ListBuckets`, disable bucket listing and enter bucket names manually.

### MinIO HTTP endpoint does not connect

BucketMate expects HTTPS for MinIO endpoints. Configure TLS for the MinIO endpoint and connect with `https://`.

### Cloudflare R2 region fails

Use `auto` for Cloudflare R2.

### Large bucket search is incomplete

Large buckets may need indexing before full search is available. Use the load-all or indexing action when BucketMate shows that search requires all items.