serv

Serve file or folder as a web-page.

CHANGELOG

Usage

Install

mise install github:dector/serve
serve --version

Serve file or folder

serv README.md
serv Downloads

Default port: 8080.

To use a specific port, pass --port/-p:

serv -p 3000 README.md

If the requested port is unavailable, serv automatically picks another free port.

Bind address

Set BIND to override the listening address:

BIND=all serv .
BIND=0.0.0.0 serv .
BIND= serv .
BIND=127.0.0.1 serv .

Empty, all, and 0.0.0.0 all bind every IPv4 interface, making the server accessible from the network. An explicit bind never silently falls back to localhost.

When BIND is unset, existing automatic binding is preserved: all interfaces when available, otherwise localhost. Tailscale uses localhost by default; BIND overrides this too.

Expose via Tailscale

Use --expose-tailscale/-T to expose the local server with Tailscale Serve. The tailscale CLI must be installed and configured.

serv -T README.md
serv --expose-tailscale Downloads
serv -T 443 README.md
serv -p 3000 -T 443 README.md

When -T is used without a value, serv chooses a seeded-random high local port and uses the same HTTPS port for Tailscale. Passing a value to -T sets the Tailscale HTTPS port only; --port/-p sets the local backend port only.

With Tailscale exposure enabled, the local server binds to 127.0.0.1 instead of all interfaces unless BIND is set. If an explicit local port is busy, serv fails instead of choosing another port.

Open in browser

Use --open/-o to open the served URL in your default browser after the server starts:

serv --open README.md
serv -o Downloads

Browser opening is best-effort; if it fails, the server keeps running and prints the URL.

Serving modes

serv defaults to preview mode, optimized for reading repos and websites:

serv .
serv README.md

In preview mode, supported Markdown files (.md, .markdown, .mdown, .mkd) render as HTML. Directories resolve README first, then index.html, then fall back to a listing. Auto-resolved README previews include a foldable side menu for navigating sibling files and folders.

Use file mode for raw file browsing:

serv --mode file Downloads
serv -m f Downloads

In file mode, files are served raw and directories show listings by default.

Change directory resolution with --dir-resolve:

serv --mode preview --dir-resolve index-first site
serv -m p --dir-resolve rf .
serv -m file --dir-resolve index-only site

Strategies: readme-first/rf, index-first/if, readme-only/ro, index-only/io, none/n.

Per-request URL overrides:

/README.md?raw=1
/README.md?preview=1
/docs/?resolve=none
/docs/?resolve=index-only

Behavior

• You can serve either a directory or a single file.
• HTML files are served directly as static HTML.
• Missing directory resolution candidates fall back to a directory listing.
• --preview/-P is deprecated; use --mode preview.
• --no-index-resolve is deprecated; use --dir-resolve.

License

Discributed using MIT license.