Zubbl Runtime

Core Python runtime client for Zubbl Runtime Guard.

zubbl-runtime provides the shared runtime, bootstrap, signing, policy enforcement, resilience and transport components used by the Zubbl framework adapters.

Requirements

• Python 3.10+

Installation

pip install zubbl-runtime

Most developers should install a framework adapter such as zubbl-fastapi, which installs this package automatically.

API keys

Supply the API key through the application environment. Never place a real Zubbl key in source code, Git, logs or screenshots.

export ZUBBL_API_KEY="zubbl_sk_..."

For local development, use an uncommitted environment file loaded by your application. Hosted applications should use their platform-managed environment variables or secrets.

Bootstrap errors

BootstrapError.retryable distinguishes temporary network, timeout, HTTP 408, HTTP 429 and HTTP 5xx failures from non-retryable credential or configuration errors. This bootstrap policy is separate from the remotely supplied runtime_fail_mode.

Trusted network context

When a framework adapter supplies a client IP, Runtime Guard uses a signed Zubbl Worker request to resolve trusted country, ASN, VPN and hosting information before local policy enforcement. Results are cached by IP to avoid a remote lookup for every request.

If trusted network information is temporarily unavailable, country remains XX. Geo policies allow unknown countries by default; applications can explicitly set unknown_country_default to deny when strict handling is required.

This normal path does not require trusting user-supplied proxy headers.