miniserve — Fast CLI File Server with Upload Support

Introduction

miniserve is a small command-line HTTP file server written in Rust. It is designed for quick, ad-hoc file sharing over a local network or the internet. Point it at a directory or a single file and it immediately starts serving content with a clean web interface, optional file uploads, and authentication.

What miniserve Does

• Serves files and directories over HTTP with a built-in web UI
• Supports file uploads from the browser when enabled with a flag
• Provides HTTP basic authentication for access control
• Generates QR codes for the server URL for easy mobile access
• Supports TLS for encrypted connections using user-provided certificates

Architecture Overview

miniserve is built on the Actix Web framework and compiles to a single static binary. When started, it binds to a port, reads the target path, and serves an HTML directory listing or the file content directly. File uploads are handled via multipart form processing. The entire application is stateless and requires no configuration files, databases, or runtime dependencies.

Self-Hosting & Configuration

• Install via cargo, Homebrew, or download a prebuilt binary for Linux, macOS, or Windows
• Run miniserve /path/to/dir to start serving immediately
• Enable uploads with --upload-files and optionally restrict with --auth user:pass
• Use --tls-cert and --tls-key flags for HTTPS
• Set --hide patterns to exclude files from the directory listing

Key Features

• Single binary with zero dependencies and instant startup
• Clean, responsive web UI with file icons and sorting
• QR code generation for quick sharing to mobile devices
• Directory listing with file size, modification time, and symlink resolution
• Color-coded terminal output showing request logs in real time

Comparison with Similar Tools

• python -m http.server — Built into Python but lacks upload, auth, and TLS; miniserve adds all three
• caddy file-server — Full web server with automatic HTTPS; miniserve is lighter for ad-hoc use
• serve (npm) — Node.js-based static server; miniserve is a single binary with no runtime
• darkhttpd — Minimal C-based server; miniserve adds uploads, auth, QR codes, and a modern UI

FAQ

Q: How do I share a file with someone on my local network? A: Run miniserve file.zip and share the displayed URL or scan the QR code from their phone.

Q: Is there a Docker image? A: Yes. The official Docker image is available and can be run with docker run -v /path:/data -p 8080:8080 svenstaro/miniserve /data.

Q: Can I use it for production file hosting? A: It is designed for temporary, ad-hoc sharing. For production use, consider a full web server like Nginx or Caddy.

Q: Does it support range requests and resumable downloads? A: Yes. miniserve supports HTTP range requests, allowing clients to resume interrupted downloads.

Sources

• https://github.com/svenstaro/miniserve
• https://crates.io/crates/miniserve