Getting started¶
Install¶
The quickest way is uv — it manages Python for you, so there's nothing else to set up.
# run it ad-hoc, no install at all:
uvx servery
# …or install the `servery` command persistently:
uv tool install servery
Don't have uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh (or see the
uv install docs).
servery needs Python 3.13+ (the free-threaded 3.13t/3.14t builds work too) and
has no third-party runtime dependencies. With uvx, uv even fetches a matching
Python for you.
Your first server¶
Run servery in any directory:
Running without installing
The examples below use the servery command. To run any of them without
installing, just prefix with uvx — e.g. uvx servery --upload. uv fetches
servery (and a matching Python) on first use and caches it.
Open http://127.0.0.1:8000/ and you get a rich, sortable directory listing — sizes, modified times, a search box, per-type icons, and a light/dark theme — all rendered server-side with no JavaScript.
By default servery binds loopback only (127.0.0.1), so nothing is reachable
from the network until you ask for it. Press Ctrl+C to stop.
Serve a specific folder, on a specific port¶
directory(positional) — what to serve; defaults to the current directory.-p, --port— defaults to8000. If it's already in use, servery binds the next free port and tells you which (no "address already in use" crash).-b, --bind— defaults to127.0.0.1. Use0.0.0.0to expose on your LAN.
Share it on your network¶
--bind 0.0.0.0 listens on every interface, and --qr prints a scannable QR code
of your LAN URL so a phone on the same Wi-Fi can open it instantly. servery prints a
warning when you expose it, because that's a deliberate, security-relevant choice:
servery: serving /home/you/photos on http://0.0.0.0:8000/
servery: WARNING bound to 0.0.0.0 — reachable from the network
See Sharing on a LAN for --discoverable (mDNS/Bonjour) and QR
details.
A password-protected drop box¶
Accept uploads, protected by a password:
Now POSTing files (or using the upload form in the listing) writes them into the
served folder, but only with the right credentials. Auth is meaningless without
encryption, so pair it with HTTPS for anything real:
Basic auth without TLS sends the password in the clear
servery warns you when --auth runs over plain HTTP. Use --tls-self-signed
(instant, ad-hoc cert) on a LAN, or --acme for a real browser-trusted one.
Automatic, browser-trusted HTTPS¶
If a domain points at your machine and port 80 is reachable, servery can fetch a real Let's Encrypt certificate for you — with zero extra dependencies:
(It defaults to the Let's Encrypt staging CA so you can test safely; add
--acme-production for the real thing.) See HTTPS & certificates.
Profiles: presets for common setups¶
--profile applies a bundle of flags so you don't have to remember them. Any
explicit flag still overrides the preset.
servery --profile share # bind LAN + self-signed TLS, ready to share
servery --profile inbox # LAN + TLS + uploads: a secure drop box
servery --profile cdn # long cache + CORS, for serving static assets
The full list: app, cdn, dev, inbox, local, public-readonly,
public-readwrite, share — run servery --help to see them, or browse the
Guide for each feature they bundle.
Next steps¶
- Vision & goals — what servery is (and isn't), and why.
- Architecture — how a request flows through it, and the security model.
- Transports — the HTTP/1.1 → HTTP/2 → HTTP/3 tiering.
Then dig into the task-oriented Guide — uploads &
auth, HTTPS & certificates, WebDAV
mounts, compression & caching,
HTTP/2 & HTTP/3 — each with copy-paste examples. Every flag is
also documented by servery --help.