Skip to content

Settings

The following options can be used to configure pyvoy when using the pyvoy CLI. Most parameters have a corresponding keyword argument when using PyvoyServer programmatically. Envoy can also be invoked directly with pyvoy for even further customization.

Application

  • app - A single positional argument that is the Python application to run, in the format <module>:<attribute>, e.g., myapp.server:app. If attribute matches app, it can be omitted, e.g., myapp.server.
  • --interface - One of asgi or wsgi to indicate the type of application being served. Default: asgi.
  • --root-path - The root path the application is mounted on if behind a reverse proxy.
  • --worker-threads - The positive number of Python threads to serve requests with. When using ASGI, this should generally be kept at 1 unless using free-threaded Python. Default: 1 for ASGI, 200 for WSGI.
  • --[no-]lifespan - Whether to require or disable ASGI lifespan support. By default, we try to run the application with lifespan and ignore any exception that is raised. If enabled explicitly, an exception will cause the server to fail to start. If disabled, lifespan will not be run at all.
  • --loop - The event loop to run ASGI applications on, one of asyncio, uvloop, winloop, zuvloop, or trio. asyncio is the standard library event loop. Only the default event loop is installed with pyvoy, others must be installed separately. Applications built on anyio, such as Starlette and FastAPI, run on any of them. Default: uvloop, or winloop on Windows.
  • --additional-mount - Can be specified any number of times to mount additional applications in the server. Takes a value in the format app=path=interface, with the path being where the application is mounted. For more complicated routing, it is recommended to invoke Envoy directly with a full config.

Static files

pyvoy can serve static files from disk alongside your application, backed by the envoy-files dynamic module. This can be useful for example to serve a single-page app bundle along with an API in the same server. Using a static mount will be several times faster than serving in Python with e.g., Starlette.

  • --static-mount - Can be specified any number of times to serve a directory of static files. Takes a value in the format prefix=root[=opt:val,opt:val,...], where prefix is the URL path prefix to mount at and root is the directory to serve (~ is expanded). The prefix is stripped before resolving files under root, so --static-mount /assets=./dist serves ./dist/app.js at /assets/app.js. Supported options:
    • directory:index|listing|deny - Behavior when a directory has no matching index file. Default: deny.
    • index:a.html;b.html - Files (;-separated) attempted in order for directory requests. Default: index.html.
    • precompressed:br;gzip;zstd - Precompressed variants (;-separated) served when available. Default: br;gzip.
    • dotfiles:true|false - Whether to serve path segments beginning with a dot. Default: false.

For cache_control, mime_overrides, and other envoy-files knobs, use PyvoyServer directly with StaticMount, which also exposes an options dictionary as an escape hatch for any remaining envoy-files setting.

Server

  • --address - The address to listen on. --address 0.0.0.0 would listen on all addresses, which is commonly needed in container deployments like k8s. Default: 127.0.0.1.
  • --port - The port to listen on. If 0, an available port will be automatically used. Default: 8000.
  • --tls-key / --tls-cert - Paths to the TLS key and cert files to enable listening with TLS.
  • --tls-ca-cert - Path to the TLS cert to verify client certificates with.
  • --tls-require-client-certificate - Whether a valid TLS client certificate must be present to connect, for mTLS. Has no effect if --tls-ca-cert is not provided.
  • --tls-port - Must be used with --tls-key / --tls-cert. If set, --port will listen with plaintext and this port will in addition listen with TLS.
  • --tls-disable-http3 - By default, if TLS is enabled, the port will also listen on UDP for HTTP/3 connections. Set to disable support for HTTP/3 connections.
  • --content-encodings - A comma-separated list of content encodings, out of gzip, br, and zstd, to compress responses with, in order of preference, for example zstd,br,gzip. Responses that are already encoded, such as precompressed static files, are passed through untouched. Default: unset, meaning responses are not compressed.

The client's Accept-Encoding header decides which of the offered encodings is used: the one the client gives the highest q-value wins, and Accept-Encoding: * selects the first encoding in the list. Unfortunately, due to an Envoy limitation, only the first entry in the list is a true server-side preference - it is chosen whenever the client accepts it at the same q-value as another offered encoding.

When this is set, applications no longer receive the Accept-Encoding request header so compression is handled entirely in Envoy.

HTTP Client

  • --upstream - Defines an upstream that can be used with the pyvoy HTTP Client. Every upstream defines a name and its URL, for example auth-service=http://auth.svc:8080. To enable TLS, specify https:// instead - the server's CA cert will be used to authenticate backends, and if TLS key / cert are provided, they will be sent for mTLS.

WebSockets

  • --websockets - Enables support for ASGI WebSockets. The primary application (the only application or first mount) must use ASGI and handles all WebSocket connections; path-based application mount routing does not apply. Not enabled by default.
  • --websockets-max-message-size - Sets the non-negative maximum WebSocket message size in bytes. Default: 64 MiB.
  • --websockets-compression - Sets whether to enable WebSocket per-message deflate compression. Default: enabled.

OpenTelemetry

Traces and metrics are each exported when their OTEL_TRACES_EXPORTER / OTEL_METRICS_EXPORTER variable includes otlp, or when it is unset and an OTLP endpoint is set with OTEL_EXPORTER_OTLP_ENDPOINT or its signal-specific variant. With nothing configured, nothing is exported.

When traces are exported, Envoy starts a server span for each request and applications receive its trace context in the traceparent request header. Instrumentation such as opentelemetry-instrumentation-asgi then continues the trace from Envoy's span without any extra configuration.

Envoy's stats are exported as metrics with an envoy. prefix, for example envoy.http.downstream_rq_total and envoy.http.downstream_rq_time, with Envoy's stat tags as attributes.

The following variables are recognized, with signal-specific variants such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT where the specification defines them:

  • OTEL_SDK_DISABLED, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES
  • OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER - otlp, otlp_proto_grpc, otlp_proto_http, or none
  • OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_INSECURE
  • OTEL_EXPORTER_OTLP_PROTOCOL - grpc or http/protobuf. Default: grpc, matching the OpenTelemetry Python SDK
  • OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_KEY - As with upstreams, an https endpoint's certificate is only verified when a CA certificate is set
  • OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG - always_on, always_off, traceidratio, and their parentbased_ variants. Default: parentbased_always_on. Envoy traces are not exported with other samplers
  • OTEL_METRIC_EXPORT_INTERVAL - Must be less than 300000 (5 minutes)
  • OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE
  • OTEL_EXPORTER_OTLP_TIMEOUT - In seconds like the OpenTelemetry Python SDK, rather than the specification's milliseconds. Default: 10

The variables are read when the Envoy config is generated, so a config printed with --print-envoy-config uses the values at the time it was printed.

Development

  • --reload - Whether to automatically restart the server on code changes. Requires the watchfiles dev dependency to be installed.
  • --reload-dirs - Directories to watch for code changes. Default: current directory
  • --reload-includes - File patterns to include for reload. Default: *.py
  • --reload-excludes - File patterns to exclude from reload. Default: .*,*.py[cod],*.sw.*,~*

Envoy

pyvoy can be used by directly invoking Envoy with an appropriate YAML config. This can be useful for production deployments by unlocking all the features of Envoy itself. The pyvoy CLI captures common configuration options, and more may be added with popular demand, but it is impossible to expose every single feature via a CLI option.

These flags cause the CLI to print output rather than start a server to help setup for running Envoy directly.

  • --print-envoy-config - Prints the Envoy config YAML that would be used if actually starting the server.
  • --print-envoy-entrypoint - Prints a shell script with environment variables included needed for setting up pyvoy.

You can see more details in deployment.