Create and manage storage buckets

A bucket is a named container for objects in a single region. It’s the unit of access control, CORS, and the smallest thing you can hand a credential to.

Prerequisites

A paid plan. Object storage isn’t available on the Free tier.
A workspace context. Buckets belong to the workspace you create them under (personal or team).

Create a bucket

From the dashboard

Open the dashboard.
Go to Object storage → Buckets and click New bucket.
Pick a name. Lowercase letters, digits, and dashes; minimum 3 characters. Names are slugified on save (My Cool Bucket becomes my-cool-bucket).
Pick a region. This is permanent; you can’t move a bucket between regions later, you can only migrate the contents.
Click Create. The bucket is ready immediately.

New bucket dialog showing the name input, region selector, and the Create button — The New bucket dialog with name and region.

Once created, the bucket detail page shows the endpoint URL and region you’ll pass to S3 clients.

Bucket detail page with endpoint URL, region, object count, total size, and tabs for Objects, Credentials, CORS, Migrations, and Settings — A bucket's detail page with endpoint, region, and the per-bucket tabs.

From the API

POST /v1/storage/buckets
x-brimble-key: <your API key>
Content-Type: application/json

{ "name": "uploads", "region": "fra" }

Omit region to use global. See Create a bucket for every field.

Regions

ID	Location
`global`	Global. Data is distributed and follows access patterns. Default.
`sjc`	San Jose, California, USA
`ord`	Chicago, Illinois, USA
`iad`	Ashburn, Virginia, USA
`ams`	Amsterdam, Netherlands
`fra`	Frankfurt, Germany
`lhr`	London, United Kingdom
`sin`	Singapore
`nrt`	Tokyo, Japan
`los`	Lagos, Nigeria

Pick the region closest to the services that read and write the data, or global if your users are spread out. To get the current list programmatically, call GET /v1/storage/regions.

Buckets in los (Lagos) support CORS, public access and custom domains, but not lifecycle rules or versioning.

List buckets

The Buckets tab lists every bucket in the current workspace with its region, object count, and total size. Click a bucket to open its detail page. For programmatic listing, paginated with page and limit (max 100), and a q query parameter for name search.

What’s fixed at creation

A bucket’s name and region are permanent. Neither can be changed after the bucket is created, the name is the path component every S3 URL embeds, and the region pins where the data physically lives. If you need a different name or a different region, create a new bucket and migrate the data over, then delete the old one. Object keys (the part after the bucket name) carry over unchanged. What you can change post-creation:

CORS rules (see below).
Credentials issued against the bucket. See Storage credentials.
Object data. See Working with objects.

Lagos region

Lagos (los) is Brimble’s object-storage region in Lagos, Nigeria. Choose it when most of your uploads or downloads are in West Africa and you want the data to live close to those clients. Like every other region, the choice is permanent for that bucket. Configure your S3 client with these three settings:

Setting	Value
Endpoint	`https://s3.los.brimble.io`
Region	`los`
Addressing	Path-style (`forcePathStyle: true`, or your SDK’s equivalent)

import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.los.brimble.io",
  region: "los",
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

Set the region to los explicitly. Requests are signed with the region, so leaving your SDK on its default (us-east-1, or auto in R2-style setups) makes every request fail with 403 SignatureDoesNotMatch, even when the keys are correct. Virtual-hosted URLs like my-bucket.s3.los.brimble.io aren’t served, so keep path-style addressing on.

See Working with objects for more SDK examples. Lagos buckets support the usual day-to-day S3 work: list, head, get, put, delete, multipart upload, CORS, storage credentials, and making a bucket public or private from the dashboard.

Limitations

Compared with other object-storage regions, Lagos does not support:

Lifecycle rules. You can’t attach expiry or transition rules on the bucket. Delete or rewrite objects from your app or with an S3 client when you need cleanup.
Bucket policies. Access is only through storage credentials (and public read when the bucket is marked public). There is no separate bucket-policy document to attach.
Server-side object copy. Operations that rely on S3 CopyObject (copying or renaming a key inside the bucket without downloading it) are not available. To duplicate or move an object, download it and upload it under the new key, or migrate into another bucket.

