# S3 protocol

> Use AWS SDKs, rclone, Cyberduck or s3cmd with a SupaHost project's Storage buckets over the S3 protocol. Endpoint, region, access keys, path-style addressing and examples.

Source: https://supahost.app/docs/storage/s3 · Updated 2026-11-11

Every SupaHost project's Storage also speaks the S3 protocol. You can point S3 tools and libraries, such as the AWS SDKs, rclone, Cyberduck and s3cmd, at your project and work with the same buckets and files you use through `supabase.storage`. A file uploaded over S3 shows up in the Storage API and Studio straight away, and the other way round.

The files are still stored on your instance's disk, in your region. S3 here is just another way in; nothing is stored in Amazon S3.

## Connection details

Open *Dashboard → your project → **Connect** → **Storage (S3)***. The tab shows:

| Setting | Value |
|---|---|
| Endpoint | `https://app-one.acme.supahost.space/storage/v1/s3` (your project URL plus `/storage/v1/s3`) |
| Region | `auto` |
| Access key ID | Shown after **Reveal access keys** |
| Secret access key | Shown after **Reveal access keys** |

Each project has one access key pair. Only the instance owner can reveal it; team members see the endpoint and region only.

Two things every client needs:

- **Path-style addressing.** Bucket names go in the path (`/storage/v1/s3/avatars/...`), not in the hostname. In the AWS SDKs, set `forcePathStyle: true`. Other tools have a similar option.
- **A region for signing.** Use `auto`. If a tool insists on a real AWS region, `us-east-1` also works. The region is only used to sign requests; your data stays in your instance's region.

## Keep the keys on your server

The S3 access keys have full access to every bucket in the project and bypass Storage RLS policies, like the `service_role` key. Use them only on servers, in CI and in admin tools you control. Never put them in a browser, mobile app or anything you ship to users.

For users uploading and downloading their own files, keep using `supabase.storage` with their session, so your RLS policies apply. Per-user S3 access with a user's session token isn't offered; only the access keys work over S3.

## JavaScript (AWS SDK v3)

```ts
import { S3Client, PutObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3'
import { readFile } from 'node:fs/promises'

const s3 = new S3Client({
  endpoint: 'https://app-one.acme.supahost.space/storage/v1/s3',
  region: 'auto',
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  },
})

await s3.send(new PutObjectCommand({
  Bucket: 'reports',
  Key: '2026/11/summary.pdf',
  Body: await readFile('summary.pdf'),
  ContentType: 'application/pdf',
}))

const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket: 'reports', Prefix: '2026/' }))
```

The bucket must already exist. Create it in Studio or with `supabase.storage.createBucket`, so its settings (public or private, size limit, allowed types) are set the way you want.

## Python (boto3)

```python
import os
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://app-one.acme.supahost.space/storage/v1/s3",
    region_name="auto",
    aws_access_key_id=os.environ["S3_ACCESS_KEY_ID"],
    aws_secret_access_key=os.environ["S3_SECRET_ACCESS_KEY"],
    config=boto3.session.Config(s3={"addressing_style": "path"}),
)

s3.upload_file("summary.pdf", "reports", "2026/11/summary.pdf")
```

## rclone

Add a remote to `~/.config/rclone/rclone.conf`:

```ini
[supahost]
type = s3
provider = Other
endpoint = https://app-one.acme.supahost.space/storage/v1/s3
region = auto
force_path_style = true
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_ACCESS_KEY
```

Then copy or sync folders:

```bash
rclone ls supahost:reports
rclone copy ./exports supahost:reports/2026/11
rclone sync supahost:avatars ./avatars-copy
```

rclone is also a simple way to keep your own copy of a project's files outside SupaHost.

## Cyberduck and s3cmd

Desktop and command-line tools such as Cyberduck and s3cmd work too. Give them the same four things: the endpoint (including `/storage/v1/s3`), the region `auto`, the access key pair, and path-style requests rather than bucket subdomains.

## Large files

Multipart uploads are supported, and the AWS SDKs and rclone use them automatically for larger files. The 50 MB limit per file still applies, whether a file arrives over S3 or the Storage API, and a bucket's own size limit can lower it further. See [Storage limits and quotas](/docs/storage/limits).

## What to expect

- Buckets, objects and their metadata are the same as in the Storage API. A file uploaded over S3 has a `storage.objects` row and is included in file backups and restores.
- Public buckets stay public. Their files are still served at the usual public URLs.
- Deleting a file over S3 deletes it from Storage too. There's no separate S3 copy.
- Requests over S3 count toward egress like any other Storage request.

## Related

- [Storage on SupaHost](/docs/storage/overview)
- [Storage access control](/docs/storage/access-control)
- [Uploading files](/docs/storage/uploads)
