vgi.serve

Module overview

Zero-boilerplate CLI for serving VGI workers.

Loads any Worker by module reference and serves it — stdio by default (matching vgi-rpc’s run_server()), --http for cloud deployment.

Usage:

# Stdio (default) — for subprocess/pipe use by vgi-client or DuckDB
vgi-serve my_worker.py
vgi-serve my_app.workers:ProductionWorker

# HTTP — for cloud deployment
vgi-serve my_worker.py --http
vgi-serve my_worker.py --http --host 0.0.0.0 --port 8080

Programmatic API:

from vgi.serve import create_app, load_worker_class

app = create_app(load_worker_class("my_app:MyWorker"))
# Use with gunicorn: gunicorn app -w 4 -b 0.0.0.0:8080

function create_app

source

create_app(
worker_cls: type[Worker],
,
prefix: str = ‘’,
cors_origins: str = ‘’,
describe: bool = True,
signing_key: bytes | None = None,
log_level: int = logging.INFO,
authenticate: Callable[[falcon.Request], AuthContext] | None = None,
proxy_proof_required: bool | None = None,
oauth_resource_metadata: Any = None,
otel_config: OtelConfig | None = None,
max_stream_response_bytes: int | None = None,
max_externalized_response_bytes: int | None = None,
introspect_principals: Iterable[str] | None = None,
introspect_rate_limit: int | None = None,
) -> falcon.App[Any, Any]

Create a WSGI app for a VGI worker.

Returns a standard WSGI app usable with gunicorn, uwsgi, waitress, or any WSGI server.

Parameters

worker_cls

The Worker subclass to serve.

prefix

URL prefix for RPC endpoints.

cors_origins

Allowed CORS origins.

describe

Enable worker + API description pages.

signing_key

Shared signing key for state tokens. When None, a random per-process key is generated (tokens are invalid across workers). Set via VGI_SIGNING_KEY env var or pass explicitly for multi-process deployments.

log_level

Logging level for the worker instance.

authenticate

Optional callback that validates each HTTP request and returns an AuthContext. When None, all requests are anonymous.

proxy_proof_required

Whether to advertise VGI-Proxy-Proof-Required so a proxy can confirm this worker actually enforces the proof it mints. None (the default) derives it from VGI_PROXY_PROOF_MODE, which is also where the gate itself comes from — so the advertisement cannot drift from the posture. Pass a bool only when supplying a hand-built gate via authenticate.

oauth_resource_metadata

Optional OAuthResourceMetadata for RFC 9728 discovery endpoint.

otel_config

Optional OpenTelemetry configuration. When provided, instruments the RPC server with tracing and/or metrics.

max_stream_response_bytes

HTTP-only. When set, producer stream responses may pack multiple Arrow batches into a single HTTP response up to this byte budget before emitting a continuation token. Default None keeps the current one-batch-per-response behaviour.

max_externalized_response_bytes

HTTP-only. Cap on a single externalized response — the payload uploaded to blob storage and replaced on the wire by a pointer. Set it to whatever a load balancer, API gateway or object-store policy in front of this worker will actually carry. Unlike max_stream_response_bytes this is a hard cap on every method type with no continuation escape, because bytes already uploaded cannot be un-uploaded. None (the default) means no cap.

introspect_principals

Principals permitted to call introspect_token. Only consulted when the worker class overrides resolve_token. None reads VGI_INTROSPECT_PRINCIPALS.

introspect_rate_limit

Introspection requests allowed per caller per second. None reads VGI_INTROSPECT_RATE_LIMIT, defaulting to 20.

Returns

A Falcon WSGI application.

function export_serve_config

source

export_serve_config(
*,
worker_ref: str,
prefix: str,
cors_origins: str,
describe: bool,
log_level: int,
max_stream_response_bytes: int | None,
max_externalized_response_bytes: int | None,
) -> None

Publish the parent’s serve configuration for worker processes to read.

Parameters

worker_ref

The worker reference string the parent was given (module:Class, module, or ./file.py). Passed rather than the resolved class because a child has to import it itself.

prefix

URL prefix for RPC endpoints.

cors_origins

Allowed CORS origins.

describe

Whether to enable the worker + API description pages.

log_level

Logging level for the worker instance.

max_stream_response_bytes

Producer-stream response budget, or None.

max_externalized_response_bytes

Externalized-response cap, or None.

function load_worker_class

source

load_worker_class(reference: str) -> type[Worker]

Load a Worker subclass from a module reference string.

Accepts several reference formats:

• module:ClassName — import module and return ClassName
• module — import module and auto-discover the single Worker subclass
• ./path/to/file.py or path.py — load from file path
• ./path/to/file.py:ClassName — load from file path, return ClassName

Auto-discovery finds Worker subclasses defined in the module (ignores imported ones by checking __module__).

Parameters

reference

Module reference string.

Returns

The Worker subclass.

Raises

SystemExit

If the reference is invalid, module can’t be loaded, no Worker subclass is found, or multiple are found.

function main

source

main() -> None

CLI entry point for vgi-serve.

function resolve_shared_signing_key

source

resolve_shared_signing_key(
*,
propagate_to_children: bool,
) -> tuple[bytes, bool]

Resolve the signing key every process in this deployment must agree on.

The key seals HTTP state tokens and catalog opaque data. Every process that might serve a continuation for a stream has to hold the same one: a token sealed by one key fails the AEAD check under another, and the failure is load-dependent rather than deterministic. A client whose connection stays pinned to one process never notices; one that reconnects mid-stream – seek_to_token, a load balancer, a respawned worker – hits an intermittent 400 that looks like flakiness.

Resolution:

• VGI_SIGNING_KEY set: use it. Tokens survive restarts and are valid across every process configured with the same value. This is the only correct setting for a load-balanced or multi-instance deployment, because nothing here can reach a peer we did not start.
• Unset: mint a random key for this deployment. Tokens are then valid for the life of these processes and clients re-ATTACH after a restart.

Parameters

propagate_to_children

True when this process will start worker processes that import the app themselves (a pre-fork server). A minted key is then exported to the environment so those children inherit it instead of each minting its own – which is the bug this function exists to prevent.

Returns

(key, is_ephemeral). is_ephemeral is True when the key was minted here rather than configured, so callers can say so out loud.

function wsgi_app_factory

source

wsgi_app_factory() -> Any

Build the WSGI app from the environment — the pre-fork worker entry point.

Granian is pointed at vgi.serve:wsgi_app_factory and calls this once per worker process. Everything it needs was published by :func:export_serve_config in the parent, plus VGI_SIGNING_KEY, which the parent minted and exported so every worker seals state tokens with the same key.

Returns

The Falcon WSGI application.

Raises

RuntimeError

Called without a parent having exported the config, which means this was invoked directly rather than by vgi-serve.