caddysnake 0.4.0

Python WSGI/ASGI server powered by Caddy

caddysnake CLI

The caddysnake package is available on PyPI and provides a CLI to serve Python WSGI/ASGI applications powered by Caddy.

Install

pip install caddysnake

Available for Python 3.12 through 3.14 on Linux (x86_64 and ARM64).

Usage

# Start a WSGI server
caddysnake --server-type wsgi --app main:app

# Start an ASGI server
caddysnake --server-type asgi --app main:app

CLI Options

Flag	Short	Description	Default
--server-type	-t	Required. Type of Python app: wsgi or asgi	—
--app	-a	Required. Python module and app variable (e.g. main:app)	—
--domain	-d	Domain name for HTTPS with automatic certificates	—
--listen	-l	Custom listen address	:9080
--workers	-w	Number of worker processes (0 = CPU count)	0
--static-path		Path to a static files directory	—
--static-route		Route prefix for static files	/static
--debug		Enable debug logging	false
--access-logs		Enable access logs	false

How it works

This package is built with maturin and distributed as platform-specific wheel files. Each wheel bundles a pre-compiled Caddy binary with the caddy-snake plugin (caddysnake-cli). The Python CLI wrapper (caddysnake_cli.py) uses click to parse arguments and then executes the bundled Caddy binary with os.execv.

The package is built and published automatically on tagged releases by the python-build.yml GitHub Actions workflow.

Full Documentation

See https://caddy-snake.readthedocs.io for complete documentation, including:

• Quickstart — get started in 5 minutes
• Installation & Distribution — PyPI, standalone binaries, Docker, and more
• Configuration Reference — all Caddyfile directives
• Examples — Flask, Django, FastAPI, Socket.IO, dynamic modules, autoreload
• Architecture — how it works under the hood