LangGraph Transparent Proxy (FastAPI)

This service is a transparent proxy in front of a LangGraph API server.

The goal is full API passthrough so agent-chat-ui can point to this service without changing its request paths.

Environment variables

• LANGGRAPH_UPSTREAM_URL (default: http://127.0.0.1:8123)
• LANGGRAPH_UPSTREAM_API_KEY (optional, injected as x-api-key to upstream)
• PROXY_TIMEOUT_SECONDS (default: 300)
• PROXY_CORS_ALLOW_ORIGINS (default: *, comma-separated)
• PROXY_UPSTREAM_RETRIES (default: 1)
• PROXY_LOG_LEVEL (default: INFO)
• API_DOCS_ENABLED (default: false, exposes /docs, /redoc, /openapi.json)
• DEV_AUTH_BYPASS_ENABLED (default: false, local development only; bypasses Keycloak verification)
• DEV_AUTH_BYPASS_MODE (default: fixed, supported: fixed / anonymous)
• DEV_AUTH_BYPASS_SUBJECT (default: dev-local-user, used when mode is fixed)
• DEV_AUTH_BYPASS_EMAIL (optional, used when mode is fixed)
• DEV_AUTH_BYPASS_ROLE (default: owner, supported: owner / admin / member)
• DEV_AUTH_BYPASS_MEMBERSHIP_ENABLED (default: true, bypasses tenant membership/admin checks in platform APIs)
• RUNTIME_ROLE_ENFORCEMENT_ENABLED (default: false, blocks runtime write methods for member role when tenant context exists)
• PLATFORM_DB_ENABLED (default: false)
• PLATFORM_DB_AUTO_CREATE (default: false)
• REQUIRE_TENANT_CONTEXT (default: false)
• DATABASE_URL (required when PLATFORM_DB_ENABLED=true)
• KEYCLOAK_AUTH_ENABLED (default: false)
• KEYCLOAK_AUTH_REQUIRED (default: false)
• KEYCLOAK_ISSUER (required when KEYCLOAK_AUTH_ENABLED=true)
• KEYCLOAK_AUDIENCE (optional but recommended)
• KEYCLOAK_JWKS_URL (optional, defaults to <issuer>/protocol/openid-connect/certs)
• KEYCLOAK_JWKS_CACHE_TTL_SECONDS (default: 300)
• OPENFGA_ENABLED (default: false)
• OPENFGA_AUTHZ_ENABLED (default: false)
• OPENFGA_AUTO_BOOTSTRAP (default: false)
• OPENFGA_URL (default: http://127.0.0.1:18081)
• OPENFGA_STORE_ID (optional, generated by setup script)
• OPENFGA_MODEL_ID (optional, generated by setup script)
• OPENFGA_MODEL_FILE (default: config/openfga-models/v1.json)
• LOGS_DIR (default: logs)
• BACKEND_LOG_FILE (default: backend.log)
• BACKEND_LOG_MAX_BYTES (default: 10485760)
• BACKEND_LOG_BACKUP_COUNT (default: 5)

Run

uv run uvicorn main:app --host 0.0.0.0 --port 2024 --reload

Recommended profiles

Local development (no login required)

PLATFORM_DB_ENABLED=true
PLATFORM_DB_AUTO_CREATE=true
DATABASE_URL=postgresql+psycopg://agent:agent_pwd@127.0.0.1:5432/agent_platform

API_DOCS_ENABLED=true
DEV_AUTH_BYPASS_ENABLED=true
DEV_AUTH_BYPASS_MODE=fixed
DEV_AUTH_BYPASS_SUBJECT=dev-local-user
DEV_AUTH_BYPASS_EMAIL=dev-local@example.com
DEV_AUTH_BYPASS_ROLE=owner
DEV_AUTH_BYPASS_MEMBERSHIP_ENABLED=true

Staging/Production (strict auth)

API_DOCS_ENABLED=false
DEV_AUTH_BYPASS_ENABLED=false
KEYCLOAK_AUTH_ENABLED=true
KEYCLOAK_AUTH_REQUIRED=true

Health check

curl http://127.0.0.1:2024/_proxy/health

Notes

• All incoming paths and methods are forwarded as-is.
• Status code and response headers are preserved (except hop-by-hop headers).
• SSE and long responses are streamed through directly.

Docs

• docs/README.md
• docs/management-console-overview.md
• docs/self-hosted-auth-rbac-mvp.md
• docs/postgres-operations.md
• docs/code-architecture.md
• docs/error-playbook.md
• docs/testing.md
• docs/ci-troubleshooting.md
• docs/logging-system.md
• docs/archive/（历史文档）

Environment templates

• config/environments/.env.dev.example
• config/environments/.env.dev.tunnel.example
• config/environments/.env.staging.example
• config/environments/.env.prod.example