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.

Policy refresh

Runtime Guard periodically refreshes effective policies using the polling interval supplied during bootstrap. Policy changes therefore take effect without restarting the protected application. The longer cache lifetime remains available for last-known-good policy recovery when Zubbl is temporarily unavailable.