Registry / http-networking / snitun

snitun

JSON →
library0.46.1pypypi✓ verified 80d ago

Snitun is a Python library that provides a Server Name Indication (SNI) proxy with TCP multiplexing capabilities, useful for routing traffic based on the SNI header. It is actively maintained by NabuCasa (the developers behind Home Assistant), currently at version 0.45.2, with a steady release cadence.

pip install snitun
INSTALL
IMPORT
SIG · SNITUN
S
snitun
http-networkingpythonv0.46.1
Install
4.1s avg
Import
Disk
42MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.40.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 43.7MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 4.1s · import 0.000s · 46MB
42MB installed
● package 42MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PROTOCOL_VERSION
from snitun import PROTOCOL_VERSION
from snitun.config import Config
utils
from snitun import utils
from snitun.config import Config

This quickstart demonstrates how to configure and instantiate a `SnitunServer`. It outlines the required `Config` parameters, especially for TLS certificates and routing rules. Note that running a functional TLS proxy requires actual certificate and key files, which are indicated by placeholder paths in this example.

import asyncio import os from snitun.config import Config from snitun.server import SnitunServer # In a real-world scenario, you would provide paths to your # actual TLS server certificate and key files. # For this quickstart, we use placeholder paths. # Running this code as-is will likely fail unless these files exist # and contain valid cert/key pairs for a TLS server. # You can generate dummy ones or provide real paths via environment variables. # Example: SNITUN_SERVER_CERT=./server.pem SNITUN_SERVER_KEY=./server.key python your_script.py DUMMY_CERT = os.environ.get("SNITUN_SERVER_CERT", "/path/to/server.pem") DUMMY_KEY = os.environ.get("SNITUN_SERVER_KEY", "/path/to/server.key") async def main(): # Define the Snitun configuration config = Config( listen_host="127.0.0.1", listen_port=8443, server_certs=DUMMY_CERT, # Required for TLS server_key=DUMMY_KEY, # Required for TLS routes={ "example.com": { # SNI hostname to route "host": "192.168.1.100", # Target host "port": 443, # Target port "no_verify_ssl": False # Verify upstream SSL certs }, "another.example.org": { "host": "127.0.0.1", "port": 8080, "no_verify_ssl": True } } ) # Create an instance of the Snitun server server = SnitunServer(config) print(f"Snitun server configured to listen on {config.listen_host}:{config.listen_port}") print(f"Routes defined: {list(config.routes.keys())}") print("\nNOTE: To actually run and test this server, you must ensure valid TLS certificate and key files ") print(" are accessible at the configured `server_certs` and `server_key` paths.") print(" See Snitun documentation for proper setup.") print("\nTo start the server (after ensuring valid certs/keys):") print(" await server.start()") print(" await asyncio.Future() # Keep running indefinitely") print(" await server.stop()") if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingPrior to version 0.37.0, configuration parameters were often passed directly to `SnitunServer` or related functions. As of 0.37.0, all configuration must be provided via a `snitun.config.Config` object, which is then passed to `SnitunServer`.
fix
Refactor your configuration to create a `snitun.config.Config` instance and pass it to `SnitunServer`. E.g., `config = Config(...); server = SnitunServer(config)`.
affects: <0.37.0
gotchaSnitun operates as a TLS proxy, requiring valid `server_certs` and `server_key` paths in the `Config` object. Without correctly configured certificates, the server will fail to start or operate securely, leading to connection errors for clients.
fix
Ensure you provide paths to valid TLS certificate (`.pem`) and private key (`.key`) files via `config.server_certs` and `config.server_key`. For production, use certificates issued by a trusted CA and secure their storage.
affects: All versions
gotchaSnitun is built entirely on `asyncio`. Users must be familiar with `async`/`await` syntax and the `asyncio` event loop for proper integration and management of the server, including starting, stopping, and handling long-running operations.
fix
Ensure your application environment correctly manages the `asyncio` event loop. Always `await` asynchronous calls to `SnitunServer` methods like `start()` and `stop()`. Use `asyncio.run()` for top-level execution.
affects: All versions
gotchaSnitun routes traffic based on the Server Name Indication (SNI) header in client TLS handshakes. If client traffic does not include an SNI header (e.g., older clients, direct IP connections), routing based on `config.routes` will not occur, and the connection might be dropped or fallback to a default if configured.
fix
Ensure clients are configured to send SNI. Verify client-side logs or use network sniffers to confirm SNI presence for troubleshooting routing issues.
affects: All versions
Upgrade
Version history
0.46.1latest on PyPI · released Jun 11, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.12 or higher as per project metadata.
aiohttprequiredCore dependency for asynchronous HTTP client/server functionality.
cryptographyrequiredUsed for cryptographic operations, particularly TLS/SSL.
trustmeoptionalUsed for generating test certificates, not a runtime dependency for deployment but useful for local testing setups.
uvloopoptionalOptional dependency for a faster `asyncio` event loop implementation.
Agent activity
15 hits · last 30 days
node
12
OpenAI (training)
1
Resources
snitun — pip install snitun · libregistry