SupabaseVFS mounts one Supabase Storage bucket: every object becomes a file
and every / in a key a folder. It reaches Supabase through the Storage S3 API.
Set up credentials as in Supabase setup.
Install
Configure
project_ref builds the endpoint
https://<project_ref>.storage.supabase.co/storage/v1/s3; endpoint_url
replaces it. region is required to sign requests: use the one on the project’s
Storage settings page. A mount takes MountMode.READ, WRITE or EXEC.
Fields
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
Provider region every request is signed for. Most providers also build their endpoint URL from it unless
endpoint_url is set.Named profile in the shared AWS config and credentials files that supplies credentials when no access key pair is given.
Address the bucket in the URL path (
<endpoint>/<bucket>/<key>) instead of as a subdomain of the endpoint.Key prefix inside the bucket that the mount treats as its root; keys outside it are not visible. Leading slashes are dropped and a trailing
/ is added.Supabase project reference. It builds the endpoint
https://<project_ref>.storage.supabase.co/storage/v1/s3 unless endpoint_url is set; one of the two is required.Authentication
Credentials come from the first of:access_key_idandsecret_access_key, a Storage S3 access key, withsession_tokenfor temporary credentials.aws_profile, a profile in~/.aws/credentials.- The AWS credential chain: environment variables, then the instance or container role.
anon or service_role key. An S3
access key reaches every bucket in the project and bypasses Row Level Security,
so keep it on a server. A request the credentials may not make answers
Permission denied.
Layout
/supabase/data/file.txt is the key data/file.txt. Folders come from the /
in keys; Supabase stores no folder objects.
Behavior
- Key prefix:
key_prefix="users/42/"mounts only that part of the bucket, so/supabase/notes.mdis the keyusers/42/notes.md. - Path style: Supabase takes only path-style URLs, so
path_styledefaults toTrue.
Integration
Supabase answers these commands through its own API, so fewer objects are read. See Integration.find: one recursive listing.du: one recursive listing.ls -Randtree: one recursive listing.
VFS.md
The VFS.md an agent reads with Supabase mounted at/<path>. <mode> is the mount’s mode: read, write or exec. The commands
shown are those of a write mount.
- Rendered
- Raw
Virtual Filesystem
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.