servepass

Serve files on your LAN over HTTPS with a token. That's it.

pipx install servepass
servepass

---

You know python -m http.server. It's great for quick file sharing on a local network. The problem is it has zero authentication, so anyone on the same network can grab whatever you're serving.

servepass fixes that. Same zero-config philosophy, but encrypted and with a token-protected URL. Run it, get a link, share it. No accounts, no cloud, no telemetry.

Install

pipx install servepass

Or with pip:

pip install servepass

Requires Python 3.8+. No required dependencies.

HTTPS needs a way to create a certificate. servepass uses the openssl command if it's on your system (it is on most Linux and macOS machines). If it isn't, for example on Windows, install the optional extra:

pipx install "servepass[tls]"

Usage

# Serve current directory
servepass

# Serve a specific path
servepass ./downloads

# Custom port
servepass --port 9090

# Fixed token (at least 16 characters recommended)
servepass --token my-long-fixed-token

# Your own certificate, e.g. from mkcert (no browser warning)
servepass --cert cert.pem --key key.pem

# Limit upload size (default 4G, 0 = no limit)
servepass --max-upload 500M

# Plain HTTP, no encryption
servepass --http

# No authentication
servepass --no-auth

Every time you run servepass, a fresh token is generated. You get a URL and an optional QR code in the terminal:

  Serving:  /home/user/downloads
  Network:  https://192.168.1.42:8080/?token=Xq3vT9kR2mW8pL5nB7cY1a
  Token:    Xq3vT9kR2mW8pL5nB7cY1a
  SHA-256:  6A:1F:0C:93:E2:5B:7D:48:AA:10:C4:3E:9F:22:B8:71
            05:DE:6C:18:F4:A9:33:57:0B:E7:92:4D:C6:81:2A:F0
            Your browser will warn about the self-signed certificate.
            It's safe to continue if it shows this same fingerprint.
  Uploads:  up to 4 GiB

  Ctrl+C to stop

Open the URL in any browser on your network and you're in. Scan the QR code to open it directly on your phone. Once you open the link, the browser keeps the token in a cookie and drops it from the address bar, so it doesn't end up in your history or in links you copy.

HTTPS and the certificate warning

servepass serves HTTPS by default, so nobody else on the network can read the token or the files you transfer.

The first time you run it, servepass creates a self-signed certificate for your machine's LAN address and keeps it in your config folder (~/.config/servepass on Linux, ~/Library/Application Support/servepass on macOS, %APPDATA%\servepass on Windows). Browsers don't know this certificate, so they show a warning the first time you connect.

To check the connection is really to your machine, open the certificate details in the browser (click the warning or the padlock icon) and compare its SHA-256 fingerprint with the one servepass printed. If they match, continue. If they don't, someone may be intercepting the connection. Because the certificate is reused, each device only has to do this once for each network address.

If you'd rather not see the warning at all, create a locally trusted certificate with mkcert and pass it with --cert and --key.

If you type http:// by mistake, servepass redirects you to https://.

Using it from scripts

Pass the token as a header instead of in the URL:

# download
curl --cacert cert.pem -H "Authorization: Bearer $TOKEN" https://192.168.1.42:8080/file.zip -O

# upload
curl --cacert cert.pem -H "Authorization: Bearer $TOKEN" -F "file=@photo.jpg" https://192.168.1.42:8080/

cert.pem is the certificate servepass created in your config folder. ?token=... in the URL also still works.

What you can do

Download files on your phone without cables Serve a folder, scan the QR code on your iPhone or Android, and grab whatever you need directly from the browser. Works with any file type: PDFs, photos, videos, zip archives.

Send photos from your phone to your computer Open the URL on your phone, use the upload form at the top of the page, and the file lands directly in the served folder on your machine. No AirDrop, no cloud, no cable. Uploads never overwrite an existing file: a second photo.jpg is saved as photo (1).jpg.

Share documents with someone on the same network Run servepass in a folder with the files you want to share. Send the link. They open it in any browser and download what they need.

QR code

The QR code is printed automatically if the qrcode package is installed:

pipx install "servepass[qr]"      # or both: "servepass[tls,qr]"

Without it, servepass works normally and just shows the URL.

Security

• Traffic is encrypted with TLS 1.2+ (unless you use --http).
• Tokens are 128-bit random values, so they can't be guessed.
• After the first visit the token lives in an HttpOnly, SameSite=Lax cookie, not in the URL.
• Uploads are only accepted from the servepass page itself, not from other websites.
• Uploads can't be written outside the served folder and never replace existing files.
• File names in the listing are escaped, so a file called <script>... is just text.
• Uploads are streamed to disk, and a size limit applies (--max-upload).

Known limitations

• The certificate is self-signed, so browsers warn on first connect. Check the fingerprint (see above) or use --cert with a trusted certificate.
• Anyone who has the link has full read and upload access to the served folder. Only share it with people you trust.
• If servepass can't create a certificate (no openssl and no servepass[tls]), it falls back to plain HTTP and prints a warning.
• Symlinks inside the served folder are followed when downloading, like python -m http.server.

Who this is for

• You're on a trusted LAN (home, office, workshop) and want to share files quickly
• You want to transfer files to and from your phone without cables or cloud storage
• You don't want to expose an unauthenticated HTTP server to everyone on the network
• You want something lightweight with zero setup time

License

MIT