rejetto/hfs: a web file server that shares folders without a cloud upload

The problem HFS 3 solves, and the people it fits

Sending someone a 4 GB folder usually means uploading it somewhere first, waiting, and hoping the recipient's link has not expired. HFS takes the opposite route. You run it on the machine that already holds the files, and it serves them over HTTP straight from disk. The README's own framing is "Turn your computer into a file-sharing server in seconds", and the two claims behind that are unlimited space and bandwidth because there is no cloud upload, plus instant ZIP downloads even for huge folders.

The audience is narrow and specific. It is a person or a small team with a machine that is on when the files are needed: a home NAS, a workstation, a small VPS. It is not a CDN and it is not a document management system. The README lists Windows, Linux, macOS, FreeBSD and Android as supported platforms, and notes that the minimum Windows version is 10 or Server 2019. If you are sharing to a handful of people and you already own the storage, HFS removes an entire upload step from the workflow. If you are publishing to the open internet at scale, the machine's uplink is now your ceiling, and that is a design consequence, not a bug.

How the virtual file system and the admin panel fit together

The core abstraction is the virtual file system. HFS does not simply mirror a directory tree onto a URL path. It maintains its own mapping between what visitors see and what exists on disk, which is why the README can promise that you can share a single file as easily as a folder, and why "show some files" is a supported pattern. The config file reflects this: the Docker entrypoint writes a `vfs:` block with a `source` key pointing at `/shares`, so the served tree is declared in configuration rather than inferred from the filesystem.

Around that sits an administration web page. The README describes the flow plainly: run HFS, an administration webpage automatically shows up, you select which files and folders are accessible, and then other devices reach them through a browser. Configuration lives in `config.yaml`, documented in config.md, and the admin panel edits the same state. That means the panel is not a thin wrapper you can ignore; it is the primary interface, and the YAML file is the escape hatch for when you cannot reach it.

There is a security default worth knowing about. By default HFS does not require a login when you access the Admin-panel from localhost. The README offers the console command `config localhost_admin false` if you dislike that. On a single-user desktop this is convenient. On a shared machine, or one where anything else can reach localhost, it is a hole you should close deliberately rather than discover later.

Installing HFS 3 and serving your first folder

The primary path is a prebuilt binary. Download the zip for your operating system from the GitHub releases page, unzip it, and launch the `hfs` file. The browser should open at localhost automatically, and you configure the rest in the admin panel. On macOS, the README warns that Gatekeeper may report the binary as being from an unidentified developer, and suggests holding the control key while clicking, then choosing open.

If no browser can be opened on that machine, HFS accepts a command typed into its own running console, not into an OS shell. This creates the admin account:

create-admin <PASSWORD>

After that you log in as `admin` with the password you chose. If you cannot reach the console at all, for example when HFS runs as a service, the README gives a one-liner that writes the config file directly:

echo "create-admin: PASSWORD" > config.yaml

Homebrew users have a shorter route:

brew install rejetto/hfs/hfs

For platforms without a published binary, HFS runs on Node.js. The README specifies version 18 to 24, and the command is `npx hfs@latest`. The README notes that configuration and other files then live in `%HOME%/.vfs`, and that failures at this step usually mean a missing node-gyp build requirement. Docker is documented separately in the project wiki rather than in the README, with `HFS_INITIAL_ADMIN_PASSWORD` used only when `config.yaml` is first created.

Where HFS 3 gets in your way

The localhost admin exemption is the first thing to audit. The README states the default and gives the switch, but it does not present it as a risk, and a reader skimming the install steps will not notice that anyone who can reach the loopback interface of that host gets an unauthenticated admin panel.

The second constraint is that HFS is a process you host, not a service someone else operates. Uptime, TLS certificate renewal, dynamic DNS, and the machine staying awake are yours. The README lists a dynamic-dns updater and easy certificate generation as features, which confirms the expectation that you are running this on a connection that changes address. That is fine for a home setup and awkward for anything with an availability target.

The third is the update mechanism. HFS fetches updated information from GitHub by default, and the README provides `--no-central` to skip that and use built-in data only, plus `DISABLE_UPDATE=1` for containers. If your environment forbids outbound calls from a file server, you need to know about those flags before deployment, not after. The README also documents a right-click on "check for updates" to enter a URL of a version to install, which is a manual escape hatch rather than a managed upgrade path.

Finally, the documentation is split. The README covers installation and a list of features, but configuration details, Docker, service installation, reverse-proxy setup and customization all live in the wiki or in separate files such as config.md and dev-plugins.md. Expect to move between several documents before a non-trivial deployment is settled.

HFS 3 against a plain web server such as nginx

The honest comparison is nginx with `autoindex` or a directory served over HTTP. nginx is faster to configure if all you want is a static tree, it is already installed on most servers, and it does not add a second process to supervise. HFS differs in that the served tree is virtual and editable at runtime through a web interface, accounts are a first-class concept rather than an htpasswd file, and folder downloads arrive as a ZIP stream without you writing any code.

That difference cuts both ways. With nginx you describe the exposure in a text file that goes through your normal review process. With HFS the exposure can change from a browser session, which is convenient for a home user and uncomfortable for anyone who expects infrastructure changes to be reviewed. The README also lists a plugin system with anti-brute-force, thumbnails, LDAP and themes, so the extension surface exists if you need authentication against a directory service. If your requirement is "serve this directory read-only and nothing else", nginx is less machinery for the same result.

Licence, upgrades and what maintenance actually costs

HFS is GPL-3.0, and the repository ships LICENSE.txt at the top level. The practical consequence is that if you distribute a modified HFS, the GPL's source-availability terms attach to your distribution. Running it internally to share files is a different situation from shipping it inside a product, and the licence text is the thing to read rather than a summary. This is not legal advice; if redistribution is on the table, that is a question for someone qualified to answer it.

The project is not archived, and the last push was on 2026-09-22, one day before the date of this writing. Releases are frequent: v3.3.0 and v3.3.1 both landed on 2026-09-17, and v3.3.2 followed on 2026-09-20. That cadence is good for fixes and bad for anyone who pins a version and forgets it. The package.json version at the time of writing is 3.3.3, ahead of the latest published release, which is normal for a repository between tag and release.

Upgrade cost depends on how you installed it. A binary install means replacing the unzipped files and keeping the configuration and data directory, which the README points to config.md to locate. A Node install via `npx hfs@latest` tracks the latest version every time it starts. A Docker install is pinned by the `HFS_VERSION` build argument in the Dockerfile, so upgrades happen when you rebuild the image, and the entrypoint sets `DISABLE_UPDATE=1` so the container does not try to update itself underneath you. Pick the install method that matches how much you want to think about upgrades.

Editorial conclusion

Adopt HFS if you need to expose folders from a machine you control, and you want a browser-based admin panel rather than a hand-written nginx config. Do not adopt it if you need multi-tenant isolation, an audit trail, or a service you never touch again: the admin panel is the product, and someone has to mind it. Before rolling it out, verify three things on your own machine: that the config directory location matches what config.md says for your platform, that the port you intend to use is free, and that the account model you configured actually blocks anonymous listing. The GPL-3.0 licence is the other thing to settle early, because it constrains what you can do with a modified HFS if you redistribute it.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. rejetto/hfs on GitHub
5. Releases