This is the comprehensive index of every persistent setting BamDude exposes — what each one does, its default, and where it shows up in the UI. Settings live in the settings key-value table; most are surfaced under Settings in the side nav, but a few are read-only mirrors of env vars (the env value wins).
The source of truth is backend/app/schemas/settings.py::AppSettings. If a setting isn't on this page, check there before assuming it doesn't exist — defaults below were verified against that schema.
Server-side default language for all browsers + Telegram chat content + email templates. Frontend reads this on first load and syncs i18n; users can override per-tab in the UI.
time_format
system
system (browser locale), 12h, or 24h. ETA / timestamp display in cards, notifications, and emails.
date_format
system
system (browser locale), us (MM/DD/YYYY), eu (DD/MM/YYYY), iso (YYYY-MM-DD). Controls every user-visible date.
currency
USD
Currency code for cost tracking display.
external_url
empty
Public-facing URL of BamDude. Wins over the APP_URL env var. Used in password-reset / MFA email links, OIDC callback construction, and the Obico cached-frame URL. Set this when you front BamDude with a reverse proxy.
default_printer_id
unset
Default printer for new queue items / Print Now from the file manager.
default_sidebar_order
empty
Admin-set default sidebar item order — JSON {"order": [...ids]} or a JSON array. Empty = use built-in order.
check_updates
true
Periodically check the BamDude release feed for new versions.
check_printer_firmware
true
Periodically check Bambu's firmware feed for printer updates.
include_beta_updates
false
Surface beta releases in the update banner alongside stable releases.
Allow auto-drying between queue items when the next print's filament needs it.
queue_drying_block
false
Block the next print until drying completes (rather than running it in parallel with the current print).
ambient_drying_enabled
false
Auto-dry AMS filament on idle printers when humidity exceeds threshold, regardless of queue state.
print_drying_enabled
false
Allow auto-drying to also fire on a printer that's currently printing, when its model + firmware supports concurrent drying (H2D 01.03.00.00+, H2C/H2S/P2S/H2D Pro 01.02.00.00+, X2D/A2L 01.01.00.00+, X1C 01.11.02.00+). Mid-print drying temp is capped 5 °C below the idle preset (floor 40 °C). See AMS & Humidity.
drying_presets
empty
JSON object of per-filament drying presets. Empty = use built-in defaults.
stagger_enabled
false
Enable staggered start — limit concurrent bed heats across the farm to avoid power spikes.
stagger_concurrent
2
Maximum concurrent printers heating.
stagger_interval_minutes
5
Wait time after a slot frees before the next start.
stagger_wait_for_bed
true
Slot frees when the bed reaches target temp (±1 °C). When off, the slot frees immediately after print start.
per_printer_mapping_expanded
false
Expand the custom filament mapping section by default in the print modal.
Master toggle for server-side slicing. Off = the Slice button is replaced by "open in your desktop slicer".
orcaslicer_api_url
empty
URL of the OrcaSlicer sidecar. Empty falls back to the SLICER_API_URL env var (http://localhost:3003). Validated on save — see the note below.
bambu_studio_api_url
empty
URL of the BambuStudio sidecar. Empty falls back to BAMBU_STUDIO_API_URL (http://localhost:3001). Validated on save.
slicer_stall_timeout_minutes
15
Minutes to keep waiting with no progress from the sidecar (range 1–240). The clock resets on every progress update, so a heavy model that keeps reporting runs to completion. On a sidecar too old to report progress it bounds total slicing time instead.
Addresses you type in are validated
The two slicer URLs, the Home Assistant URL and the Obico detection endpoint
are all checked before they are saved. A mistyped or hostile value could point
BamDude at somewhere it should never fetch — most notably the cloud metadata
address, which is the standard way credentials get read out of a server.
Addresses on your own machine or home network stay allowed, because that is
where these services normally live. What is refused: a non-web address, an
address written as a plain number, a multicast address, and the cloud metadata
endpoints. The single-sign-on issuer address, which must be reachable on the
public internet, is checked by the stricter rule it always should have used.
Spool remaining percentage at which filament_low notifications fire. Range 0.1 – 99.9.
runout_zero_point_enabled
true
Close a spool at exactly its label weight when the printer reports an unambiguous filament runout.
ams_sync_bidirectional
true
Let idle AMS readings correct a Bambu-tagged spool's weight downward too (a value must repeat across two reports a minute apart).
runout_purge_grams
0
Grams charged to the backup spool for the purge of an AMS auto-switch. 0 disables it.
usage_events_retention_hours
72
How long a finished print's usage-event journal (runout/tray timeline) is kept for troubleshooting.
disable_filament_warnings
false
Master mute for low / out-of-filament alerts.
prefer_lowest_filament
true
After compatibility and exact-colour preference, auto-assignment favours the lowest remaining source. Tracked AMS spools use grams; firmware-only sources use percentage in a separate tier.
default_filament_cost
25.0
Per-kg fallback cost when a spool's cost field is unset.
auto_add_unknown_rfid
true
Auto-add a spool to inventory when an AMS reads an unknown RFID tag. Off → a confirmation card (material / colour pre-filled) is shown instead of silent creation. See Spool Inventory.
ams_humidity_good
40
Green-zone humidity threshold (%) on AMS cards (≤ this value).
ams_humidity_fair
60
Yellow-zone humidity threshold (≤ this value). Above is red.
ams_humidity_thresholds
empty
JSON map of per-filament-type humidity trigger thresholds for auto-drying + alarms — {"default": int, "PLA": int, "ASA": int, …}. Empty = fall back to ams_humidity_fair for every type. A multi-material AMS resolves to the strictest (lowest) across its loaded spools.
ams_temp_good
28.0
Green-zone temperature threshold (°C) on AMS cards.
ams_temp_fair
35.0
Yellow-zone temperature threshold. Above is red.
ams_history_retention_days
30
How many days of AMS history to keep before pruning.
inbox_retention_days
30
How many days of in-app notification-centre history each person keeps. Range 1-365. Swept once a day, read or not.
log_retention_days
7
Retention limit for daily bamdude-YYYY-MM-DD.log archives. Range 1–365. Excess archives are removed at the next successful rotation. See System info → Log rotation.
bed_cooled_threshold
35.0
Bed temperature (°C) at which the bed_cooled notification fires.
Enable MQTT publishing — republish printer state to an external MQTT broker.
mqtt_broker
empty
Broker hostname or IP.
mqtt_port
1883
Broker port. TLS deployments typically use 8883.
mqtt_username / mqtt_password
empty
Broker auth. Password is encrypted at rest.
mqtt_use_tls
false
Use TLS for the MQTT broker connection.
mqtt_topic_prefix
bambuddy
Prefix for all republished topics. Inherited from upstream Bambuddy — change to bamdude on fresh installs if you prefer.
ftp_retry_enabled
true
Retry FTP 3MF downloads when the printer was unreachable at print start. See Print Archive.
ftp_retry_count
3
Maximum retries per attempt cycle (1–10).
ftp_retry_delay
2
Seconds between retries (1–30).
ftp_timeout
30
Seconds a single FTP socket operation may sit with no data arriving (10–300). It bounds a stalled transfer, not a slow one — a 3MF download that keeps arriving is left to finish however long it takes. See Print Archive.
When true, unknown Telegram chats are auto-registered as inactive (pending admin activation). When false, unknown chats are rejected outright. There is no separate "approval" mode — the auto-register-then-activate flow is what true does.
user_notifications_enabled
true
Enable per-user email notifications for prints the user owns (requires Advanced Authentication).
LDAP server URL (e.g. ldap://ldap.example.com:389).
ldap_security
starttls
starttls or ldaps.
ldap_bind_dn
empty
Bind DN for searches (e.g. cn=admin,dc=example,dc=com).
ldap_bind_password
empty
Encrypted bind password.
ldap_search_base
empty
Search base DN (e.g. ou=users,dc=example,dc=com).
ldap_user_filter
(sAMAccountName={username})
LDAP user search filter. {username} is replaced with the login username. The default targets Active Directory; for OpenLDAP, switch to (uid={username}).
ldap_group_mapping
empty
JSON object mapping LDAP group DNs to BamDude group names. Empty = no group sync.
ldap_auto_provision
false
Auto-create the BamDude user on first successful LDAP bind.
ldap_default_group
empty
Fallback BamDude group name when an LDAP user has no mapped groups. Empty = no fallback (login fails).
Poll cadence for mains-powered Zigbee sensors (jittered like the plug poller). Battery sensors are never polled — they sleep.
zigbee_sensor_reporting
empty
JSON blob of per-measurement reporting defaults ({"temperature": {"min_interval": …, "max_interval": …, "reportable_change": …}, …}) applied to devices with no override of their own. Empty, or any missing field, falls back to the registry defaults.
zigbee_sensor_stale_multiplier
2
A reporting sensor's value older than this multiple of its max_interval counts as stale ("sensor went silent"). Per-device staleness override wins; polled devices keep a fixed 120 s window.
A couple of auth settings are editable from the UI (Settings → Users):
Key
Default
Effect
session_max_hours
720
Admin ceiling on session lifetime (the refresh-token TTL), in hours. Range 1–720; default 720 h (30 days) preserves remember-me. Applied to existing sessions at their next refresh. Set via the Session Policy card. See Authentication.
local_login_enabled
true
Allow username + password login on /auth/login. Turn off when only SSO should be usable (guarded: needs ≥ 1 enabled OIDC provider and your own account OIDC-linked). Env BAMDUDE_LOCAL_LOGIN=true bypasses this at the route level for recovery.
The rest are read-only env mirrors — set them via environment variables. See Installation for the env-var details.
Setting
Source
Effect
Setup gate active
users table
Drops automatically when the first admin is created. The reset_admin CLI clears it for recovery.
JWT signing key
JWT_SECRET_KEY env or data/.jwt_secret file
Auto-generated on first boot if neither is present.
Refresh-cookie Secure flag
AUTH_REFRESH_COOKIE_SECURE env
Auto-detected from request scheme when unset.
Trusted reverse-proxy IPs
TRUSTED_PROXY_IPS env
Comma-separated. Required for accurate per-IP rate limiting behind nginx / Caddy.
MFA-secret encryption key
MFA_ENCRYPTION_KEY env
Plaintext fallback works without it but logs a warning.