caddysnake CLI
The caddysnake package is available on PyPI and provides a CLI to serve Python WSGI/ASGI/ESGI applications powered by Caddy.
Install
pip install caddysnake
Available for Python 3.12 through 3.14 on Linux and macOS (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
# Start an ESGI server
caddysnake --server-type esgi --app main:application
CLI Options
Python-handler flags mirror the Caddyfile python block. Extra flags cover listen address, HTTPS, and static files.
| Flag | Short | Description | Default |
|---|---|---|---|
--server-type |
-t |
Required. Type of Python app: wsgi, asgi, or esgi |
— |
--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 |
--max-dynamic-apps |
Max distinct dynamic Python apps | 128 |
|
--request-body-max-size |
Maximum HTTP request body size (e.g. 1KiB, 2GB) |
unlimited | |
--python-path |
Path to the Python interpreter | — | |
--working-dir |
Working directory for the Python app | — | |
--venv |
Path to a Python virtual environment | — | |
--env-file |
Dotenv file for worker env (repeatable) | — | |
--env-var |
Inline worker env var NAME=VALUE (repeatable) |
— | |
--start-timeout |
Worker readiness wait (120s default; use =-1 or forever for indefinite) |
120s |
|
--runtime |
WSGI: sync|gevent; ESGI: gevent; ASGI: native|uvloop |
per interface | |
--lifespan |
ASGI lifespan events (on|off) |
off |
|
--cache-mode |
Cache topology: local|cluster |
local |
|
--cache-listen |
Cluster peer TCP listener (host:port) |
— | |
--cache-advertise |
Dialable address identifying this peer | — | |
--cache-peer |
Static cluster peer address (repeatable) | — | |
--cache-namespace |
Namespace shared by every cluster peer | — | |
--cache-secret |
Shared peer secret (16–4096 bytes) | — | |
--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 |
|
--autoreload |
Watch .py files and reload on changes |
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 — 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
1 maintainer
Metadata
1 maintainer
Release files for caddysnake 0.6.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 206.5 MB
Release files / caddysnake-0.6.4-cp314-cp314-manylinux_2_34_x86_64.whl
| Download URL | caddysnake-0.6.4-cp314-cp314-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 17.8 MB |
| Tags | CPython 3.14 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
cbceda98f044144f03c08174151643dc1f7c4a85e912400ee360c87a04612e9f
|
|
BLAKE2b-256 checksum How to use checksums |
a15d0de954ae73caf8a22685bd3bbcc285551373771cd0f885be4e391e55d9c5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp314-cp314-manylinux_2_34_aarch64.whl
| Download URL | caddysnake-0.6.4-cp314-cp314-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 16.1 MB |
| Tags | CPython 3.14 Linux glibc 2.34+ ARM64 |
|
SHA-256 checksum How to use checksums |
695218cc6020cf33d226aa8ccccc2a5e9a2b322e012034197dd8948f9bfcc845
|
|
BLAKE2b-256 checksum How to use checksums |
038865bff13a60dfe9979460d07bada67dc2dbc711c24a7752a1f3b52ddf9068
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | caddysnake-0.6.4-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 16.9 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c69f339287ff685b6f5a4ce9128a1efe6925735b910b256f4084d8b04b8d6cbf
|
|
BLAKE2b-256 checksum How to use checksums |
e8b722b60c900db0c8061fb4192d78e3686491a11cfec26be15e5392b525f42a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp314-cp314-macosx_10_12_x86_64.whl
| Download URL | caddysnake-0.6.4-cp314-cp314-macosx_10_12_x86_64.whl |
|---|---|
| Size | 18.1 MB |
| Tags | CPython 3.14 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
8758e3947182061465a6708430130d1a4604340430b46c0bb8920d16eae52911
|
|
BLAKE2b-256 checksum How to use checksums |
5bcfd78a51bae278c45d40f1c2c9a283ae7564918a7525125e8bab5fbd32f863
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp313-cp313-manylinux_2_34_x86_64.whl
| Download URL | caddysnake-0.6.4-cp313-cp313-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 17.8 MB |
| Tags | CPython 3.13 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
ba858706bd55d68ac85be5c599eefea7cc9a8899bc5c992b4e91a51f3fc61c80
|
|
BLAKE2b-256 checksum How to use checksums |
420ad8e3b157d62d8deb183dee6271cf3cbd713f3dea99a646106632800cd965
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp313-cp313-manylinux_2_34_aarch64.whl
| Download URL | caddysnake-0.6.4-cp313-cp313-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 16.1 MB |
| Tags | CPython 3.13 Linux glibc 2.34+ ARM64 |
|
SHA-256 checksum How to use checksums |
5dd0ac229e3b535fcaa8e90574c791629354cc844306d9c63fac68cad1c39084
|
|
BLAKE2b-256 checksum How to use checksums |
c358fc39fe3aeeaced7f5950a6262d59302f32272e1c0f07c9edcdf2acd48122
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | caddysnake-0.6.4-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 16.9 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
03252031720ceec40eaa67da841179bd6f1bb484a7823cc1770dd6ca96714690
|
|
BLAKE2b-256 checksum How to use checksums |
f8ce38e01df87d045775b1cac6285c7052d1eabd1270e66109324535c4b8f6c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp313-cp313-macosx_10_12_x86_64.whl
| Download URL | caddysnake-0.6.4-cp313-cp313-macosx_10_12_x86_64.whl |
|---|---|
| Size | 18.1 MB |
| Tags | CPython 3.13 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
1b3a3d577edb35e72746804377d1f1b1fbb5fd7f80a78e7a251433363bcaf883
|
|
BLAKE2b-256 checksum How to use checksums |
393663588430dd58d2fa957feff6cf2e6cd81caf1ff929709ee3926a8febb469
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp312-cp312-manylinux_2_34_x86_64.whl
| Download URL | caddysnake-0.6.4-cp312-cp312-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 17.8 MB |
| Tags | CPython 3.12 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
fe50b62736de531e39ba0761403f796bdcca03f874b0e4eb3a2f3c520a7e5e62
|
|
BLAKE2b-256 checksum How to use checksums |
04af6267444ac13fd6be87ff98f16f5170e3db04a6e38863e7f3fbdb509631a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp312-cp312-manylinux_2_34_aarch64.whl
| Download URL | caddysnake-0.6.4-cp312-cp312-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 16.1 MB |
| Tags | CPython 3.12 Linux glibc 2.34+ ARM64 |
|
SHA-256 checksum How to use checksums |
1a92dd0695440b102b0bd6343dfc855981f95c72eb4987e2d1e277b0602aae24
|
|
BLAKE2b-256 checksum How to use checksums |
9af32ab6a56e3960c0de745a3ca8f6f8cc941b33456d1926c527b28557665f5d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | caddysnake-0.6.4-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 16.9 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
8bb8fa242bc948a05e5a19c39f93ebbef628703bed36753b8d18db637c9b32fc
|
|
BLAKE2b-256 checksum How to use checksums |
c9ea0ef0e4d4c6623d1240ba6fc51bd512b7ba98302deb8efe509b2773ab55f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / caddysnake-0.6.4-cp312-cp312-macosx_10_12_x86_64.whl
| Download URL | caddysnake-0.6.4-cp312-cp312-macosx_10_12_x86_64.whl |
|---|---|
| Size | 18.1 MB |
| Tags | CPython 3.12 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
708a7774db0ef4dd6d85176b74410d613b6665a78339919a76e9033928c20ba3
|
|
BLAKE2b-256 checksum How to use checksums |
e41271eeb9102ee74c9c739e9a06b8723d2f8b15e8c3b822ea83d9456554e923
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency log
