Settings Reference¶

Django-Bolt settings are configured in your Django settings.py file.

CORS settings¶

CORS_ALLOWED_ORIGINS¶

List of allowed origins for CORS.

CORS_ALLOWED_ORIGINS = [
    "https://example.com",
    "https://app.example.com",
]

CORS_ALLOW_ALL_ORIGINS¶

Allow all origins (development only).

CORS_ALLOW_ALL_ORIGINS = True

CORS_ALLOW_CREDENTIALS¶

Allow credentials in CORS requests.

CORS_ALLOW_CREDENTIALS = True

CORS_ALLOW_METHODS¶

Allowed HTTP methods for CORS.

CORS_ALLOW_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]

CORS_ALLOW_HEADERS¶

Allowed headers in CORS requests.

CORS_ALLOW_HEADERS = ["Content-Type", "Authorization", "X-Requested-With"]

CORS_EXPOSE_HEADERS¶

Headers exposed to the browser.

CORS_EXPOSE_HEADERS = ["X-Total-Count", "X-Page-Count"]

CORS_MAX_AGE¶

Preflight cache duration in seconds.

CORS_MAX_AGE = 86400  # 24 hours

File upload settings¶

BOLT_MAX_UPLOAD_SIZE¶

Maximum file upload size in bytes. Requests exceeding this limit will be rejected with a 413 error before any per-view validation occurs.

BOLT_MAX_UPLOAD_SIZE = 10 * 1024 * 1024  # 10 MB

You can also use the FileSize enum for readability:

from django_bolt import FileSize

BOLT_MAX_UPLOAD_SIZE = FileSize.MB_10

# settings.py
BOLT_MAX_UPLOAD_SIZE = FileSize.MB_50  # 50 MB global limit

# In your view
file: Annotated[UploadFile, File(max_size=FileSize.MB_1)]  # 1 MB per-view limit

ASGI mount settings¶

BOLT_ASGI_MOUNT_TIMEOUT¶

Maximum time (seconds) to wait for a mounted ASGI app to complete.

BOLT_ASGI_MOUNT_TIMEOUT = 30

Default: 30

When exceeded, Django-Bolt returns 504 Gateway Timeout for the mounted request.

BOLT_MEMORY_SPOOL_THRESHOLD¶

Size threshold before file uploads are spooled to disk. Files smaller than this are kept in memory; larger files are written to a temporary file on disk.

BOLT_MEMORY_SPOOL_THRESHOLD = 5 * 1024 * 1024  # 5 MB

Default: 1048576 (1 MB)

This setting controls memory usage during file uploads:

• Lower values reduce memory usage but increase disk I/O
• Higher values improve performance for medium-sized files but use more memory

File serving settings¶

BOLT_ALLOWED_FILE_PATHS¶

Whitelist of directories for FileResponse.

BOLT_ALLOWED_FILE_PATHS = [
    "/var/app/uploads",
    "/var/app/public",
]

When set, FileResponse only serves files within these directories.

Authentication settings¶

Django-Bolt uses Django's SECRET_KEY for JWT signing by default.

SECRET_KEY = "your-secret-key"

Override per-backend:

JWTAuthentication(secret="custom-jwt-secret")

BOLT_AUTHENTICATION_CLASSES¶

Default authentication backends applied to all endpoints.

Default: [] (no authentication)

BOLT_DEFAULT_PERMISSION_CLASSES¶

Default permission guards applied to all endpoints.

Default: [AllowAny()] (all endpoints publicly accessible)

See Global authentication for usage and examples.

Logging settings¶

Django-Bolt integrates with Django's logging system.

LOGGING = {
    "version": 1,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "loggers": {
        "django_bolt": {
            "handlers": ["console"],
            "level": "INFO",
        },
    },
}

Django signals settings¶

BOLT_EMIT_SIGNALS¶

Enable Django request_started and request_finished signal emission.

BOLT_EMIT_SIGNALS = True

Default: False

Django-Bolt disables signals by default for maximum performance. Enable this setting when:

• Using CONN_MAX_AGE with a value other than None (required for connection recycling)
• Using third-party packages that depend on request signals (e.g., django-debug-toolbar)
• Implementing custom signal receivers for request lifecycle events

CONN_MAX_AGE = 600
BOLT_EMIT_SIGNALS = True  # Required!

See Django Signals for detailed documentation.

Dev reload settings¶

BOLT_DEV_FORCE_POLLING¶

Force the --dev auto-reloader to use file-system polling instead of native OS file events.

BOLT_DEV_FORCE_POLLING = True

Default: False

Django-Bolt's dev reloader uses the notify crate's recommended watcher (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows). These backends are fast but rely on kernel events, which do not propagate across some bind-mount boundaries — most notably a Linux container running on a Windows host where the source tree is mounted from the host filesystem.

Enable polling when:

• Running runbolt --dev inside a Docker container on a Windows host with the project bind-mounted from the host
• Working on a remote / network filesystem that does not deliver native change events
• Native file events appear to fire inconsistently for your editor or sync tool

Polling is checked every 500 ms. It uses more CPU than native events on large source trees but is the only reliable option when kernel events are unavailable.

This setting only affects runbolt --dev; production servers do not watch files.

runbolt command options¶

The runbolt management command accepts these options:

Examples¶

# Development with auto-reload
python manage.py runbolt --dev

# Production with scaling
python manage.py runbolt --processes 4 --workers 2

# Custom bind address
python manage.py runbolt --host 127.0.0.1 --port 3000

The dev reloader follows a Django-style source watch list: Python modules and HTML templates are reloaded automatically, while runtime files like logs, databases, and other generated artifacts do not trigger reloads.

OpenAPI settings¶

Configure via OpenAPIConfig in your api.py:

from django_bolt import BoltAPI
from django_bolt.openapi import OpenAPIConfig

api = BoltAPI(
    openapi_config=OpenAPIConfig(
        title="My API",
        version="1.0.0",
        description="API description",
        enabled=True,
        docs_url="/docs",
        openapi_url="/openapi.json",
        django_auth=False,
    )
)

Content Security Policy (CSP) settings¶

Django-Bolt applies CSP headers to static files served by the Rust server using Django 6.0+'s native SECURE_CSP setting.

SECURE_CSP¶

from django.utils.csp import CSP

SECURE_CSP = {
    "default-src": [CSP.SELF],
    "script-src": [CSP.SELF],
    "style-src": [CSP.SELF, CSP.UNSAFE_INLINE],
    "img-src": [CSP.SELF, "data:"],
}

See Static Files - Content Security Policy for full documentation.

Compression settings¶

Configure via CompressionConfig:

from django_bolt import BoltAPI, CompressionConfig

api = BoltAPI(
    compression=CompressionConfig(
        backend="brotli",      # "brotli", "gzip", or "zstd"
        minimum_size=1000,     # Minimum size to compress (bytes)
        gzip_fallback=True,    # Fall back to gzip
    )
)

All settings reference¶