Configuration and Settings

Flasgo applications are configured through the Settings dataclass. You can pass a mapping, settings object, importable settings module, or an existing Settings instance to the app; unknown keys are retained for application-specific use.

Common settings

Setting	Default	Typical use
DEBUG	False	Enables debug-mode behavior and controls default CLI reload
SECRET_KEY	Random URL-safe token	Signs sessions and other sensitive values
ALLOWED_HOSTS	{"127.0.0.1", "localhost"}	Restricts valid host headers to listed hostnames, IP addresses, or .suffix patterns
ENFORCE_ALLOWED_HOSTS	True	Enables host-header rejection
CSRF_ENABLED	True	Controls CSRF enforcement for unsafe methods
CSRF_COOKIE_NAME	"flasgo-csrf"	Sets the CSRF cookie name
CSRF_HEADER_NAME	"x-csrf-token"	Sets the header used for the double-submit token
CSRF_TRUSTED_ORIGINS	set()	Trusts exact origins, https://*.example.com wildcards, bare hosts, or .suffix patterns for unsafe requests
CSRF_CHECK_ORIGIN	True	Requires Origin/Referer validation for unsafe methods
CSRF_REQUIRE_ORIGIN	True	Rejects unsafe requests that omit Origin and Referer
CSRF_COOKIE_SECURE	True	Restricts CSRF cookies to HTTPS
SESSION_COOKIE_NAME	"flasgo-session"	Sets the session cookie name
SESSION_COOKIE_MAX_AGE	604800	Sets session lifetime as a positive integer number of seconds
SESSION_COOKIE_SECURE	True	Restricts session cookies to HTTPS
SESSION_COOKIE_HTTP_ONLY	True	Prevents client-side JavaScript access to session cookies
SESSION_COOKIE_SAME_SITE	"Lax"	Sets the session cookie SameSite value
ENFORCE_NO_STORE_CACHE	True	Forces no-store cache headers unless a response allows public cache
MAX_REQUEST_BODY_BYTES	1048576	Caps request body size
MAX_REQUEST_HEAD_BYTES	16384	Caps the HTTP/WebSocket request head before tracing, routing, or session loading
REQUEST_READ_TIMEOUT_SECONDS	10.0	Bounds request body read time
MAX_MULTIPART_PARTS	1000	Caps multipart parts before full parsing
MAX_FORM_FIELDS	1000	Caps query, URL-encoded, and multipart text fields
MAX_VALIDATION_DEPTH	64	Caps recursive request and response model/collection depth
MAX_VALIDATION_WORK	10000	Caps validation work separately for request binding and response contracts
MAX_VALIDATION_ISSUES	100	Caps collected validation issues; rejected output is not returned to clients
SECURITY_FAILURE_RATE_LIMIT	50	Caps repeated host, CSRF, and authentication/authorization failures per client window
SECURITY_FAILURE_WINDOW_SECONDS	60	Sets the security-failure rate-limit window
LOG_SECURITY_EVENTS	True	Logs security denials and unexpected failures
TRUST_INCOMING_REQUEST_ID	False	Accepts a strictly validated upstream x-request-id when a trusted proxy overwrites it
LOG_FORMAT	"text"	Selects bounded text or JSON framework logs
LOG_LEVEL	"INFO"	Sets the flasgo logger level; standard level names are case-insensitive
WEBSOCKET_ENFORCE_ORIGIN	True	Enforces same-origin or exact allowlist WebSocket handshakes
WEBSOCKET_ALLOWED_ORIGINS	set()	Allows exact cross-origin WebSocket origins
WEBSOCKET_ALLOW_MISSING_ORIGIN	False	Permits missing WebSocket origins for deliberate non-browser clients
WEBSOCKET_MAX_MESSAGE_BYTES	65536	Caps each WebSocket message
WEBSOCKET_MAX_MESSAGES_PER_MINUTE	120	Caps messages per connection and minute
SERVER_LIMIT_CONCURRENCY	1000	Bounds concurrent work in the built-in server
METRICS_ENABLED	False	Enables the optional protected Prometheus endpoint
METRICS_PATH	"/metrics"	Sets the metrics endpoint path
METRICS_BEARER_TOKEN	None	Authenticates metrics scrapes; at least 32 characters when enabled
METRICS_EVENT_LOOP_ENABLED	True	Samples event-loop lag after lifespan startup when metrics are enabled
METRICS_EVENT_LOOP_INTERVAL_SECONDS	0.1	Sets the lag sampling interval; finite numeric values from 0.01 through 60
OTEL_ENABLED	False	Enables optional HTTP and WebSocket tracing
OTEL_SERVICE_NAME	"flasgo"	Sets the OpenTelemetry service name
OTEL_SERVICE_VERSION	None	Adds the deployed service version to telemetry resources
OTEL_TRACE_SAMPLE_RATIO	1.0	Sets the parent-based trace sampling ratio from 0.0 to 1.0
OTEL_EXCLUDED_PATHS	set()	Excludes exact paths or route templates from tracing
OTEL_SET_GLOBAL_PROVIDER	True	Registers a Flasgo-built tracer provider as process-global
ENABLE_DOCS	False	Enables the built-in Swagger UI and OpenAPI JSON endpoints
DOCS_AUTH_BACKEND	None	Protects both documentation endpoints with a registered auth backend
DOCS_PATH	"/docs"	Controls the Swagger UI path
OPENAPI_PATH	"/openapi.json"	Controls the OpenAPI JSON path
API_TITLE	"Flasgo API"	Sets the OpenAPI title
API_VERSION	"0.11.0"	Sets the OpenAPI info version; use your application’s own version when appropriate
API_DESCRIPTION	""	Sets the OpenAPI description
API_SERVERS	[]	Declares root OpenAPI server URLs
SSRF_ENABLED	True	Enables outbound URL validation helpers
SSRF_ALLOWED_SCHEMES	{"http", "https"}	Limits outbound URL schemes
SSRF_ALLOWED_HOSTS	set()	Optionally restricts outbound URL hosts
SSRF_ALLOW_PRIVATE_NETWORKS	False	Allows private-network outbound targets when explicitly needed
SSRF_ALLOW_USERINFO	False	Allows outbound URLs containing credentials
SSRF_ALLOW_UNRESOLVABLE_HOSTS	False	Allows unresolved outbound hosts
SSRF_RESOLUTION_TIMEOUT_SECONDS	5.0	Bounds async outbound DNS resolution; None disables the timeout
SECURITY_HEADERS	Secure header map	Sets response headers applied by default

