Skip to main content
An existing S3 bucket becomes a folder tree, with one file per object.

Setup

The S3 VFS needs an AWS access key pair that can read the bucket, and write to it for a write mount.
  1. Open the IAM console, then Users > Create user.
  2. Attach AmazonS3ReadOnlyAccess, or AmazonS3FullAccess for writes. A policy that grants s3:ListBucket, s3:GetObject, s3:PutObject and s3:DeleteObject on the one bucket is narrower.
  3. Open the user, then Security credentials > Create access key > Application running outside AWS.
  4. Copy the Access key ID and Secret access key. AWS shows the secret only once.
  • With ~/.aws/credentials set up, give aws_profile (profile in TypeScript) instead of the key pair. With no credentials at all, the AWS credential chain applies.
  • A browser mount can fetch presigned URLs from a backend instead of holding keys; see the TypeScript S3 guide.

Connect

workspace.yaml

Layout

  • Each object key is a file path; folders are key prefixes, and the bucket holds no directory objects.
  • key_prefix (keyPrefix in TypeScript) scopes every operation to one subpath of the bucket, such as users/42/. Leading slashes are dropped and a trailing / is added; unset or empty means no prefix.
  • grep -r, find and du stop after 1000 files; a glob matching more, tar -c, cp -r and rm -r are refused.

Sample runs

On a write mount, redirects, cp, mv and rm change objects in the bucket. Set default_content_type (defaultContentType in TypeScript) to stamp every upload with one content type. Unset, S3 picks its own default, and the browser’s presigned PUT sends application/octet-stream.

S3-compatible VFSes

How write: conditional behaves depends on where the bucket is:
  • AWS S3, and the VFSes built on it (R2, GCS, Wasabi and the rest): writes, copies and deletes all carry the condition. A provider that ignores the condition on a copy or a delete runs it unconditioned.
  • MinIO, and the s3 VFS pointed at a non-AWS endpoint: only writes carry it. Mirage refuses anything that would copy or delete within the mount (cp, mv, rm, find -delete) with ENOTSUP.
  • A TypeScript browser mount signed by presigned URLs: cannot declare write: conditional.
See read and write behavior for what a conditional write does.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.