.\"             -*-Nroff-*-
.\"
.TH "algernon" 1 "05 Nov 2026" "" ""
.SH NAME
algernon \- web server
.sp
.SH SYNOPSIS
.B algernon
[\fBflags\fR]
[\fBfile or directory\fR]
[\fBhost\fR][\fB:port\fR]
.sp
.SH DESCRIPTION
Serve the given file or directory, with an optional \fB:port\fP and \fBhostname\fP.
.sp
.SH OPTIONS
.sp
.TP
.B \-a or \-\-autorefresh
Inject JavaScript that refreshes the served web pages when they receive
server-sent events (SSE), when a file or directory has changed.
.TP
.B \-v or \-\-version
Display the current version number.
.TP
.B \-h or \-\-help
Display usage information. Includes a few flags that are not listed here.
.TP
.B \-\-noheaders
Don't use the security-related HTTP headers.
.TP
.B \-\-stricter
Stricter HTTP headers (same origin policy).
.TP
.B \-n or \-\-nobanner
Don't display a colorful banner at start.
.TP
.B \-\-cert=FILENAME
Provide a TLS certificate, for using HTTPS.
.TP
.B \-\-key=FILENAME
Provide a TLS key, for using HTTPS.
.TP
.B \-\-boltdb=FILENAME
Provide a Bolt database filename, instead of using \fB/tmp/algernon.db\fP.
.TP
.B \-t or \-\-httponly
Only serve regular HTTP.
.TP
.B \-\-http2only
Only serve HTTP/2, without HTTPS.
.TP
.B \-u
Serve QUIC aka HTTP/3.
.TP
.B \-\-limit=N
Limit clients to N request per second (the default is 10).
.TP
.B \-\-nodb
Don't use a database backend. Some Lua functions might not work.
.TP
.B \-\-timeout=N
Timeout when serving files, in seconds.
.TP
.B \-\-largesize=N
Threshold for not reading static files into memory, in bytes.
.TP
.B \-\-lua
Don't serve anything, just present an interactive Lua prompt (REPL).
.TP
.B \-s or \-\-noninteractive
Disable debug + interactive mode. Is unrelated to if anything is served or not.
.TP
.B \-q or \-\-quiet
Don't output anything to stdout or stderr.
.TP
.B \-\-servername=NAME
Custom HTTP header value for the \fBServer\fP field.
.TP
.B \-o or \-\-open=COMMAND
Open the served URL with \fBxdg-open\fP, or with the given application.
.TP
.B \-z or \-\-quit
Quit after the first request has been served.
.TP
.B \-m
View the given Markdown file in the browser.
Quit after the file has been served once.
This is equivalent to \fB\-q \-o \-z\fP.
.TP
.B \-c or \-\-statcache
Speed up responses by caching \fBos.Stat\fP.
Only use if served files will never be removed!
.TP
.B \-\-accesslog=FILENAME
Filename for where to log requests in the Combined Log Format (CLF).
.TP
.B \-\-ncsa=FILENAME
Filename for where to log requests in the Common Log Format (NCSA).
.TP
.B \-\-letsencrypt
Use certificates provided by Let's Encrypt for all served domains and serve
over regular HTTPS by using CertMagic. Implies \fB\-\-domain\fP.
.TP
.B \-\-testcert
Use the Let's Encrypt staging CA instead of the production CA, to avoid
hitting rate limits while configuring a new domain. Use together with
\fB\-\-letsencrypt\fP.
.TP
.B \-D or \-\-domain
Serve files from the subdirectory with the same name as the requested domain,
for instance \fB/srv/algernon/mydomain.com\fP and \fB/srv/algernon/otherweb.com\fP,
depending on if HTTP requests are using \fBhttps://mydomain.com\fP or
\fBhttps://otherweb.com\fP.
.TP
.B \-x or \-\-simple
Simple mode. Serve the current directory over regular HTTP, disable debug mode,
interactive mode, request limits and all features that require a database.
.TP
.B \-\-dir=DIRECTORY
The directory to serve. Can also be given as a positional argument.
.TP
.B \-\-addr=[HOST][:PORT]
The host and port to serve on, like \fB:4000\fP or \fB[::1]:443\fP.
Can also be given as a positional argument.
.TP
.B \-\-http-addr=[HOST][:PORT]
Serve regular HTTP on this address. Can be combined with \fB\-\-https\-addr\fP,
to serve both at the same time, on different ports.
.TP
.B \-\-https\-addr=[HOST][:PORT]
Serve HTTPS + HTTP/2 on this address. Can be combined with \fB\-\-http\-addr\fP.
.TP
.B \-r or \-\-redirect
Redirect HTTP traffic to HTTPS, if both are being served.
.TP
.B \-\-conf=FILENAME
Server configuration, written in Lua. The default is \fBserverconf.lua\fP.
.TP
.B \-e or \-\-dev
Development mode. Serve regular HTTP, enable debug mode, raise the request
limit and use a cache setting that is suitable while developing.
.TP
.B \-p or \-\-prod
Production mode. Serve \fB/srv/algernon\fP, use the certificate and key in
\fB/etc/algernon\fP, cache aggressively and disable interactive mode.
.TP
.B \-d or \-\-debug
Debug mode. Show detailed error messages in the browser.
.TP
.B \-V or \-\-verbose
Verbose logging.
.TP
.B \-\-server
Deprecated alias for \fB\-\-noninteractive\fP. Still supported.
.TP
.B \-\-log=FILENAME
Server log file, written as JSON. Send SIGHUP after moving it aside, to make
Algernon re-open it.
.TP
.B \-\-internal=FILENAME
Internal log file, for HTTP/2 debug output. The default is \fB/dev/null\fP.
.TP
.B \-\-watchdir=DIRECTORY
Directory to watch for changes. Also enables \fB\-\-autorefresh\fP.
.TP
.B \-\-eventserver=[HOST][:PORT]
Address for the server-sent events (SSE) server that \fB\-\-autorefresh\fP uses.
The default is \fB:5553\fP.
.TP
.B \-\-eventrefresh=DURATION
How often to check for changes, like \fB350ms\fP.
.TP
.B \-\-theme=NAME
Theme for Markdown pages, directory listings and error pages.
.TP
.B \-\-dirbaseurl=URL
Base URL in front of the links in the directory listing, like \fB/files\fP or
\fBhttps://example.com/pub\fP. Useful when Algernon is behind a reverse proxy
that serves it on a sub-path.
.TP
.B \-\-proxy=[/PREFIX=]ENDPOINT
Reverse proxy requests to \fIENDPOINT\fP, which can be a URL like
\fBhttp://localhost:3000\fP, \fBhost:port\fP or just a port number.
Everything is proxied unless a path prefix is given, like
\fB\-\-proxy /api=3000\fP. Can be given several times; the longest matching
prefix wins.
.TP
.B \-\-hide\-dotfiles
Hide files and directories that start with a dot, both in directory listings
and when serving. \fB.well\-known\fP is still served, for ACME challenges.
.TP
.B \-\-redis=[HOST][:PORT]
Address of the Redis or Valkey server. The default is \fB:6379\fP.
.TP
.B \-\-dbindex=N
Redis database index.
.TP
.B \-b or \-\-bolt
Use the default Bolt database filename.
.TP
.B \-\-maria=DSN
MariaDB/MySQL connection string.
.TP
.B \-\-mariadb=NAME
MariaDB/MySQL database name.
.TP
.B \-\-postgres=DSN
PostgreSQL connection string.
.TP
.B \-\-postgresdb=NAME
PostgreSQL database name.
.TP
.B \-\-sqlite=FILENAME
SQLite filename, or connection string.
.TP
.B \-\-cache=MODE
What to cache. One of \fBon\fP, \fBprod\fP, \fBdev\fP, \fBimages\fP, \fBsmall\fP
or \fBoff\fP.
.TP
.B \-\-cachesize=N
Cache size, in bytes.
.TP
.B \-\-nocache
Disable caching.
.TP
.B \-\-rawcache
Disable cache compression.
.TP
.B \-\-nolimit
Disable rate limiting.
.TP
.B \-\-clear
Clear the default URL prefixes that are used for handling permissions.
.TP
.B \-\-cookiesecret=STRING
Secret to use when setting and getting login cookies.
.TP
.B \-\-ctrld
Press ctrl\-d twice to exit the interactive Lua prompt (REPL).
.TP
.B \-\-quic
Serve just QUIC aka HTTP/3, if Algernon was built with QUIC support.
.TP
.PP
.SH "LUA REQUEST API"
.sp
A selection of Lua functions available inside served pages. Type \fBhelp web\fP
in the interactive Lua prompt for the full list.
.TP
.B remoteaddr() -> string
Return the remote address ("host:port") of the connected client.
.PP
.SH "SIGNALS"
.sp
On UNIX-like platforms, Algernon responds to the following signals:
.TP
.B SIGUSR1, SIGUSR2
Clear the file cache.
.TP
.B SIGHUP
Re-open the server log and the access logs, for use with log rotation tools
like \fBlogrotate\fP(8) or \fBnewsyslog\fP(8). Rotate by moving the files aside
and then sending SIGHUP, instead of truncating them.
.PP
.SH "ENV"
.sp
The \fBNO_COLOR\fP environment variable can be set to 1 to turn off all colors.
.sp
\fBALGERNON_CERT_DIR\fP sets where the Let's Encrypt certificates are stored.
If it is not set, \fB$XDG_DATA_HOME/certmagic\fP is used, then
\fB$HOME/.local/share/certmagic\fP, then \fB/var/lib/algernon\fP. The directory
must persist across reboots, since requesting new certificates for every boot
counts against the Let's Encrypt rate limits.
.sp
.SH "WHY"
.sp
Web development with few dependencies and a decent caching system.
.SH "EXAMPLE USAGE"
.sp
.TP
For auto-refreshing a webpage while developing:
\fBalgernon --dev --httponly --debug --autorefresh --bolt --noninteractive . :4000\fP
.TP
Serve /srv/mydomain.com and /srv/otherweb.com over HTTP and HTTPS + HTTP/2:
\fBalgernon -c --domain --noninteractive --cachesize 67108864 --prod /srv\fP
.TP
Serve the current dir over QUIC, port 7000, no banner:
\fBalgernon -s -u -n . :7000\fP
.TP
Serve the current directory over HTTP, port 3000. No limits, cache, permissions
or database connections:
\fBalgernon -x\fP
.SH "SEE ALSO"
.BR apache (1)
.BR caddy (1)
.BR nginx (1)
.SH VERSION
1.17.13
.SH AUTHOR
.B algernon
was written by Alexander F. Rødseth <xyproto@archlinux.org>