miniserve Documentation

For when you really just want to serve some files over HTTP right now!

7,918 stars Rust Rust 1 file · ~12,999 tokens #cli#command-line#command-line-tool#http-server#serve#server#static-files
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy miniserve on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name miniserve --restart always svenstaro/miniserve:latest

File: README.md

miniserve - a CLI tool to serve files and dirs over HTTP







For when you really just want to serve some files over HTTP right now!

miniserve is a small, self-contained cross-platform CLI tool that allows you to just grab the binary and serve some file(s) via HTTP.
Sometimes this is just a more practical and quick way than doing things properly.

Screenshot

How to use

Serve a directory:

text
miniserve linux-distro-collection/

Serve a single file:

text
miniserve linux-distro.iso

Set a custom index file to serve instead of a file listing:

text
miniserve --index test.html

Serve an SPA (Single Page Application) so that non-existent paths are forwarded to the SPA's router instead

text
miniserve --spa --index index.html

Require username/password:

text
miniserve --auth joe:123 unreleased-linux-distros/

Require username/password as hash:

text
pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
miniserve --auth joe:sha256:$pw unreleased-linux-distros/

Require username/password from file (separate logins with new lines):

text
miniserve --auth-file auth.txt unreleased-linux-distros/

Generate random 6-hexdigit URL:

text
miniserve -i 192.168.0.1 --random-route /tmp
# Serving path /private/tmp at http://192.168.0.1/c789b6

Bind to multiple interfaces:

text
miniserve -i 192.168.0.1 -i 10.13.37.10 -i ::1 /tmp/myshare

Insert custom headers

text
miniserve --header "Cache-Control:no-cache" --header "X-Custom-Header:custom-value" -p 8080 /tmp/myshare
# Check headers in another terminal
curl -I http://localhost:8080

If a header is already set or previously inserted, it will not be overwritten.

Start with TLS:

text
miniserve --tls-cert my.cert --tls-key my.key /tmp/myshare
# Fullchain TLS and HTTP Strict Transport Security (HSTS)
miniserve --tls-cert fullchain.pem --tls-key my.key --header "Strict-Transport-Security: max-age=31536000; includeSubDomains; preload" /tmp/myshare

