Configuration¶

Every server option is exposed in three equivalent ways:

• a CLI flag on the h2corn command
• an H2CORN_* environment variable
• a key in a TOML config file (passed via --config or H2CORN_CONFIG)

When the same option is provided in more than one place, the order of precedence is CLI > environment > TOML > defaults.

--host / --port and H2CORN_HOST / H2CORN_PORT are shortcuts for one TCP listener and cannot be combined with bind. --config and H2CORN_CONFIG select the TOML file; command-only controls are listed below.

Option index¶

Application¶

Where the ASGI app lives and how it is loaded.

root_path¶

ASGI root path (to mount the application at a subpath).

lifespan¶

ASGI lifespan handling mode.

timeout_lifespan_startup¶

Maximum time to wait for ASGI lifespan startup in seconds. Use 0 to disable.

timeout_lifespan_shutdown¶

Maximum time to wait for ASGI lifespan shutdown in seconds. Use 0 to disable.

Listeners¶

How h2corn accepts connections.

bind¶

Listener addresses to bind. Repeat the flag to add more listeners. Supports HOST:PORT, [IPv6]:PORT, unix:PATH, and fd://N.

uds_permissions¶

Octal mask for Unix Domain Socket permissions.

backlog¶

Maximum number of queued connections on the listening socket.

reuse_port¶

Set SO_REUSEPORT on the TCP listeners so other server processes can bind the same port — for zero-downtime deploys or independent processes. Workers of one server always share the inherited listener. TCP listeners only.

TLS¶

Direct TLS for TCP listeners. Leave unset when terminating TLS at a proxy.

certfile¶

PEM certificate chain file for direct TLS.

keyfile¶

PEM private key file for direct TLS. Encrypted keys are not supported.

ca_certs¶

PEM CA bundle used to verify client certificates for direct TLS.

cert_reqs¶

Client certificate verification mode for direct TLS.

Process and workers¶

Process identity, worker pool, and lifecycle on Unix.

pid¶

Write the server process PID to this file.

user¶

User name or numeric UID for worker processes and created Unix sockets.

group¶

Group name or numeric GID for worker processes and created Unix sockets.

umask¶

Octal process umask to apply before creating files and sockets. Leave unset to preserve the inherited umask.

workers¶

Number of worker processes to spawn.

runtime_threads¶

Number of Tokio runtime worker threads per worker process.

loop¶

Python event-loop implementation: 'auto' uses uvloop when installed (the 'h2corn[uvloop]' extra), otherwise the stdlib asyncio loop. h2corn runs its I/O in Rust, so this only affects how application callbacks are scheduled.

loop_threads¶

Number of Python event-loop threads per worker, balanced round-robin. Requires a free-threaded (no-GIL) interpreter; ignored on GIL builds. Secondary loops require the built-in asyncio or uvloop factory (the default 'auto' resolves to one); multiple loop threads are rejected when embedded in a custom loop. Each loop runs its own ASGI lifespan and state. Composes with workers — keep workers x loop_threads at or below the core count.

max_requests¶

Maximum number of requests or WebSocket sessions a worker should complete before retiring. Use 0 to disable.

max_requests_jitter¶

Maximum jitter added to max_requests to stagger worker retirements. Use 0 to disable.

timeout_worker_healthcheck¶

Maximum time between worker healthcheck heartbeats before the supervisor replaces the worker. Use 0 to disable.

HTTP and resource limits¶

Protocol behavior and per-connection bounds.

http1¶

Whether to accept HTTP/1.1 connections. Intended for development; disable in production.

access_log¶

Whether to log requests to stderr.

log_format¶

Encoding for everything h2corn writes to stderr: the startup banner, worker lifecycle, errors and access records. 'json' emits one object per line so the stream can be shipped without parsing prose.

max_concurrent_streams¶

Maximum active HTTP/2 streams per connection. At least 1.

limit_request_head_size¶

Maximum total HTTP/1.1 request head size in bytes. Use 0 for no limit.

limit_request_line¶

Maximum HTTP/1.1 request line size in bytes. Use 0 for no limit.

limit_request_fields¶

Maximum number of request header fields; HTTP/2 counts every decoded field, including duplicates. Use 0 for no limit.

limit_request_field_size¶

Maximum individual HTTP/1.1 header field size in bytes. Use 0 for no limit.

h2_max_header_list_size¶

Maximum decoded HTTP/2 header list size in bytes. Use 0 for no limit.

h2_max_header_block_size¶

Maximum compressed HTTP/2 header block size in bytes while collecting HEADERS and CONTINUATION frames. Use 0 for no limit.

h2_max_inbound_frame_size¶

Maximum inbound HTTP/2 frame payload size to accept and advertise via SETTINGS_MAX_FRAME_SIZE.