DOCS_PATH, OPENAPI_PATH, METRICS_PATH, and OTEL_EXCLUDED_PATHS are matched against the path relative to the application’s mount point. When an ASGI server sets a root_path, do not include that prefix in these settings; see Mounted applications.

CORS is configured with the CORSConfig object passed to Flasgo(cors=...) or an individual route’s cors= argument rather than through Settings. It is disabled by default.

Object and constructor configuration

These options are supplied as objects or constructor arguments rather than additional Settings keys:

API	Configuration
Flasgo(rate_limiter=...)	Supply RedisRateLimiter(store, max_keys=10000) for shared route quotas
Flasgo(session_backend=...)	Supply ServerSideSessions(store, max_bytes=65536) for opaque-cookie sessions
RedisStore.from_url(...)	namespace="flasgo", timeout=2, max_value_bytes=65536; owned pool capped at 100 connections
RedisStore(client, ...)	Wrap an application-owned client; also accepts max_value_bytes=65536
Depends(...)	scope="request" or scope="function", with use_cache=True by default
HTTP routes	public=False, response_model=None, and dependencies=()
Streaming constructors	max_chunk_bytes=65536, send_timeout=10, idle_timeout=60, max_duration=3600, cleanup_timeout=10
EventSourceResponse(...)	Also accepts heartbeat=15 and item_model=
NDJSONResponse(...)	Also accepts item_model=

SESSION_COOKIE_MAX_AGE also controls server-side session TTL; modified saves refresh it. Ordinary response contracts use the configured validation limits, while SSE/NDJSON use independent bounded per-item validation budgets. CORS can also be configured on a blueprint, inherited when omitted, replaced explicitly, or disabled with cors=False.

See Shared Quotas and Sessions, Streaming Responses, and Response Contracts for setup, limits, and failure behavior.

Development defaults

