How to Use Hoistbay: The Beginner's Guide (S3 as a Folder, Header Rules, and One-Click CloudFront Invalidation)
CodexFuse Team · 2026-11-03T08:23:54.067Z · 12 min read min read
Learning how to use Hoistbay takes about fifteen minutes, and it replaces the two tools most developers reluctantly use for S3 work: the AWS Console and the command line. If you host a static site, store media files, or deploy front-end builds to Amazon S3, you have probably felt the friction of opening a browser tab, clicking through five screens, and fighting the console's upload form just to push a folder. Hoistbay removes that friction by treating S3 like a regular folder on your computer.
Hoistbay is a free, open-source desktop app for Amazon S3 and CloudFront — in the vendor's own words from the GitHub README, "a free, open-source desktop app for Amazon S3 and CloudFront. Your keys stay in your OS keychain, and the app talks to nobody but AWS." This beginner's guide walks you through the full first-run arc: installing it, connecting your first bucket, setting header rules once so you never re-upload a build because of wrong cache headers, and clearing your CloudFront cache in one click. Before you start, it is worth knowing what S3 will cost you as you scale, so bookmark the AWS S3 cost calculator alongside this guide.
What Is Hoistbay, Exactly?
Hoistbay is a free, open source S3 desktop client for macOS and Windows that manages Amazon S3 buckets and CloudFront distributions without the AWS Console. In this Hoistbay tutorial you will see the full beginner arc: install, first bucket connection, header rules, and the CloudFront one click invalidation that makes deploys painless. The maker's tagline on the product page sums it up: "Manage S3 and CloudFront Without the AWS Console." It was launched on Product Hunt on October 9, 2026 by individual maker Kartik Shah, is distributed under the MIT license, and the source code is publicly auditable in the mekartikshah/hoistbay repository.
Three design decisions define the app. First, it treats S3 like a folder: buckets open in a familiar file-browser view with breadcrumbs, grid and list views, and drag-and-drop uploads that preserve your folder structure. Second, it automates HTTP headers: you define per-bucket rules by file pattern once, and every upload gets the right Cache-Control and Content-Type values automatically. Third, it keeps CloudFront one click away: your distributions appear next to your buckets, and you can invalidate paths after a deploy without opening the console. Hoistbay is an independent project and is not affiliated with Amazon Web Services.
What Do You Need Before You Start?
You need three things before Hoistbay can talk to your AWS account. First, an AWS account with at least one S3 bucket (a free-tier account works fine for learning). Second, IAM credentials — an access key ID and secret access key for an IAM user or role — because Hoistbay signs requests with Signature V4 like any other S3 client. Third, about ten minutes of quiet time, because the install includes one macOS gatekeeper step you should not rush.
The README publishes a least-privilege IAM policy for the app, which is worth setting up before your first launch so a misclick cannot touch anything outside S3 and CloudFront. The table below maps each permission to what it unlocks inside Hoistbay.
| IAM permission | What it unlocks in Hoistbay |
|---|---|
s3:ListAllMyBuckets | The bucket list on the app's home screen |
s3:GetBucketLocation | Automatic region detection per bucket, so you skip the SignatureDoesNotMatch error |
s3:ListBucket | Browsing and searching inside a bucket, with full pagination past 1,000 objects |
s3:GetObject | Downloading single objects or whole folders |
s3:PutObject | Uploads, including drag-and-drop with folder structure preserved |
s3:DeleteObject | Deleting objects and folders from the browser view |
cloudfront:ListDistributions | Seeing your distributions next to your buckets |
cloudfront:CreateInvalidation | The one-click cache clear after a deploy |
cloudfront:GetInvalidation | Watching the invalidation status until it says "Cache cleared" |
How Do You Install Hoistbay?
Installation is a download, an unzip, and one security acknowledgement — the exact steps differ between macOS and Windows because the app is not yet code-signed on either platform. Hoistbay runs on macOS 12 and later (both Apple Silicon and Intel) and on Windows 10 and 11 (x64); Linux is listed as "Coming soon" in the README download table. You can also build from source with Flutter if you prefer, but the prebuilt zips are the fast path.
- Download the right zip. Grab
Hoistbay-macOS.ziporHoistbay-Windows.zipfrom the GitHub releases page (github.com/mekartikshah/hoistbay). - On macOS, move it to Applications first. The vendor's verbatim steps: "Unzip, move Hoistbay to Applications, then right-click the app → Open → Open." The right-click Open matters — a plain double-click is what triggers the blocked dialog.
- On macOS, handle the notarization notice. "Hoistbay isn't notarized by Apple yet, so macOS asks before opening it." If you only see "Move to Trash," go to System Settings → Privacy & Security and click "Open Anyway." You only need to do this once.
- On Windows, run the executable and pass SmartScreen. The vendor's verbatim steps: "Unzip the folder and run
hoistbay.exe. If SmartScreen shows 'Windows protected your PC', click More info → Run anyway." - Launch the app and let it open empty. Nothing is pre-configured; the first-run screen asks for your first AWS profile, which is where the next section picks up. If you have been hunting for a free S3 GUI client Mac users can actually audit — no login, no backend, no onboarding funnel — this empty first-run screen is the design paying off.
How Do You Connect Your First Bucket?
You connect by saving a named profile per AWS account and region — and the moment you paste your keys, they go into your operating system's secure storage, not into the app's files and never to a server. On macOS that means the Keychain; on Windows it means Credential Manager (DPAPI), both reached through flutter_secure_storage, and the keys are only read at the instant the app calls AWS. "Access keys live in the macOS Keychain or Windows Credential Manager. No account, no backend, no telemetry — and the code is open for you to check," says the vendor page.
Save one profile per account and region, then switch between them instantly from the profile picker — handy if you keep client work in a separate AWS account from your own projects. Session tokens work too, so temporary credentials from an assumed role are supported. Bucket regions are detected automatically when you open a bucket, which eliminates the classic SignatureDoesNotMatch error that comes from signing against the wrong region. If you live in the terminal, the AWS CLI cheat sheet is a good companion reference for the days you need the CLI anyway; Hoistbay covers the everyday visual work.
How Do Header Rules Save You Re-Uploads?
Header rules are the feature that pays for the app's existence: you set per-bucket rules by file pattern once, and Hoistbay applies the right HTTP headers to every upload automatically from then on. The vendor's own example is the whole pitch in one line: "Set per-bucket rules once — *.js and *.css get Cache-Control: max-age=31536000, *.html gets no-cache — and Hoistbay applies them to every upload automatically. No more re-uploading a build because the headers were wrong."
The pattern syntax is glob-style, matching what you already know from .gitignore and bundler configs: *.js, *.css, *.html. Each rule pairs a pattern with a header and a value, and Hoistbay evaluates them on upload. The table below is the starter set the guide recommends for a static site build — copy it into your first bucket's rule list and you will never hand-edit a Cache-Control header again.
| Pattern | Header | Value | Why |
|---|---|---|---|
*.js | Cache-Control | max-age=31536000, immutable | Bundled JS is content-hashed, so a year of caching is safe |
*.css | Cache-Control | max-age=31536000, immutable | Same logic as JS for hashed stylesheets |
*.html | Cache-Control | no-cache | Entry pages must revalidate so visitors get the new build |
*.png, *.jpg, *.webp, *.svg | Cache-Control | max-age=604800 | A week of caching for images that rarely change name |
*.woff2 | Cache-Control | max-age=31536000, immutable | Fonts are versioned by filename; cache them hard |
If a header was wrong on an old upload, you do not need to re-upload: Hoistbay can fix Content-Type, Content-Encoding, or x-amz-meta-* values in place on existing objects. When you are deploying a static build — for example a site assembled with a Keystatic beginner guide workflow — the header rules fire on every deploy automatically, which is the difference between a one-step deploy and a deploy plus an afternoon of header surgery.
How Do You Upload and Download Like a Normal Folder?
You drag files or folders onto the bucket window and Hoistbay uploads them with the folder structure preserved — that is the entire interaction. There is no "create folder, navigate in, upload files, navigate out" loop like the console forces on you; nested directories from your local machine become nested prefixes in S3 automatically. Uploads auto-retry up to three times, and failures are reported per object rather than aborting the whole batch, so one flaky file does not sink a 500-file deploy.
Downloads work the same way in reverse: "Download single objects or whole folders," says the vendor page. Select a folder, hit download, and the full tree lands on your disk with its structure intact. Browsing supports search with breadcrumbs and full pagination past 1,000 objects, so even a bucket with tens of thousands of files stays navigable — a real improvement over the console's paginated, click-heavy navigation.
How Do You Clear the CloudFront Cache in One Click?
After a deploy, you open the distribution sitting next to your bucket, type the paths to invalidate — /* for everything or specific paths like /assets/* — and submit; Hoistbay creates the invalidation and shows its progress until it completes. This is the Hoistbay CloudFront workflow end to end, and CloudFront one click invalidation is exactly what it sounds like: one action, no console navigation, no waiting blindly. The vendor's description of the flow: "See your distributions next to your buckets, invalidate /* or specific paths after a deploy, and watch the invalidation until it says 'Cache cleared'."
Why this matters: CloudFront caches your files at edge locations worldwide, so a fresh upload to S3 is invisible to visitors until the old cached copy expires or is invalidated. If you are unsure how that caching layer works, the CDN explainer walks through what a CDN is and how it sits between your visitors and your S3 origin. The practical rule for beginners: invalidate /* after full-site deploys, and invalidate specific paths when you only changed a handful of files — full invalidations are the simplest thing to get right on day one.
What Trips Up Beginners on Day One?
Every one of these mistakes comes from habits the AWS Console teaches you — Hoistbay's folder metaphor makes some console habits actively harmful. The table below lists the five most common first-day mistakes and the fix for each.
| Mistake | What happens | Fix |
|---|---|---|
| Skipping the right-click Open on macOS | macOS shows only "Move to Trash" and the install feels broken | Right-click → Open → Open, or System Settings → Privacy & Security → "Open Anyway" — once only |
| Using your root account's access keys | A leaked key compromises your entire AWS account | Create an IAM user with the least-privilege policy from the table above and use those keys |
| Forgetting to set header rules before the first deploy | HTML files cache for a year and visitors see a stale site | Set the *.html → no-cache rule before your first upload, not after |
Invalidating only /index.html after a redesign | CSS and JS stay cached at the edge; the new page loads with old styles | Invalidate /* on full-site deploys until you can reason about exactly what changed |
| Uploading the build folder itself instead of its contents | Your site lives at /dist/index.html instead of /index.html | Open the build folder locally first, select its contents, and drag those — not the folder |
Sources
The facts in this guide were verified against the following sources on November 3, 2026:
- hoistbay.app — the vendor's product page: definition, platforms, header-rule examples, install steps for macOS and Windows, multi-account switching, one-click invalidation flow, keychain/DPAPI storage, and the no-backend/no-telemetry claim.
- github.com/mekartikshah/hoistbay — the open-source repository: MIT license state, Flutter desktop stack, least-privilege IAM permission list, auto-retry and pagination behavior, release history including the S3 Scout rename, 24 stars as of November 3, 2026.
- producthunt.com/products/hoistbay — the launch page: published October 9, 2026 (updated November 2), free pricing, macOS and Windows support, and the "keys stay in your OS keychain, no backend, no telemetry" trust claim.
- The maker's launch discussion on Product Hunt — Kartik Shah's own description of the folder-style S3 workflow.
- voyagecontrol.com/hoyst — checked to confirm that "Hoyst," Voyage Control's construction-hoist management software that turns phones into call stations on construction sites, is a completely different product from Hoistbay.
Frequently Asked Questions
Is Hoistbay really free?
Yes. The Product Hunt listing prices it at 0 USD, there is no paid tier documented anywhere, and the only monetization visible is a buy-me-a-coffee tip link in the README. The app is also MIT-licensed open source, so the code is free to inspect and fork.
Is Hoistbay safe to give my AWS keys to?
It is designed around that exact concern: keys are stored in your OS keychain (macOS) or Credential Manager (Windows), encrypted at rest, and are only read when the app calls AWS. There is no account system, no backend server, and no telemetry — Hoistbay calls the official AWS regional endpoints over HTTPS using the aws_s3_api SDK and nothing else. Use the least-privilege IAM policy from this guide to limit what those keys can do.
Does Hoistbay work on Linux?
Not yet. The README download table lists Linux as "Coming soon"; the supported platforms today are macOS 12+ (Apple Silicon and Intel) and Windows 10/11 (x64). Because the source is open, you can build it yourself with Flutter, but there are no official Linux binaries as of November 3, 2026.
How is Hoistbay different from the AWS Console?
The console treats S3 as a website you click through; Hoistbay treats it as a folder you work in. The practical differences are drag-and-drop uploads that preserve folder structure, header rules applied automatically on every upload, whole-folder downloads, and one-click CloudFront invalidation — plus instant switching between AWS accounts without re-entering keys.
Is Hoistbay made by Amazon?
No. It is an independent open-source project by maker Kartik Shah, and the repository carries an explicit trademark disclaimer that it is not affiliated with Amazon Web Services. The app was previously named "S3 Scout" before being renamed to Hoistbay in the v1.1.1 release.
