How Firepipe maps virtual folders to your bucket

When a partner connects to Firepipe over SFTP, they see an ordinary folder tree: directories, files, the usual cd and ls. Underneath, there are no folders at all, just objects in your cloud bucket with slash-containing keys. Here’s exactly how Firepipe bridges the two, and what that means in practice.

Paths are key prefixes

Cloud object storage is a flat keyspace. An object isn’t “in a folder”; it just has a key like clients/acme/2026/report.csv. Firepipe presents the parts between slashes as a folder hierarchy:

• The SFTP path /clients/acme/2026/report.csv maps to the object key clients/acme/2026/report.csv in your bucket.
• Listing /clients/acme becomes a prefix listing of clients/acme/ with / as a delimiter, returning 2026/ as a sub-folder and any files directly under it.
• Uploading streams the bytes into an object at the matching key (multipart for large files); downloading streams the object back.

So the folder tree your partner navigates is a view computed from object keys, not a real directory structure. See how an SFTP proxy works for the general mechanics.

A user’s home directory is a prefix jail

Each Firepipe user is scoped to a prefix, and that prefix is both their home directory and their jail. A user mapped to clients/acme/ lands there on login, sees it as their root, and every operation is checked to ensure the key it touches starts with clients/acme/. Anything outside simply doesn’t exist from their point of view, and can’t be reached. This is how one bucket safely serves many partners: each is boxed into their own prefix. See chroot directories explained.

What this means for everyday operations

• Create a folder: since folders are implied by keys, “creating” one is essentially a no-op until a file is put under it (Firepipe presents it as you’d expect).
• Rename: there’s no atomic rename in object storage, so renaming an object is a server-side copy then delete. The common upload-to-temp-then-rename pattern works; renaming a very large object takes as long as copying it; and renaming a whole directory isn’t supported (you’ll get a clear message rather than a silent partial move).
• Listings: a normal directory lists quickly. A directory with an enormous number of objects is the one case to plan for, see the note below.
• Timestamps and permissions: object storage has no POSIX mode bits or mtime, so chmod and timestamp-preserving flags report success but have no effect.

Big directories and the optional index

Listing a prefix with millions of keys means a large live enumeration of the bucket, which can be slow. Firepipe bounds very large single-directory listings and fails loudly rather than returning a silent partial list, and offers an optional synced index to keep such listings fast. The index is opt-in, not the default. The full, honest behaviour is on the SFTP compatibility & known limitations page, worth reading before you automate against deep or huge folders.

Why it’s done this way

Mapping folders to prefixes is what lets Firepipe give object storage a faithful SFTP interface without changing your bucket, while keeping each user contained to their own slice. Your files stay exactly where they are, as normal objects you can also read with the cloud’s own tools. See SFTP to S3 to set it up.