miniserve: a single-binary Rust file server and the flag quirks that bite on first use
🌟 For when you really just want to serve some files over HTTP right now!
At a glance
- What is it?
- svenstaro/miniserve serves a file or directory over HTTP from one command. This piece covers its upload flag, auth forms, TLS pairing, header rules and release build, and where each one stops short.
- Who is it for?
- Use miniserve when you need to hand a directory or a single file to another machine in one command and can accept flag-level configuration. Skip it if you expect a persistent file manager with accounts.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- svenstaro/miniserve8,145 ★ · +276
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| svenstaro/miniserve | 7.9k | 8.1k |
276 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The -u flag swallows a path, so uploads need a double dash
Enabling uploads looks trivial and is the first place miniserve surprises people. The short flag -u can itself take a path, or several. If you give it a path, uploading is possible only to those paths instead of to every path. To say "uploads everywhere" and still pass the directory to serve, you separate the two with a double dash:
miniserve -u -- .The consequence is concrete. A bare `miniserve -u .` makes the dot the upload target rather than the served directory, which narrows uploads in a way you did not intend. The same parsing rule also means you cannot bundle short flags once -u is involved. Writing `-uv` fails; you have to write `-u -v`. This affects every shell alias and script that turns on uploads, so test the exact line before you hand the address to anyone else.
There is also a long form, `--upload-files`, which appears in the directory creation example and avoids the short flag altogether.
Uploading and creating folders with curl instead of the browser
Uploads are a plain multipart form post, so any HTTP client can drive them. With the server started as above, the upload command is:
curl -F "path=@$FILE" http://localhost:8080/upload\?path\=/`$FILE` is the local file path, and the example relies on miniserve's default port of 8080. The query string says where in the served tree the file should land. Creating a directory needs a second flag on the server side and a different form field on the client side:
miniserve --upload-files --mkdir .curl -F "mkdir=$DIR_NAME" http://localhost:8080/upload\?path=\/There is a phone workflow too. `miniserve -u -m image -q` uses the `--media-type` option, which sends a hint about the expected media type to the browser. Some mobile browsers, Firefox on Android among them, will offer to open the camera app when they see it. The hint is only a hint, so a browser that ignores it simply shows an ordinary file picker.
Uploaded data is first written to a temporary location set by `--temp-directory`, whose help text advises making sure that directory is on disk and not in memory.
Three ways to supply credentials, and what each one exposes
Basic authentication is built in. The simplest form puts the password on the command line:
miniserve --auth joe:123 unreleased-linux-distros/That is convenient for a throwaway share and poor for anything you leave running, since the secret sits in your shell history in the clear. The second form stores a SHA-256 digest instead. You compute it first and then pass it with the `sha256` marker:
pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
miniserve --auth joe:sha256:$pw unreleased-linux-distros/The `echo -n` matters, because a trailing newline would change the digest and the login would never match. The third form reads logins from a file, one per line:
miniserve --auth-file auth.txt unreleased-linux-distros/Authentication is the only access control the examples show. There is no mention of per-directory permissions, so one set of logins covers everything the process serves. Without TLS, the credentials travel over plain HTTP, which is why the TLS section below matters on anything beyond a trusted LAN.
Custom headers never overwrite, which limits what --header can fix
The `--header` option can be repeated and takes `Name:value` pairs:
miniserve --header "Cache-Control:no-cache" --header "X-Custom-Header:custom-value" -p 8080 /tmp/myshareYou can check the result from a second terminal with `curl -I http://localhost:8080`. The rule that catches people is stated in one line: if a header is already set or previously inserted, it will not be overwritten. So `--header` can add a header miniserve does not send, but it cannot replace one the server already sets, and a repeated name does not replace the earlier value. If a response header looks wrong, passing a corrected copy will not change it, and you will see no error.
Values containing spaces must be wrapped in quotes. That is not cosmetic: the HSTS example below has spaces inside the value, and without the quotes the shell splits the argument and the header is not what you meant.
TLS and HSTS are two separate settings and the A+ grade needs both
HTTPS is switched on by pointing at a certificate and key:
miniserve --tls-cert my.cert --tls-key my.key /tmp/myshareFor a full chain plus HTTP Strict Transport Security, the second command adds the HSTS header through the same `--header` mechanism:
miniserve --tls-cert fullchain.pem --tls-key my.key --header "Strict-Transport-Security: max-age=31536000; includeSubDomains; preload" /tmp/myshareHSTS is therefore not a TLS flag. It is an ordinary header you supply yourself. The note beside the example says that reaching an A+ rating at ssllabs.com requires enabling both fullchain TLS and HSTS, so a certificate alone will not get you there.
TLS is also conditional on how the binary was built. Cargo.toml lists `rustls` and `rustls-pemfile` as optional dependencies, and the feature list says TLS is available "for supported architectures". A build for an architecture outside that set cannot serve HTTPS, and the practical response is to put a reverse proxy in front of it.
Random routes and multiple interfaces for quick, semi-private sharing
Two options handle the case where you share a directory on a network you do not fully control. `--random-route` appends a random six hex digit path to the address, so the share is not at the root:
miniserve -i 192.168.0.1 --random-route /tmpThe example output reads `Serving path /private/tmp at http://192.168.0.1/c789b6`. Anyone who does not know the suffix cannot guess a link from the bare address, though this is obscurity and not authentication, and it should be paired with `--auth` if the contents matter.
Binding is controlled with `-i`, which can be repeated for IPv4 and IPv6 addresses at once:
miniserve -i 192.168.0.1 -i 10.13.37.10 -i ::1 /tmp/myshareThis restricts the listener to the addresses you name instead of every interface. A QR code for quick access from a phone is also in the feature list, and a healthcheck route lives at `/__miniserve_internal/healthcheck`, useful when a container orchestrator needs something to poll.
Browsing without a browser: raw output, filtering and the wget footer
The directory listing has a text-only mode. Adding `?raw=true` to any request returns minimal HTML meant for terminal browsers such as lynx or w3m, and it is on by default:
curl http://localhost:8080?raw=trueFiltering is also a query parameter. `?search=<keyword>` shows only files and directories whose name contains the keyword, case insensitively, for example by visiting `http://127.0.0.1:8080/src/?search=file`. It filters names, not contents.
For pulling a whole tree to another machine, the `--show-wget-footer` flag adds a copy-pastable `wget` command at the bottom of every rendered page, written to grab the current directory recursively:
miniserve --show-wget-footer .Folder downloads are compressed on the fly as `.tar.gz` or `.zip`. The tool also renders a README.md in a directory the way GitHub does, supports range requests, and offers WebDAV through the `dav-server` crate.
A size-tuned release build, and install routes that differ per platform
The release profile in Cargo.toml is tuned for a small binary, not for peak speed: `opt-level = 'z'`, `lto = true`, `codegen-units = 1`, `panic = 'abort'` and `strip = true`. The Makefile goes further for its Linux, Windows and Apple targets, running `strip` and then `upx --lzma` on the output. The musl target used for Linux is what makes the single binary drop-in claim practical. Because panics abort, a fault in a request handler ends the process rather than unwinding, so a long-running share should sit under a supervisor.
Install paths vary. On Linux you download `miniserve-linux` from the releases page and run:
chmod +x miniserve-linux
./miniserve-linuxElsewhere there are package managers: `pacman -S miniserve` on Arch Linux, `pkg install miniserve` on Termux, `brew install miniserve` on macOS, and `scoop install miniserve` on Windows. On Windows the direct download is `miniserve-win.exe`. The latest release in the data is v0.35.0, published 2026-04-08, and the most recent push to the repository was 2026-11-02.
Editorial conclusion
Use miniserve when you need to hand a directory or a single file to another machine in one command and can accept flag-level configuration. Skip it if you expect a persistent file manager with accounts. Before relying on it, check the -u argument rule and the header overwrite rule, because both change what a command does without any error.
Frequently asked questions
How to use miniserve?
Run `miniserve` followed by a directory or a file, for example `miniserve linux-distro-collection/` or `miniserve linux-distro.iso`. Options such as --auth, -u, and --tls-cert add logins, uploads and HTTPS. The default port is 8080.
How to install miniserve?
Download the binary for your platform from the releases page (miniserve-linux, miniserve-osx or miniserve-win.exe), or use a package manager such as pacman, pkg, Homebrew or Scoop. Linux and macOS downloads need chmod +x first.
Mini serve vs self serve: which one is miniserve?
miniserve is the Rust CLI tool by svenstaro whose description is "For when you really just want to serve some files over HTTP right now!". It ships as a single cross-platform binary under the MIT license.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/svenstaro-miniserve)Star history chart for your README
[](https://hysenlabs.com/projects/svenstaro-miniserve)Was this useful?