---
title: "Object storage"
---

> Documentation Index
> Fetch the complete documentation index at: https://ermahgerd-docs.t-bd7662a5eeb4.workers.ermahgerd.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Object storage

ermahgerd includes organization-scoped object storage derived from Barbara's
workerd-native storage engine. It offers two interfaces over the same objects:

* an S3-compatible endpoint for AWS CLI, boto3, SDKs, backups, and direct
  administration;
* R2-style Worker bindings declared in Wrangler configuration.

## Create a bucket

Open **Storage** in the organization section of the console and create a
bucket. A read/write organization token may also use Wrangler's R2 bucket API
after [connecting Wrangler](/build/connect-wrangler/).

Bucket metadata is isolated in an organization-specific Durable Object
namespace. Object paths are random internal identifiers; another organization
cannot address a bucket through the management API, an S3 credential, or a
Worker binding.

## Browse and manage a bucket

Select a bucket in the organization Storage page to open its object browser.
The browser treats `/`-delimited keys as virtual folders, provides prefix
breadcrumbs, and keeps the active prefix, filter, page, and current-versus-
versions view in the URL. An object detail page shows its size, content type,
last-modified time, ETag, version ID, and custom metadata. Read/write members
can upload, copy, download, and delete objects; observers can browse and
download them.

Bucket settings expose Barbara's full safety model:

* versioning can be enabled to retain immutable object versions and delete
  markers;
* current objects, older versions, delete markers, unfinished multipart
  uploads, and retained bytes are counted separately;
* an exact version or delete marker can be downloaded or permanently removed;
* emptying requires the bucket name and a freshly reviewed contents revision,
  so a concurrent write invalidates the confirmation;
* deleting a bucket remains disabled until every current object, retained
  version, delete marker, and unfinished upload has been removed.

![Organization storage browser and S3 endpoint](/media/screenshots/storage-browser.png)

Browser uploads currently share the control API's 128 MiB request limit. Use
the S3 endpoint and multipart uploads for larger objects or resumable transfer.

## Bind a bucket to a Worker

Declare the binding exactly where a Cloudflare Worker project normally does:

```json
{
  "r2_buckets": [
    {"binding": "MEDIA", "bucket_name": "media-assets"}
  ]
}
```

Deploy with Wrangler. The control plane verifies that the bucket exists in the
same organization before accepting the version. At invocation time, the
trusted runtime dispatcher injects a bucket-scoped capability as `env.MEDIA`.
It does not inject an S3 key or the storage service token.

The current adapter implements the common `get`, `head`, `put`, `delete`, and
`list` operations, including streaming reads and byte ranges. Multipart R2
binding methods and the full Cloudflare R2 conditional/metadata surface are
not yet implemented. The external S3 interface retains Barbara's broader
multipart, versioning, checksum, and range support.

The example in `examples/r2-media/` writes through `env.MEDIA`, then streams
the stored object back. The same pattern can serve audio, video, downloads, or
static site assets without buffering reads in Worker code.

## Use the S3 endpoint

Create an S3 access key from the Storage page. The secret is displayed only
once. Each key is read-only or read/write and may be restricted to named
buckets.

Copy **S3 endpoint** from your organization's Storage page. Use that complete
URL; it already includes the correct scheme and organization namespace.

```sh
export S3_ENDPOINT='<endpoint-copied-from-storage>'
export AWS_ACCESS_KEY_ID='<your-access-key-id>'
export AWS_SECRET_ACCESS_KEY='<your-secret-access-key>'
export AWS_DEFAULT_REGION=us-east-1
aws --endpoint-url "$S3_ENDPOINT" s3 ls
```

Requests use AWS Signature Version 4. The signed host must match the
credential's organization namespace. Revoking a key takes effect on its next
request.

## Persistence and limits

Objects and metadata persist on the storage service host across Worker
deployments and service restarts. The service does not replicate objects or
provide automatic recovery from loss of that host's disk. Keep independent
copies of important data.

The Free tier includes 512 MiB of retained object data, Standard includes 2 GiB,
and Enterprise includes 8 GiB before support overrides. Old versions and delete
markers affect bucket cleanup; inspect the bucket's usage before purging.
See [Usage and quotas](/build/usage-and-limits/) for allowance and enforcement behavior.

Source: https://ermahgerd-docs.t-bd7662a5eeb4.workers.ermahgerd.io/build/storage/index.mdx