Bengal surfaces contextual tips when running in containers, WSL, or other environments. Hints help you avoid common configuration mistakes and improve the development experience.
When Hints Appear
Hints are shown during:
- Build — After
bengal buildcompletes (as a tip line) - Serve — In the dev server startup message
- Config — When loading configuration (logged via structured logger)
At most one hint is shown per context by default. Usemax_hintsin the collector API for more.
Available Hints
| Hint ID | Condition | Message |
|---|---|---|
docker_baseurl |
Running in Docker with empty baseurl | SetBENGAL_BASEURLfor correct canonical URLs |
kubernetes_baseurl |
Running in Kubernetes with empty baseurl | SetBENGAL_BASEURLfor correct canonical URLs |
wsl_watchfiles |
WSL + dev server | If live reload is unreliable, tryWATCHFILES_FORCE_POLLING=1 |
dev_server_container |
Docker + host=localhost + serve | For host access, usebengal serve --host 0.0.0.0 |
gil |
GIL enabled (Python free-threading) | Tip about GIL status and migration |
Opt-Out
Disable hints via environment variables:
| Variable | Effect |
|---|---|
BENGAL_HINTS=0 |
Disable all hints |
BENGAL_NO_HINTS=1 |
Disable all hints |
BENGAL_HINT_DOCKER_BASEURL=0 |
Disable thedocker_baseurlhint |
BENGAL_HINT_KUBERNETES_BASEURL=0 |
Disable thekubernetes_baseurlhint |
BENGAL_HINT_WSL_WATCHFILES=0 |
Disable thewsl_watchfileshint |
BENGAL_HINT_DEV_SERVER_CONTAINER=0 |
Disable thedev_server_containerhint |
BENGAL_HINT_GIL=0 |
Disable the GIL hint |
Per-hint opt-out uses the patternBENGAL_HINT_{ID}=0 where {ID} is the hint ID in UPPER_SNAKE_CASE (e.g. docker_baseurl → DOCKER_BASEURL).
Examples
Docker Build
When building inside Docker withoutBENGAL_BASEURLset:
Tip: Running in Docker. Set BENGAL_BASEURL for correct canonical URLs.
WSL Dev Server
When runningbengal serveon WSL with unreliable file watching:
Tip: On WSL. If live reload is unreliable, try WATCHFILES_FORCE_POLLING=1
Kubernetes
When running in a Kubernetes pod without baseurl:
Tip: Running in Kubernetes. Set BENGAL_BASEURL for correct canonical URLs.