# Buckets

A bucket keeps an app's files outside its container: what its users upload, exports it writes, assets it generates. It speaks S3, so every S3 client and SDK works with it.

Keep files in a bucket rather than a [volume](/docs/volumes) when you can. A service with a volume runs on one server: it can't scale out across servers, and it can't move when its server goes. A service that keeps its files in a bucket stays free to sleep, scale out and move.

## Make one

On the project's canvas, **+ Create → Bucket**, and give it a name, like `uploads`. It sits on the canvas beside your services, with how much it holds, and a dashed line from each app that uses it. Click it to open its page.

Making a bucket makes a key for it, and shows the key's secret **once**. You only need it for a tool on your own computer: apps get it by reference (below).

## Connecting an app

In the bucket's window, on **Connect**, choose the app and click **Connect**. The app gets five variables and is deployed with them:

| Variable | Holds |
| --- | --- |
| `S3_ENDPOINT` | `https://storage.smartalfred.com` |
| `S3_BUCKET` | The bucket's name over S3, like `uploads-k3m9x2ab` |
| `S3_REGION` | `auto` |
| `S3_ACCESS_KEY_ID` | The key's id |
| `S3_SECRET_ACCESS_KEY` | The key's secret |

What's stored on the app are [references](/docs/variables-and-secrets) like `${{uploads.S3_BUCKET}}`, not copies. Give the bucket a new key and the app has it with its next deploy.

Then use them in your code with any S3 SDK: [buckets in your code](/docs/bucket-code).

## Its files

The bucket's **Files** tab shows what's in it a folder at a time, with each file's size and when it changed; folders are how keys read up to each `/`. **Open** gives you the file through a link signed with the bucket's key and good for ten minutes; **Delete** removes it for good. The page's header says how much the bucket holds and roughly what that costs a month.

## Good to know

- One upload in a single request can be up to 100 MB. Larger files go up in parts, which every S3 SDK does by itself for large files.
- Storage is billed like volumes, by the gigabyte-month of what's held. Requests and data transfer aren't billed.
- **New key** makes a new key and shows its secret once. The old key keeps working for a day, so connected apps carry on until their next deploy gives them the new one.
- Deleting a bucket deletes every file in it, for good. So does deleting its project.
- A project can have up to 10 buckets.
- A bucket's name can't be the name of a service in the same project: references name both the same way.
- Agents have the same: `create_bucket`, `connect_bucket`, `list_buckets`, `rotate_bucket_key` and `delete_bucket` in the [agent tools](/docs/agent-tools).