h2_initial_stream_window_size¶

HTTP/2 per-stream receive flow-control window in bytes (SETTINGS_INITIAL_WINDOW_SIZE). Controls inbound upload throughput; response throughput uses the peer-advertised send window. The default is 8 MiB.

h2_initial_connection_window_size¶

HTTP/2 connection-wide receive flow-control window in bytes. Bounds total charged upload bytes per connection; the default matches the 8 MiB stream window so one upload can use the whole connection budget.

max_request_body_size¶

Maximum request body size in bytes. Use 0 for no limit.

limit_concurrency¶

Maximum number of concurrent ASGI request or session tasks per worker. Use 0 for no limit.

limit_connections¶

Maximum number of live client connections per worker. Use 0 for no limit.

Timeouts¶

Connection-level timeouts in seconds. For the optional timeouts, 0 disables the timer. For timeout_graceful_shutdown, 0 means no graceful wait — stop immediately rather than waiting for in-flight work.

timeout_handshake¶

Maximum time from accepting a connection to a finished PROXY preamble, TLS handshake and protocol preface, in seconds. Use 0 to disable.

timeout_graceful_shutdown¶

Maximum time for workers to finish in-flight requests on shutdown, in seconds.

timeout_keep_alive¶

Idle keep-alive timeout in seconds. Use 0 to disable.

timeout_request_header¶

Idle timeout in seconds while reading an HTTP request head or an HTTP/2 header block. Use 0 to disable.

timeout_request_body_idle¶

Idle timeout in seconds while reading an HTTP request body. Use 0 to disable.

h2_timeout_response_stall¶

Timeout in seconds for HTTP/2 response body bytes pinned behind peer flow control. Use 0 to disable.

WebSocket¶

Limits and keep-alive for RFC 6455 and RFC 8441 WebSockets.

websocket_max_message_size¶

Maximum WebSocket message size in bytes. Defaults to 16 MiB; use 0 for no limit.

websocket_per_message_deflate¶

Whether to negotiate permessage-deflate for WebSockets when the client offers it.

websocket_ping_interval¶

Interval in seconds between server WebSocket ping frames. Use 0 to disable.

websocket_ping_timeout¶

Time limit in seconds to wait for a pong after a server WebSocket ping. Use 0 to disable. No effect while websocket_ping_interval is 0.

Proxy and response headers¶

Trust boundaries with the upstream proxy and default response headers.

proxy_headers¶

Enable forwarding-header processing for peers in forwarded_allow_ips; forwarded_fields selects the facts and dialect.

forwarded_allow_ips¶

Allowed IPs or networks (in CIDR notation) for proxy headers. Use '*' to trust all.

forwarded_fields¶

Forwarding facts to interpret from a trusted proxy: for, proto, host, port, prefix select X-Forwarded-* fields; forwarded selects RFC 7239 Forwarded. The dialects cannot be combined.

proxy_protocol¶

Expect HAProxy's PROXY protocol on inbound connections.

server_header¶

Identify the server in a Server header: off sends none, on sends the name, full adds the version. Any other value goes through --header, which also wins over this.

date_header¶

Whether to add a default Date header when the application sets none.

response_headers¶

Default response headers in lowercase name: value form, added only when the application did not set that name itself. Repeat the flag to add more headers.

Command-only CLI controls¶

These flags control application loading, development reload, or process actions rather than a Config value.

Command-only flags: -h, --help¶

Print command help, then exit.

Command-only flags: -c, --config¶

Select the TOML file; H2CORN_CONFIG selects the same file.

Command-only flags: --version¶

Print the installed h2corn version, then exit.

Command-only flags: --check-config¶

Validate configuration and TLS, then exit.

Command-only flags: --print-config¶

Print the fully resolved configuration, then exit.

Command-only flags: --factory¶

Call the target as a zero-argument app factory.

Command-only flags: --app-dir¶

Import the target from this directory.

Command-only flags: --env-file¶

Load application environment before import.

Command-only flags: --reload¶

Watch application files and restart one development worker.

Command-only flags: --reload-dir¶

Add a development reload directory; repeatable.

Command-only flags: --reload-include¶

Add a development reload glob; repeatable.

Command-only flags: --reload-exclude¶

Add a development reload exclusion; repeatable.

Command-only flags: --host¶

TCP host convenience input for bind; H2CORN_HOST is equivalent when H2CORN_BIND is unset.

Command-only flags: -p, --port¶

TCP port convenience input for bind; H2CORN_PORT is equivalent when H2CORN_BIND is unset.

Building a Config programmatically¶

Config is a frozen dataclass; instantiate it directly or use Config.from_env(), Config.from_mapping(), or Config.from_toml(). See the Config API reference for their signatures.