BucketMate
Providers

MinIO

Step-by-step guide to connect self-hosted MinIO or MinIO-compatible storage to BucketMate for macOS with access keys, a custom endpoint, and path style.

BucketMate connects to MinIO through its S3-compatible endpoint. MinIO is often self-hosted, so endpoint and TLS setup matter more than with managed providers.

Prerequisites

  • MinIO endpoint URL
  • Access key
  • Secret key
  • Bucket name, or permission to list buckets

Endpoint and region

Use your MinIO endpoint:

https://<your-minio-endpoint>

BucketMate also accepts http:// endpoints for MinIO, such as http://localhost:9000. It shows a warning because HTTP is not encrypted. Use HTTP only on trusted networks.

BucketMate defaults MinIO region to:

us-east-1

If your MinIO deployment uses another region, choose Custom... and enter it.

Connection steps

  1. Open BucketMate.
  2. Choose Add connection.
  3. Select MinIO.
  4. Enter the endpoint, including https:// or http://.
  5. Enter the access key and secret key.
  6. Keep region as us-east-1, or enter your custom MinIO region.
  7. If the credentials cannot list buckets, turn off Load all buckets and enter bucket names manually.
  8. Use Test Connection.
  9. Choose Connect.

Common issues and fixes

Path-style vs virtual-hosted style

MinIO defaults to path-style requests. Fix by using path-style URLs, or configure MINIO_DOMAIN to enable virtual-hosted-style access.

Bucket subdomain conflicts

When MINIO_DOMAIN is enabled, subdomains are treated as bucket names. Fix by ensuring DNS records and bucket names do not conflict with other subdomains.

Cannot connect to localhost

Check that the endpoint scheme matches your server. If MinIO listens on HTTP, enter http://localhost:9000 or your port. If it uses TLS, enter https://. To set up HTTPS for local MinIO, follow MinIO HTTPS on localhost.

Browser trust errors

If MinIO uses a self-signed certificate, make sure macOS trusts the certificate before connecting from BucketMate.

Bucket list permission is restricted

If your MinIO policy allows object access but not bucket listing, turn off Load all buckets and enter the bucket names manually.

BucketMate tips

  • Prefer HTTPS. Use HTTP only for local development on a trusted network.
  • Use manual bucket names for restricted MinIO policies.
  • Use workspaces to separate local MinIO, staging MinIO, and production storage.