If the parameter value has spaces, be sure to wrap it in quotes.
(To achieve an A+ rating at https://www.ssllabs.com/ssltest/, enabling both fullchain TLS and HSTS is necessary.)

Upload a file using `curl`:

text
# in one terminal
miniserve -u -- .
# in another terminal
curl -F "path=@$FILE" http://localhost:8080/upload\?path\=/

(where $FILE is the path to the file. This uses miniserve's default port of 8080)

Note that for uploading, we have to use -- to disambiguate the argument to -u.
This is because -u can also take a path (or multiple). If a path argument to -u is given,
uploading will only be possible to the provided paths as opposed to every path.

Another effect of this is that you can't just combine flags like this -uv when -u is used. In
this example, you'd need to use -u -v.

Create a directory using `curl`:

text
# in one terminal
miniserve --upload-files --mkdir .
# in another terminal
curl -F "mkdir=$DIR_NAME" http://localhost:8080/upload\?path=\/

(where $DIR_NAME is the name of the directory. This uses miniserve's default port of 8080.)

Use the raw renderer for use with simple viewers

You can pass ?raw=true with requests where you only require minimal HTML output for CLI-based browsers such as lynx or w3m.
This is enabled by default without any extra flags:

text
miniserve .
curl http://localhost:8080?raw=true

You can enable a convenient copy-pastable footer for wget using --show-wget-footer:

text
miniserve --show-wget-footer .

Afterwards, check the bottom of any rendered page.
It'll have a neat wget command you can easily copy-paste to recursively grab the current directory.

Use query parameter to do a simple filter

You can pass a ?search=<keyword> query parameter to only show files and directories whose name contains the <keyword>, for example:

text
miniserve .
# Then visit http://127.0.0.1:8080/src/?search=file

This filter feature is case insensitive.

Take pictures and upload them from smartphones:

text
miniserve -u -m image -q

This uses the --media-type option, which sends a hint for the expected media type to the browser.
Some mobile browsers like Firefox on Android will offer to open the camera app when seeing this.

Features

  • Easy to use
  • Just works: Correct MIME types handling out of the box
  • Single binary drop-in with no extra dependencies required
  • Authentication support with username and password (and hashed password)
  • Mega fast and highly parallel (thanks to Rust and Actix)
  • Search/filter by file or directory name
  • Folder download (compressed on the fly as .tar.gz or .zip)
  • File uploading
  • Directory creation
  • Pretty themes (with light and dark theme support)
  • Scan QR code for quick access
  • Shell completions
  • Sane and secure defaults
  • TLS (for supported architectures)
  • Supports README.md rendering like on GitHub
  • Range requests
  • WebDAV support
  • Healthcheck route (at /__miniserve_internal/healthcheck)

Usage

text
For when you really just want to serve some files over HTTP right now!

Usage: miniserve [OPTIONS] [PATH]

Arguments:
  [PATH]
          Which path to serve

          [env: MINISERVE_PATH=]

Options:
  -v, --verbose
          Be verbose, includes emitting access logs

          [env: MINISERVE_VERBOSE=]

      --temp-directory <TEMP_UPLOAD_DIRECTORY>
          The path to where file uploads will be written to before being moved to their correct location. It's wise to make sure that this
          directory will be written to disk and not into memory.

          This value will only be used **IF** file uploading is enabled. If this option is not set, the operating system default temporary
          directory will be used.

          [env: MINISERVER_TEMP_UPLOAD_DIRECTORY=]

      --index <INDEX>
          The name of a directory index file to serve, like "index.html"

          Normally, when miniserve serves a directory, it creates a listing for that directory. However, if a directory contains this file,
          miniserve will serve that file instead.

          [env: MINISERVE_INDEX=]

      --spa
          Activate SPA (Single Page Application) mode

          This will cause the file given by --index to be served for all non-existing file paths. In effect, this will serve the index file
          whenever a 404 would otherwise occur in order to allow the SPA router to handle the request instead.

          [env: MINISERVE_SPA=]

      --quiet
          Reduce output and silence warnings

          [env: MINISERVE_QUIET=]

      --pretty-urls
          Activate Pretty URLs mode

          This will cause the server to serve the equivalent `.html` file indicated by the path.

          `/about` will try to find `about.html` and serve it.

          [env: MINISERVE_PRETTY_URLS=]

  -p, --port <PORT>
          Port to use

          [env: MINISERVE_PORT=]
          [default: 8080]

  -i, --interfaces <INTERFACES>
          Interface to listen on

          [env: MINISERVE_INTERFACE=]

      --workers <WORKERS>
          Number of server workers

          [env: MINISERVE_WORKERS=]
          [default: 4]

  -a, --auth <AUTH>
          Set authentication

          Currently supported formats:
          username:password, username:sha256:hash, username:sha512:hash
          (e.g. joe:123, joe:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3)

          [env: MINISERVE_AUTH=]

      --auth-file <AUTH_FILE>
          Read authentication values from a file

          Example file content:

          joe:123
          bob:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
          bill:

          [env: MINISERVE_AUTH_FILE=]

      --route-prefix <ROUTE_PREFIX>
          Use a specific route prefix

          [env: MINISERVE_ROUTE_PREFIX=]

      --random-route
          Generate a random 6-hexdigit route

          [env: MINISERVE_RANDOM_ROUTE=]

  -P, --no-symlinks
          Hide symlinks in listing and prevent them from being followed

          [env: MINISERVE_NO_SYMLINKS=]

  -H, --hidden
          Show hidden files

          [env: MINISERVE_HIDDEN=]

  -S, --default-sorting-method <DEFAULT_SORTING_METHOD>
          Default sorting method for file list

          Possible values:
          - name: Sort by name
          - size: Sort by size
          - date: Sort by last modification date (natural sort: follows alphanumerical order)

          [env: MINISERVE_DEFAULT_SORTING_METHOD=]
          [default: name]

  -O, --default-sorting-order <DEFAULT_SORTING_ORDER>
          Default sorting order for file list

          Possible values:
          - asc:  Ascending order
          - desc: Descending order

          [env: MINISERVE_DEFAULT_SORTING_ORDER=]
          [default: desc]

  -c, --color-scheme <COLOR_SCHEME>
          Default color scheme

          [env: MINISERVE_COLOR_SCHEME=]
          [default: squirrel]
          [possible values: squirrel, archlinux, ayu-dark, zenburn, monokai]

  -d, --color-scheme-dark <COLOR_SCHEME_DARK>
          Default color scheme

          [env: MINISERVE_COLOR_SCHEME_DARK=]
          [default: archlinux]
          [possible values: squirrel, archlinux, ayu-dark, zenburn, monokai]

  -q, --qrcode
          Enable QR code display

          [env: MINISERVE_QRCODE=]

  -u, --upload-files [<ALLOWED_UPLOAD_DIR>]
          Enable file uploading (and optionally specify for which directory)

          The provided path is not a physical file system path. Instead, it's relative to the serve dir. For instance, if the serve dir is
          '/home/hello', set this to '/upload' to allow uploading to '/home/hello/upload'. When specified via environment variable, a path
          always needs to be specified.

          [env: MINISERVE_ALLOWED_UPLOAD_DIR=]

      --web-upload-files-concurrency <WEB_UPLOAD_CONCURRENCY>
          Configure amount of concurrent uploads when visiting the website. Must have upload-files option enabled for this setting to matter.

          For example, a value of 4 would mean that the web browser will only upload 4 files at a time to the web server when using the web
          browser interface.

          When the value is kept at 0, it attempts to resolve all the uploads at once in the web browser.

          NOTE: Web pages have a limit of how many active HTTP connections that they can make at one time, so even though you might set a
          concurrency limit of 100, the browser might only make progress on the max amount of connections it allows the web page to have open.

          [env: MINISERVE_WEB_UPLOAD_CONCURRENCY=]
          [default: 0]

      --chmod <CHMOD>
          Set unix file permissions of uploaded files

          This takes an octal number, for example 0600. By default 0666 & ~umask is used to simulate the system's default behavior.

          [env: MINISERVE_CHMOD=]

      --directory-size
          Enable recursive directory size calculation

          This is disabled by default because it is a potentially fairly IO intensive operation.

          [env: MINISERVE_DIRECTORY_SIZE=]

  -U, --mkdir
          Enable creating directories

          [env: MINISERVE_MKDIR_ENABLED=]

      --pastebin
          Enable creating pastebin 'pastes'

          'pastes' are plaintext files created in the current directory. Creation requires file uploads be enabled.

          [env: MINISERVE_PASTEBIN_ENABLED=]

  -m, --media-type <MEDIA_TYPE>
          Specify uploadable media types

          [env: MINISERVE_MEDIA_TYPE=]
          [possible values: image, audio, video]

  -M, --raw-media-type <MEDIA_TYPE_RAW>
          Directly specify the uploadable media type expression

          [env: MINISERVE_RAW_MEDIA_TYPE=]

  -o, --on-duplicate-files <ON_DUPLICATE_FILES>
          What to do if existing files with same name is present during file upload

          If you enable renaming files, the renaming will occur by adding a numerical suffix to the filename before the final extension. For
          example file.txt will be uploaded as file-1.txt, the number will be increased until an available filename is found.

          [env: MINISERVE_ON_DUPLICATE_FILES=]
          [default: error]
          [possible values: error, overwrite, rename]

  -R, --rm-files [<ALLOWED_RM_DIR>]
          Enable file and directory deletion (and optionally specify for which directory)

          [env: MINISERVE_ALLOWED_RM_DIR=]

  -r, --enable-tar
          Enable uncompressed tar archive generation

          [env: MINISERVE_ENABLE_TAR=]

  -g, --enable-tar-gz
          Enable gz-compressed tar archive generation

          [env: MINISERVE_ENABLE_TAR_GZ=]

  -z, --enable-zip
          Enable zip archive generation

          WARNING: Zipping large directories can result in out-of-memory exception because zip generation is done in memory and cannot be sent
          on the fly

          [env: MINISERVE_ENABLE_ZIP=]

  -C, --compress-response
          Compress response

          WARNING: Enabling this option may slow down transfers due to CPU overhead, so it is disabled by default.

          Only enable this option if you know that your users have slow connections or if you want to minimize your server's bandwidth usage.

          [env: MINISERVE_COMPRESS_RESPONSE=]

  -D, --dirs-first
          List directories first

          [env: MINISERVE_DIRS_FIRST=]

  -t, --title <TITLE>
          Shown instead of host in page title and heading

          [env: MINISERVE_TITLE=]

      --header <HEADER>
          Inserts custom headers into the responses. Specify each header as a 'Header:Value' pair. This parameter can be used multiple times
          to add multiple headers.

          Example: --header "Header1:Value1" --header "Header2:Value2" (If a header is already set or previously inserted, it will not be
          overwritten.)

          [env: MINISERVE_HEADER=]

  -l, --show-symlink-info
          Visualize symlinks in directory listing

          [env: MINISERVE_SHOW_SYMLINK_INFO=]

  -F, --hide-version-footer
          Hide version footer

          [env: MINISERVE_HIDE_VERSION_FOOTER=]

      --hide-theme-selector
          Hide theme selector

          [env: MINISERVE_HIDE_THEME_SELECTOR=]

  -W, --show-wget-footer
          If enabled, display a wget command to recursively download the current directory

          [env: MINISERVE_SHOW_WGET_FOOTER=]

      --print-completions <shell>
          Generate completion file for a shell

          [possible values: bash, elvish, fish, powershell, zsh]

      --print-manpage
          Generate man page

      --tls-cert <TLS_CERT>
          TLS certificate to use

          [env: MINISERVE_TLS_CERT=]

      --tls-key <TLS_KEY>
          TLS private key to use

          [env: MINISERVE_TLS_KEY=]

      --readme
          Enable README.md rendering in directories

          [env: MINISERVE_README=]

  -I, --disable-indexing
          Disable indexing

          This will prevent directory listings from being generated and return an error instead.

          [env: MINISERVE_DISABLE_INDEXING=]

      --enable-webdav
          Enable read-only WebDAV support (PROPFIND requests)

          [env: MINISERVE_ENABLE_WEBDAV=]

      --size-display <SIZE_DISPLAY>
          Show served file size in exact bytes

          [env: MINISERVE_SIZE_DISPLAY=]
          [default: human]
          [possible values: human, exact]

      --file-external-url <FILE_EXTERNAL_URL>
          Optional external URL (e.g., 'http://external.example.com:8081') prepended to file links in listings.

          Allows serving files from a different URL than the browsing instance. Useful for setups like: one authenticated instance for
          browsing, linking files (via this option) to a second, non-indexed (-I) instance for direct downloads. This obscures the full file
          list on the download server, while users can still copy direct file URLs for sharing. The external URL is put verbatim in front of
          the relative location of the file, including the protocol. The user should take care this results in a valid URL, no further checks
          are being done.

          [env: MINISERVE_FILE_EXTERNAL_URL=]

      --log-color <LOG_COLOR>
          Set the color style of the log output

          "auto" (default) enables colors only when the output is a terminal. "always" always enables colors. "never" always disables colors.

          [env: MINISERVE_LOG_COLOR=]
          [default: auto]
          [possible values: auto, always, never]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

How to install

On Linux: Download miniserve-linux from the releases page and run

text
chmod +x miniserve-linux
./miniserve-linux

Alternatively, if you are on Arch Linux, you can do

text
pacman -S miniserve

On Termux

text
pkg install miniserve

On OSX: Download miniserve-osx from the releases page and run

text
chmod +x miniserve-osx
./miniserve-osx

Alternatively install with Homebrew:

text
brew install miniserve
miniserve

On Windows: Download miniserve-win.exe from the releases page and run

text
miniserve-win.exe

Alternatively install with Scoop:

text
scoop install miniserve

With Cargo: Make sure you have a recent version of Rust. Then you can run

text
cargo install --locked miniserve
miniserve

With Docker: Make sure the Docker daemon is running and then run

text
docker run -v /tmp:/tmp -p 8080:8080 --rm -it docker.io/svenstaro/miniserve /tmp

With Podman: Just run

text
podman run -v /tmp:/tmp -p 8080:8080 --rm -it docker.io/svenstaro/miniserve /tmp

With Helm: See this third-party Helm chart by @wrenix.

Shell completions

If you'd like to make use of the built-in shell completion support, you need to run miniserve --print-completions <your-shell> and put the completions in the correct place for your shell. A
few examples with common paths are provided below:

text
# For bash
miniserve --print-completions bash > ~/.local/share/bash-completion/completions/miniserve
# For zsh
miniserve --print-completions zsh > /usr/local/share/zsh/site-functions/_miniserve
# For fish
miniserve --print-completions fish > ~/.config/fish/completions/miniserve.fish

systemd

A hardened systemd-compatible unit file can be found in packaging/[email protected]. You could
install this to /etc/systemd/system/[email protected] and start and enable miniserve as a
daemon on a specific serve path /my/serve/path like this:

text
systemctl enable --now miniserve@-my-serve-path

Keep in mind that you'll have to use systemd-escape to properly escape a path for this usage.

In case you want to customize the particular flags that miniserve launches with, you can use

text
systemctl edit miniserve@-my-serve-path

and set the [Service] part in the resulting override.conf file. For instance:

text
[Service]
ExecStart=
ExecStart=/usr/bin/miniserve --enable-tar --enable-zip --no-symlinks --verbose -i ::1 -p 1234 --title hello --color-scheme monokai --color-scheme-dark monokai -- %I

Make sure to leave the %I at the very end in place or the wrong path might be served.
Alternatively, you can configure the service via environment variables:

text
[Service]
Environment=MINISERVE_ENABLE_TAR=true
Environment=MINISERVE_ENABLE_ZIP=true
Environment="MINISERVE_TITLE=hello world"
...

You might additionally have to override IPAddressAllow and IPAddressDeny if you plan on making
miniserve directly available on a public interface.

Binding behavior

For convenience reasons, miniserve will try to bind on all interfaces by default (if no -i is provided).
It will also do that if explicitly provided with -i 0.0.0.0 or -i ::.
In all of the aforementioned cases, it will bind on both IPv4 and IPv6.
If provided with an explicit non-default interface, it will ONLY bind to that interface.
You can provide -i multiple times to bind to multiple interfaces at the same time.

Why use this over alternatives?

  • darkhttpd: Not easily available on Windows and it's not as easy as download-and-go.
  • Python built-in webserver: Need to have Python installed, it's low performance, and also doesn't do correct MIME type handling in some cases.
  • netcat: Not as convenient to use and sending directories is somewhat involved.

Releasing

This is mostly a note for me on how to release this thing:

  • Make sure CHANGELOG.md is up to date.
  • cargo release <version>
  • cargo release --execute <version>
  • Releases will automatically be deployed by GitHub Actions.
  • Update Arch package.

File: CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog
and this project adheres to Semantic Versioning.

[Unreleased] - ReleaseDate

  • Fix suffix generation for pastes in non-HTTPS env #1562 (thanks @pzhlkj6612)

[0.35.0] - 2026-04-08

  • Add --workers to limit the number of workers and default to 4 #1556

[0.34.0] - 2026-04-07

  • Add Ayu Dark theme #1551 (thanks @rysb-dev)
  • Add simple search/filter feature #1505 (thanks @7sDream)

[0.33.0] - 2026-02-16

  • Add --log-color to explicitly control when to print colors #1529 (thanks @MrCroxx)
  • Fix --rm-files not working with --route-preifx #1531 (thanks @Jianchi-Chen)
  • Add illumos builds #1543
  • Ignore failure on file hash calculation during upload #1542 (thanks @outloudvi)
  • Add --quiet flag to reduce output and silence warnings #1539 (thanks @joshleeb)
  • Enable some markdown rendering extensions #1545 (thanks @duskmoon314)
  • Add --pastebin flag to enable pastebin form #1546 (thanks @rktjmp)
  • Always use forward slashes in zip files #1534 (thanks @pzhlkj6612)

[0.32.0] - 2025-09-17

  • Skip hash calculation when crypto.subtle is not available #1507 (thanks @outloudvi)
  • Fix hostname:port getting repeated in wget footer if TLS is used #1515 (thanks @xtay573269555)
  • Add --chmod to set file mode after upload on unix #1506 (thanks @lilydjwg)
  • Add --rm-files to allow file deletion #1518 (thanks @NOBLESSE and @cyqsimon)

[0.31.0] - 2025-06-27

  • Fix filtering symlinks when hosting WebDAV #1502 (thanks @ahti)
  • Enable renaming during file upload if duplicate exists #1453 (thanks @Atreyagaurav)

[0.30.0] - 2025-06-26

  • Add --file-external-url to generate links pointing to another server #1492 (thanks @jankeymeulen)
  • Add date pill and sort links for mobile views #1473 (thanks @Flat)
  • Add upload progress bar and allow for multiple concurrent file uploads #1431 (thanks @AlecDivito)
  • Add --size-display to allow for toggling file size display between human and exact #1261 (thanks @Lzzzzzt)
  • Add well-known healthcheck route at /__miniserve_internal/healthcheck (of //__miniserve_internal/healthcheck when using --route-prefix)
  • Add asynchronous recursive directory size counting #1482
  • Add link to miniserve GitHub page to footer
  • Add --directory-size flag to enable directory size counting
  • Fix --no-symlinks not filtering files and dirs nested in symlinks #1495 (thanks @ahti)

[0.29.0] - 2025-02-06

  • Make URL encoding fully WHATWG-compliant #1454 (thanks @cyqsimon)
  • Fix OVERWRITE_FILES env var not being prefixed by MINISERVE_ #1457
  • Change font-weight of regular files to be normal to improve readability #1471 (thanks @shaicoleman)
  • Add webdav support #1415 (thanks @ahti)
  • Move favicon and css to stable, non-random routes #1472 (thanks @ahti)

[0.28.0] - 2024-09-12

  • Fix wrapping text in mobile view when the file name too long #1379 (thanks @chaibiq)
  • Fix missing drag-form when dragging file in to browser #1390 (thanks @chaibiq)
  • Improve documentation for the --header parameter #1389 (thanks @orwithout)
  • Don't show mkdir option when the directory is not upload allowed #1442 (thanks @Atreyagaurav)

[0.27.1] - 2024-03-16

  • Add Add file and folder symbols #1365 (thanks @chaibiq)

[0.27.0] - 2024-03-16

  • Add -C/--compress-response to enable response compression 1315 (thanks @zuisong)
  • Refactor errors #1331 (thanks @cyqsimon)
  • Add -I/--disable-inexing #1329 (thanks @dyc3)

[0.26.0] - 2024-01-13

  • Properly handle read-only errors on Windows #1310 (thanks @ViRb3)
  • Use tokio::fs instead of std::fs to enable async file operations #445
  • Add -S/--default-sorting-method and -O/--default-sorting-order flags #1308 (thanks @ElliottLandsborough)

[0.25.0] - 2024-01-07

  • Add --pretty-urls #1193 (thanks @nlopes)
  • Fix single quote display with --show-wget-footer #1191 (thanks @d-air1)
  • Remove header Content-Encoding when archiving #1290 (thanks @5long)
  • Prevent illegal request path from crashing program #1285 (thanks @cyqsimon)
  • Fixed issue where serving files with a newline would fail #1294

[0.24.0] - 2023-07-06

  • Fix ANSI color codes are printed when not a tty #1095
  • Allow parameters to be provided via environment variables #1160

[0.23.2] - 2023-04-28

  • Build Windows build with static CRT #1107

[0.23.1] - 2023-04-17

  • Add EC key support #1080

[0.23.0] - 2023-03-01

  • Update to clap v4
  • Show localized datetime #949 (thanks @IvkinStanislav)
  • Fix sorting breaks subdir downloading #991 (thanks @Vam-Jam)
  • Fix wget footer #1043 (thanks @Yusuto)

[0.22.0] - 2022-09-20

  • Faster QR code generation #848 (thanks @cyqsimon)
  • Make --readme support not only README.md but also README and README.txt rendered as
    plaintext #911 (thanks @Atreyagaurav)
  • Change -u/--upload-files slightly in the sense that it can now either be provided by itself as
    before or receive a file path to restrict uploading to only that path. Can be provided multiple
    times for multiple allowed paths #858 (thanks
    @jonasdiemer)

[0.21.0] - 2022-09-15

  • Fix bug where static files would be served incorrectly when using --random-route #835 (thanks @solarknight)
  • Add --readme to render the README in the current directory after the file listing #860 (thanks @Atreyagaurav)
  • Add more architectures (and also additional container images)

[0.20.0] - 2022-06-26

  • Fixed security issue where it was possible to upload files to locations pointed to by symlinks
    even when symlinks were disabled #781 (thanks @sheepy0125)
  • Added --hide-theme-selector flag to hide the theme selector functionality in the frontend #805 (thanks @flamingoodev)
  • Added --mkdir flag to allow for uploading directories #781 (thanks @sheepy0125)

[0.19.5] - 2022-05-18

  • Fix security issue where --no-symlinks would only hide symlinks from listing but it would
    still be possible to follow them if the path was known

[0.19.4] - 2022-04-02

  • Fix random route leaking on error pages #764 (thanks @steffhip)

[0.19.3] - 2022-03-15

  • Allow to set the accept input attribute to arbitrary values using -m and -M #755 (thanks @mayjs)

[0.19.2] - 2022-02-21

  • Add man page support via --print-manpage #738

[0.19.1] - 2022-02-16

  • Better MIME type guessing support due to updated mime_guess

[0.19.0] - 2022-02-06

  • Fix panic when using TLS in some instances #670 (thanks @aliemjay)
  • Add --route-prefix to add a fixed route prefix #728 (thanks @aliemjay and @Jikstra)
  • Allow tapping the whole row in mobile view #729

[0.18.0] - 2021-10-26

  • Add raw mode and raw mode footer display #508 (thanks @Jikstra)
  • Add SPA mode #515 (thanks @sinking-point)

[0.17.0] - 2021-09-04

  • Print QR codes on terminal #524 (thanks @aliemjay)
  • Fix mobile layout info pills taking whole width #591
  • Fix security exploit when uploading is enabled #590 #518 (thanks @aliemjay)
  • Fix uploading to symlink directories #590 #466 (thanks @aliemjay)

[0.16.0] - 2021-08-31

  • Fix serving files with backslashes in their names #578 (thanks @Jikstra)

  • Fix behavior of downloading symlinks by upgrading to actix-web 4 #582 #462 (thanks @aliemjay)

  • List directory if index file not found #583 #275 (thanks @aliemjay)

  • Add special colors for visited links #521 (thanks @raffomania)

  • Switch from structopt to clap v3 #587

    This enables slightly nicer help output as well as much better completions.

  • Fix network interface handling #500 #470 #405 #422 (thanks @aliemjay)

  • Implement show symlink destination #542 #499 (thanks @deantvv)

  • Fix error page not being correctly themed #529 #588 (@aliemjay)

[0.15.0] - 2021-08-27

  • Add hardened systemd template unit file to packaging/[email protected]
  • Fix qrcodegen dependency problem #568
  • Remove animation on QR code hover (it was kind of annoying as it makes things less snappy)
  • Add TLS support #576

[0.14.0] - 2021-04-18

  • Fix breadcrumbs for right-to-left languages #489 (thanks @aliemjay)
  • Fix URL percent encoding for special characters #485 (thanks @aliemjay)
  • Wrap breadcrumbs at any char #496 (thanks @aliemjay)
  • Add separate flags for compressed and uncompressed tar archives #492 (thanks @deantvv)
  • Bump deps
  • Fix Firefox becoming confused when opening a .gz file directly #160
  • Prefer UTF8 for text responses #263
  • Resolve symlinks on directory listing #479 (thanks @aliemjay)

[0.13.0] - 2021-03-28

  • Change default log level to Warn

  • Change some messages a bit to be more clear

  • Add --print-completions to print shell completions for various supported shells #482 (thanks @rouge8)

  • Don't print some messages if not attached to an interactive terminal

  • Refuse to start if not attached to interactive terminal and no explicit path is provided

    This is a security consideration as you wouldn't want to run miniserve without an explicit path
    as a service. You could end up serving / or /root in case those working directories are set.

[0.12.1] - 2021-03-27

  • Fix QR code not showing when using both --random-route and --qrcode #480 (thanks @rouge8)
  • Add FreeBSD binaries

[0.12.0] - 2021-03-20

  • Add option -H/--hidden to show hidden files
  • Start instantly in case an explicit index is chosen
  • Fix DoS issue when deliberately sending unconforming URL paths
  • Add footer #456 (thanks @levaitamas)
  • Switched from failure to thiserror for error handling

[0.11.0] - 2021-02-28

  • Add binaries for more architectures
  • Upgrade lockfile which fixes some security issues
  • Allow multiple file upload #434 (thanks @mhuesch)
  • Allow for setting custom headers via --header #452 (thanks @deantvv)

[0.10.4] - 2021-01-05

  • Add --dirs-first/-D option to list directories first #423 (thanks @levaitamas)

[0.10.3] - 2020-11-09

  • Actually fix publish workflow

[0.10.2] - 2020-11-09

  • Fix publish workflow

[0.10.1] - 2020-11-09

  • Now compiles on stable! :D

[0.10.0] - 2020-10-02

  • Add embedded favicon #364
  • Add --title option which can be used to set the page title #378 (thanks @ahti)
  • Default title is now the same host received in the request #378 (thanks @ahti)
  • Client-side color-scheme handling #380 (thanks @ahti)

[0.9.0] - 2020-09-16

  • Added prebuilt binaries for AARCH64, ARMv7, and ARM #350
  • Remove percent-encoding in heading and title #362 (thanks @ahti)
  • Make name ordering case-insensitive #362 (thanks @ahti)
  • Give name column more space #362 (thanks @ahti)
  • Fix double-escaping #354
  • Upgrade to actix-web 3.0
  • Fix time display for files created "now" #373 (thanks @imp and @KevCui)

[0.8.0] - 2020-07-22

  • Accept port 0 to find a random free port and use that #327 (thanks @parrotmac)
  • Show QR code in interface #330 (thanks @wyhaya)
  • Ported to actix-web 2 and futures 0.3 #343 (thanks @equal-l2)

[0.7.0] - 2020-05-14

  • Add zip archiving #297 (thanks @marawan31)

[0.6.0] - 2020-03-14

  • Add option to disable archives #235 (thanks @DamianX)
  • Fix minor bug when using --random-route #219
  • Add a default index serving option #189

[0.5.0] - 2019-06-24

  • Add streaming download of tar archives (thanks @gyscos)
  • Add support for hashed passwords (thanks @KSXGitHub)
  • Add support for multiple auth flags (thanks @KSXGitHub)
  • Some theme related bug fixes (thanks @boastful-squirrel)

File: tests/data/auth1.txt

joe:123
bob:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
bill:

File: .github/dependabot.yml

version: 2
updates:

  • package-ecosystem: cargo
    directory: "/"
    schedule:
    interval: monthly
    groups:
    all-dependencies:
    patterns:
    - "*"

File: .github/FUNDING.yml

github: svenstaro

File: .github/workflows/build-release.yml

name: Build/publish release

on: [push, pull_request]

jobs:
publish:
name: Binary ${{ matrix.target }} (on ${{ matrix.os }})
runs-on: ${{ matrix.os }}
outputs:
version: ${{ steps.extract_version.outputs.version }}
strategy:
matrix:
include:
- os: ubuntu-latest
target: x86_64-unknown-linux-musl
compress: true
cargo_flags: ""
- os: ubuntu-latest
target: x86_64-unknown-linux-gnu
compress: true
cargo_flags: ""
- os: ubuntu-latest
target: aarch64-unknown-linux-musl
compress: true
cargo_flags: ""
- os: ubuntu-latest
target: aarch64-unknown-linux-gnu
compress: true
cargo_flags: ""
- os: ubuntu-latest
target: armv7-unknown-linux-musleabihf
compress: true
cargo_flags: ""
- os: ubuntu-latest
target: armv7-unknown-linux-gnueabihf
compress: true
cargo_flags: ""
- os: ubuntu-latest
target: arm-unknown-linux-musleabihf
compress: true
cargo_flags: ""
- os: ubuntu-latest
target: riscv64gc-unknown-linux-gnu
compress: false
cargo_flags: "--no-default-features"
- os: windows-latest
target: x86_64-pc-windows-msvc
compress: true
cargo_flags: ""
- os: windows-latest
target: i686-pc-windows-msvc
compress: true
cargo_flags: ""
- os: macos-latest
target: x86_64-apple-darwin
compress: false
cargo_flags: ""
- os: macos-latest
target: aarch64-apple-darwin
compress: false
cargo_flags: ""
- os: ubuntu-latest
target: x86_64-unknown-freebsd
compress: false
cargo_flags: ""
- os: ubuntu-latest
target: x86_64-unknown-illumos
compress: false
cargo_flags: ""

text
steps:
  - name: Checkout code
    uses: actions/checkout@v5

  - name: Setup Rust toolchain
    uses: dtolnay/rust-toolchain@stable

  - run: sudo apt install musl-tools
    if: startsWith(matrix.os, 'ubuntu')

  - name: cargo build
    uses: houseabsolute/actions-rust-cross@v0
    with:
      command: build
      args: --release --locked ${{ matrix.cargo_flags }}
      target: ${{ matrix.target }}

  - name: Set exe extension for Windows
    run: echo "EXE=.exe" >> $env:GITHUB_ENV
    if: startsWith(matrix.os, 'windows')

  - name: Compress binaries
    uses: svenstaro/upx-action@v2
    with:
      files: target/${{ matrix.target }}/release/miniserve${{ env.EXE }}
      args: --best --lzma
      strip: false  # We're stripping already in Cargo.toml
    if: ${{ matrix.compress }}

  - name: Upload artifact
    uses: actions/upload-artifact@v4
    with:
      name: ${{ matrix.target }}
      path: target/${{ matrix.target }}/release/miniserve${{ env.EXE }}

  - name: Get version from tag
    id: extract_version
    run: |
      echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
    shell: bash

  - name: Install CHANGELOG parser
    uses: taiki-e/install-action@parse-changelog

  - name: Get CHANGELOG entry
    run: parse-changelog CHANGELOG.md ${{ steps.extract_version.outputs.version }} | tee changelog_entry
    if: startsWith(github.ref_name, 'v') && github.ref_type == 'tag'
    shell: bash

  - name: Read changelog entry from file
    id: changelog_entry
    uses: juliangruber/read-file-action@v1
    with:
      path: ./changelog_entry
    if: startsWith(github.ref_name, 'v') && github.ref_type == 'tag'

  - name: Release
    uses: svenstaro/upload-release-action@v2
    with:
      repo_token: ${{ secrets.GITHUB_TOKEN }}
      file: target/${{ matrix.target }}/release/miniserve${{ env.EXE }}
      tag: ${{ github.ref_name }}
      asset_name: miniserve-${{ steps.extract_version.outputs.version }}-${{ matrix.target }}${{ env.EXE }}
      body: ${{ steps.changelog_entry.outputs.content }}
    if: startsWith(github.ref_name, 'v') && github.ref_type == 'tag'

container-images:
name: Publish images
runs-on: ubuntu-latest
needs: publish
# Run for tags and pushes to the default branch
if: (startsWith(github.ref_name, 'v') && github.ref_type == 'tag') || github.event.repository.default_branch == github.ref_name

text
steps:
  - name: Checkout code
    uses: actions/checkout@v5

  - name: Download artifact aarch64-unknown-linux-gnu
    uses: actions/download-artifact@v4
    with:
      name: aarch64-unknown-linux-gnu
      path: target/aarch64-unknown-linux-gnu/release

  - name: Download artifact x86_64-unknown-linux-gnu
    uses: actions/download-artifact@v4
    with:
      name: x86_64-unknown-linux-gnu
      path: target/x86_64-unknown-linux-gnu/release

  - name: Download artifact armv7-unknown-linux-gnueabihf
    uses: actions/download-artifact@v4
    with:
      name: armv7-unknown-linux-gnueabihf
      path: target/armv7-unknown-linux-gnueabihf/release

  - name: Download artifact aarch64-unknown-linux-musl
    uses: actions/download-artifact@v4
    with:
      name: aarch64-unknown-linux-musl
      path: target/aarch64-unknown-linux-musl/release

  - name: Download artifact x86_64-unknown-linux-musl
    uses: actions/download-artifact@v4
    with:
      name: x86_64-unknown-linux-musl
      path: target/x86_64-unknown-linux-musl/release

  - name: Download artifact armv7-unknown-linux-musleabihf
    uses: actions/download-artifact@v4
    with:
      name: armv7-unknown-linux-musleabihf
      path: target/armv7-unknown-linux-musleabihf/release

  - name: podman login
    run: podman login --username ${{ secrets.DOCKERHUB_USERNAME }} --password ${{ secrets.DOCKERHUB_TOKEN }} docker.io

  - name: podman build linux/arm64
    run: podman build --format docker --platform linux/arm64/v8 --manifest miniserve -f Containerfile target/aarch64-unknown-linux-gnu/release

  - name: podman build linux/amd64
    run: podman build --format docker --platform linux/amd64 --manifest miniserve -f Containerfile target/x86_64-unknown-linux-gnu/release

  - name: podman build linux/arm
    run: podman build --format docker --platform linux/arm/v7 --manifest miniserve -f Containerfile target/armv7-unknown-linux-gnueabihf/release

  - name: podman manifest push latest
    run: podman manifest push miniserve docker.io/svenstaro/miniserve:latest

  - name: podman manifest push tag version
    run: podman manifest push miniserve docker.io/svenstaro/miniserve:${{ needs.publish.outputs.version }}
    if: startsWith(github.ref_name, 'v')

  - name: podman build linux/arm64 (alpine edition)
    run: podman build --format docker --platform linux/arm64/v8 --manifest miniserve-alpine -f Containerfile.alpine target/aarch64-unknown-linux-musl/release

  - name: podman build linux/amd64 (alpine edition)
    run: podman build --format docker --platform linux/amd64 --manifest miniserve-alpine -f Containerfile.alpine target/x86_64-unknown-linux-musl/release

  - name: podman build linux/arm (alpine edition)
    run: podman build --format docker --platform linux/arm/v7 --manifest miniserve-alpine -f Containerfile.alpine target/armv7-unknown-linux-musleabihf/release

  - name: podman manifest push latest (alpine edition)
    run: podman manifest push miniserve-alpine docker.io/svenstaro/miniserve:alpine

  - name: podman manifest push tag version (alpine edition)
    run: podman manifest push miniserve-alpine docker.io/svenstaro/miniserve:${{ needs.publish.outputs.version }}-alpine
    if: startsWith(github.ref_name, 'v')

File: .github/workflows/ci.yml

name: CI

on: [push, pull_request]

jobs:
ci:
name: ${{ matrix.os }}
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]

text
steps:
  - name: Checkout code
    uses: actions/checkout@v5

  - name: Setup Rust toolchain
    uses: dtolnay/rust-toolchain@stable
    with:
      components: rustfmt, clippy

  - name: cargo build
    run: cargo build

  - name: cargo test
    run: cargo test -- --test-threads 1

  - name: cargo fmt
    run: cargo fmt --all -- --check

  - name: cargo clippy
    run: cargo clippy -- -D warnings

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#cli Browse cli catalog → #command-line Browse command-line catalog → #command-line-tool Browse command-line-tool catalog → #http-server Browse http-server catalog → #serve Browse serve catalog → #server Browse server catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →