FluxLit documentation

FastAPI and Streamlit on one public port. FluxLit gives you one app object, one gateway URL, and a managed Streamlit sidecar so your API and UI deploy together.

Install: pip install fluxlit (Python 3.10+) · PyPI · GitHub

Tip

New here? Follow Quick start first. You should have a working app at http://127.0.0.1:8000 in a few minutes.

Choose your path

I want to…

Start here

Run a minimal API + Streamlit app locally

Quick start

Understand how requests reach FastAPI vs Streamlit

Architecture

Configure ports, env vars, proxy paths, or reload behavior

Configuration · Command-line interface

Deploy with containers, Kubernetes, platforms, or a reverse proxy

Deployment · Platform recipes · Production TLS and edge headers

Operate the app with logs, metrics, probes, and runbooks

Observability · Runbooks

Add JWT, OIDC, or call secured APIs from Streamlit

Security architecture · Auth recipes

Survive full page reload without cookies (URL + server store)

URL session continuity (no cookies) · URL sessions, query tokens, and email links (security)

Deep links, query params, and invite-style URLs to Streamlit

Deep links and query parameters

Test API routes, Streamlit pages, multipage nav, and query params in Pytest

Testing

Copy-paste deployment and header patterns

Cookbook

Call the FastAPI app from Streamlit pages (client, bearer, errors)

Streamlit → FastAPI: ApiClient patterns

FastAPI-style typing, Depends, query models, manifests

Streamlit pages: typing, Depends, and manifests

Fix imports, 503 readiness, WebSockets, or wrong API paths

Troubleshooting · fluxlit doctor

Browse API reference, support policy, or release history

Python API reference · Support matrix · Changelog

Ideas to remember

  • Gateway: Uvicorn serves the public URL; Streamlit runs in a child process on an internal port.

  • Routing: /api/* goes to FastAPI. Everything else, including /_stcore/... WebSockets, is proxied to Streamlit.

  • From Streamlit, call the API with the injected client using paths like "/users", not "/api/users". The runtime sets the base URL for you. For bearer auth, use with_bearer() or for_fluxlit(); see Streamlit → FastAPI: ApiClient patterns and Auth recipes.

  • Secured routes: the default page client has no Authorization header unless you add it per request or use with_bearer / for_fluxlit.

  • Gateway → Streamlit headers: by default, arbitrary browser headers are not merged onto the internal HTTP hop to Streamlit. Optional 0.10+ allowlists (FLUXLIT_GATEWAY_FORWARD_CLIENT_HEADERS_TO_STREAMLIT) merge named non-secret headers for correlation; credential and hop-by-hop names are rejected from the allowlist. 0.11+ surfaces those rejected names in fluxlit config warnings and a fluxlit doctor row so misconfigurations are obvious. 0.12+ adds fluxlit doctor --strict to fail CI on broad proxy allowlists and public_base_url path mismatches vs the mount — see Command-line interface. Treat forwarding as high risk and read Security architecture before enabling. Prefer set_page_header_context() from trusted FastAPI code for sensitive deployments.

  • Health: GET /api/healthz checks the API. GET /api/readyz checks the Streamlit sidecar when the gateway is managing one.

  • Operations: request IDs, structured logs, Prometheus metrics (with stability notes in Support matrix and Observability), gateway limits, graceful shutdown, Kubernetes guidance, and multi-replica checklists are documented in Observability and Deployment. Unified FluxLit ASGI rejects Uvicorn --workers > 1 at lifespan startup unless FLUXLIT_ALLOW_UNIFIED_UVICORN_MULTIWORKER=1 (unsupported); scale with replicas instead — see Deployment and URL session continuity (no cookies) for session stickiness vs external stores.

  • Tests: use FluxLitTestClient for gateway-aware API tests and streamlit_main_path() / AppTest for thin Streamlit smoke tests; helpers like apptest_select_page help exercise multipage st.navigation and query params. See Testing and Deep links and query parameters.

Note

Contributors: the default test command and CI matrix are in Testing. Repository guidelines: Contributing.

User guide

Reference