If you need lifecycle rules or server-side copy, create the bucket in a region that lists those capabilities in the dashboard, or keep Lagos for the Africa-local data path and use another bucket for workflows that need those features.

CORS rules

If you upload to or read from a bucket directly from a browser (presigned URLs in a single-page app, file-picker uploads, direct video playback), the browser will check the bucket’s CORS configuration before issuing requests from your domain. Open Object storage → Buckets → <bucket> → CORS and add rules, or set them in brimble.toml. Each rule is a list of allowed origins, methods, headers, and an optional max age for the browser preflight cache.

CORS configuration panel with allowed origins, allowed methods checkboxes, allowed headers, expose headers, and max-age seconds inputs — The CORS configuration panel with a rule editor.

brimble.toml

[buckets.uploads]
cors = [
  { origins = ["https://app.example.com", "https://staging.example.com"], methods = ["GET", "HEAD", "PUT", "POST", "DELETE"], headers = ["*"], expose_headers = ["ETag"], max_age = "1h" },
]

origins is required and must contain at least one origin. Use the exact origin (https://app.example.com), not a hostname or wildcard host.
methods must be a non-empty subset of GET, HEAD, PUT, POST, DELETE.
headers and expose_headers are optional. Use ["*"] on headers if your client sends custom headers and you don’t want to enumerate them.
max_age caches the preflight result in the browser, as a duration such as "1h". One hour is a reasonable default.

You can configure up to 100 rules per bucket. Rules are evaluated top-down; the first matching rule wins.

origins = ["*"] opens the bucket to any browser-driven script on any domain. Useful for public download buckets; risky for anything that holds user-scoped data. Prefer an explicit list of origins.

Delete a bucket

Open the bucket’s Settings tab and click Delete bucket. You’ll be asked to confirm by typing the bucket name.

Deletion is permanent and immediate. The bucket, its objects, and every credential issued against it are removed. There is no soft-delete and no restore. If the data matters, migrate it out or copy it to another bucket first.

A non-empty bucket can be deleted; Brimble removes the contents as part of the delete. For very large buckets this can take a few minutes to fully reclaim.

Bucket overview metrics

The Overview tab on a bucket shows:

Total size (current GB held).
Object count.
Region.
Endpoint URL.

The same tab on the Object storage root shows aggregate metrics across all buckets in the workspace.

Troubleshooting

“Bucket name must be at least 3 characters.” Names are sanitized to lowercase + dashes, and a too-short final slug is rejected. Pick a longer name. “Bucket name already taken.” Bucket names must be unique within your workspace. Pick a different one, or check whether it already exists under Object storage → Buckets. Browser request blocked by CORS. The bucket’s CORS configuration doesn’t include your origin or the method you used. Open the bucket’s CORS tab, add a rule for the origin in question, and retry. Browsers cache the preflight; a hard reload clears it. Can’t delete bucket. A credential or an in-flight migration is holding the bucket. Cancel any running migrations first, then retry the delete.

Next steps

Working with objects, upload, download, list, delete.
Storage credentials, issue keys to read and write the bucket.
Migrate from another provider, bring an existing bucket over.

Getting started

Brimble Agent

Brimble MCP

CLI

Projects

Databases

Config as code

Sandboxes

Volumes

Object storage

Domains

Environments

Networking

Scaling

Observability

Analytics

Workspaces and teams

Security

Billing

Notifications

Webhooks

Log Drains

Troubleshooting

Reference

Create and manage storage buckets

Prerequisites

Create a bucket

From the dashboard

From the API

Regions

List buckets

What’s fixed at creation

Lagos region

Limitations

CORS rules

Delete a bucket

Bucket overview metrics

Troubleshooting

Next steps

​Prerequisites

​Create a bucket

​From the dashboard

​From the API

​Regions

​List buckets

​What’s fixed at creation

​Lagos region

​Limitations

​CORS rules

​Delete a bucket

​Bucket overview metrics

​Troubleshooting

​Next steps

Prerequisites

Create a bucket

From the dashboard

From the API

Regions

List buckets

What’s fixed at creation

Lagos region

Limitations

CORS rules

Delete a bucket

Bucket overview metrics

Troubleshooting

Next steps