Skip to content

Buckets

If your app declares storage.buckets in appmecca.yaml, AppMecca provisions a private object-storage bucket per name on deploy and injects an app-scoped credential into your containers. The mecca bucket commands let you inspect those buckets and manage the credential.

Buckets speak the S3 API, so any S3-compatible client library works unchanged — boto3, @aws-sdk/client-s3, minio, and so on. AppMecca injects the credential your client needs; see Configuration: Storage for the exact variable names.

Declaring buckets

See Configuration: Storage for how to declare buckets and which environment variables are injected.

Listing Buckets

To see a branch's buckets, access key id and IAM user (never the secret):

mecca bucket list myapp -b dev

NAME     BUCKET                      ENV VAR
media    appmecca-dev-3f2a...c91e    APPMECCA_BUCKET_MEDIA_NAME
exports  appmecca-dev-7b8d...04af    APPMECCA_BUCKET_EXPORTS_NAME

  Branch             dev
  Region             <your environment's region>
  IAM user           appmecca-dev-tb-...
  Access key ID      AKIA...EXAMPLE
  Secret             not yet revealed

The NAME column is the logical name you declared; BUCKET is the real bucket AppMecca created for it, and ENV VAR is the variable your containers receive it in. Your code never hardcodes the physical name — read it from that variable.

If nothing is provisioned yet, declare storage.buckets in appmecca.yaml and deploy.

Buckets are per-branch

Each branch of your app gets its own set of buckets. A file written by the dev branch is not visible to main, and vice versa. Omit -b/--branch and the command resolves your production branch.

Revealing the Secret Key

The secret access key is shown once. Reveal it to copy it into a password manager or a local .env; after that, mecca bucket list reports it as already revealed and you must rotate to see a new one.

mecca bucket reveal myapp

You're prompted to type the app name back. Your containers already have the credential injected automatically — you only need reveal if you want the secret for use outside the app (local development, a script, another tool).

Rotating the Key

To mint a fresh key for one branch — for example after revealing the secret:

mecca bucket rotate-key myapp -b dev

Rotation acts on that branch's credential only; no other branch's key changes. The output names the branch, its IAM user and its buckets, so you can confirm it acted on the one you meant. It requires the app name typed back.

What happens to the old key

Rotation mints a new key and makes it the one reveal and future deploys use. It does not revoke the current key: the old key stays active and keeps working. The old key is only removed when the branch is rotated again, so do not rotate twice in quick succession — the second rotation can remove the key your containers are still using.

The redeploy is automatic

After rotating, AppMecca queues a redeploy of that branch — of the release it is already running, not of your latest build — so your containers pick up the new key. Until it finishes they keep using the old key, which still works, so there is no gap.

If the branch has nothing running there is nothing to update, so no redeploy is queued. mecca queue status <action-id> reports which of those happened.

Every command accepts -b/--branch. Omit it to act on the app's production branch; name a branch that does not exist and the command is refused rather than falling back to production. Every command also accepts the global --json flag.

Browsing and Transferring Files

Buckets have the same file surface drives do — browse, upload, download, delete, and download the whole bucket as one archive:

mecca bucket ls myapp media                    # one prefix level
mecca bucket ls myapp media photos/ -r         # everything beneath a prefix
mecca bucket stat myapp media photos/beach.jpg

mecca bucket upload myapp media ./photo.jpg                    # key = photo.jpg
mecca bucket upload myapp media ./photo.jpg photos/2026/p.jpg  # explicit key
mecca bucket download myapp media photos/beach.jpg -o ./beach.jpg

mecca bucket mkdir myapp media photos/2027
mecca bucket rm myapp media photos/old.jpg
mecca bucket rm myapp media photos/2025/ -r    # a whole prefix
mecca bucket purge myapp media                 # empty it; the bucket survives

mecca bucket archive myapp media -o ./media.tar.gz

The same surface is in the dashboard under the app's Buckets tab.

Uploads go straight to S3 — they never pass through AppMecca

upload asks the platform for a short-lived presigned policy and then sends the file directly to S3. The bytes never touch the API or the agent, so a large upload costs the platform nothing and is limited only by your own connection. The same is true of download.

rm and purge ask you to type the bucket name back

Both are destructive and irreversible — there is no bucket versioning and no recycle bin, so the typed name is the only thing between a wrong window and a deleted object. It is checked server-side; the prompt is a courtesy, not the gate.

How this differs from a drive

The verbs match, but S3 is not a filesystem and the surface does not pretend otherwise:

Drives Buckets
mv / cp yes no — S3 has no server-side rename; a "directory" move is a copy-then-delete loop with no atomicity. Use aws s3 mv with your own credential if you need it.
Folders real directories prefixes. mkdir writes the zero-byte marker the AWS console uses, so an empty folder survives a reload.
Quota enforced against size_gb none — buckets carry no declared size.
Upload path via platform transit storage direct to S3.

Bulk archive

mecca bucket archive (and mecca drive archive) stream the whole store into a single .tar.gz and hand back a short-lived download link. The archive is staged in transit storage and expires within a day — download it when the command gives you the URL.

There is a size ceiling (50 GiB / 250,000 objects). Over it, the command refuses and tells you the measured size rather than running unbounded. Archive a narrower prefix with --prefix, or use the AWS CLI with your own credential.

If another process deletes an object while the archive is running, that object is skipped and reported in the summary — the archive never silently omits something.

Next Steps