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.

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.

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:

{
  "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.

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 for allowance and enforcement behavior.