Local development examples keep secure behavior visible while allowing fast iteration. Typical settings include DEBUG=True, localhost host allowlists, and non-secure cookies for local HTTP use.

Production baseline

Production settings should move in the opposite direction:

• DEBUG=False
• SECRET_KEY loaded from the environment
• ALLOWED_HOSTS set to real domains
• SESSION_COOKIE_SECURE=True
• CSRF_COOKIE_SECURE=True
• SESSION_COOKIE_HTTP_ONLY=True

Example

import os
from flasgo import Flasgo

app = Flasgo(
    settings={
        "DEBUG": False,
        "SECRET_KEY": os.environ["FLASGO_SECRET_KEY"],
        "ALLOWED_HOSTS": {"api.example.com"},
        "CSRF_ENABLED": True,
        "SESSION_COOKIE_SECURE": True,
        "CSRF_COOKIE_SECURE": True,
        "SESSION_COOKIE_HTTP_ONLY": True,
        "ENABLE_DOCS": False,
    }
)

Loading settings

For larger apps, settings can come from an object or module with uppercase attributes:

from flasgo import Flasgo

app = Flasgo(settings="myproject.settings")

Known framework settings populate the typed settings object. Extra keys remain available through settings.get(key, default) for application code; get() returns framework settings fields and extra keys, never methods of the Settings class.

Boolean fields in Settings and SecurityConfig require actual True or False values. Strings such as "false", integers such as 0 or 1, and None raise TypeError during construction, loading, or later assignment. Parse environment strings explicitly before passing them to Flasgo; Python’s bool("false") is True.

SESSION_COOKIE_NAME and CSRF_COOKIE_NAME must be non-empty ASCII HTTP tokens and are validated when the application is initialized. The event-loop sampling interval rejects booleans, non-finite values, and values outside 0.01 to 60, even when metrics are disabled. See the Metrics Reference for sampler lifecycle and metric meanings.

Flasgo validates important startup settings: SECRET_KEY must be present and at least 32 characters in every mode; SESSION_COOKIE_SAME_SITE must be Lax, Strict, or None, with None requiring secure session cookies; SESSION_COOKIE_MAX_AGE must be a positive integer; ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS entries must use a supported form (see Host and origin entries); request, multipart, form, validation, WebSocket, and server limits must be positive; WebSocket origins must be exact http:// or https:// origins; OpenTelemetry sampling must be between 0.0 and 1.0 and excluded paths must be absolute; SSRF schemes cannot be empty and the async resolution timeout must be positive or None; internal endpoint paths must be distinct absolute paths; and enabled metrics require a bounded bearer-safe ASCII token of at least 32 characters. DOCS_AUTH_BACKEND must name a registered backend when the docs endpoints are used, while every API_SERVERS entry must be a non-empty URL string. LOG_FORMAT must be text or json, and LOG_LEVEL must be a standard Python logging level name in any case, such as "info" or "WARNING".

Host and origin entries

ALLOWED_HOSTS accepts hostnames (api.example.com), IPv4 or IPv6 addresses (127.0.0.1, ::1), and .suffix patterns (.example.com). A suffix pattern matches subdomains such as api.example.com, not the apex example.com; list the apex separately when it is served. Matching is case-insensitive and ignores the port. Wildcards such as "*" and "*.example.com" are rejected at startup; "*" never matched any host in earlier releases. Request Host values must be DNS names or IP literals, so URL delimiters, spaces, and bracketed IPv6 values with a zone ID are rejected, and suffix patterns never match IPv6 literals.

CSRF_TRUSTED_ORIGINS accepts:

Entry	Trusts
https://partner.example	That exact scheme, host, and port
https://*.example.com	Subdomains of example.com over that scheme and port
partner.example	That host over the request’s own scheme
.example.com	Subdomains of example.com over the request’s own scheme

Origins are compared in canonical form, so https://partner.example/ and https://partner.example:443 are the same entry. Bare host and suffix entries never let an HTTPS application trust a plain-HTTP origin. Non-HTTP(S) schemes such as chrome-extension://, and origins with a path, query, or credentials, raise ValueError at startup because they could never match.

For the typed binding model controlled by the validation limits, see Request Data and Dependencies. For tracing behavior, see Observability.

Sources:

• README.md
• flasgo/__init__.py