Skip to content

Settings reference ​

Every user-adjustable setting, its YAML key, its environment variable and its value in the Docker configuration (config/docker.yaml over config/home.yaml and the printer model). tests/test_docker_release.py derives the inventory from the settings schema and fails when a setting lacks a row here or an .env.example line, or when a documented name is not a real setting.

  • YAML: put keys in a file and select it with PRINT_BUDDY_CONFIG. In Docker, mount the file and point PRINT_BUDDY_CONFIG at its container path.
  • Environment: PRINT_BUDDY__SECTION__KEY=value overrides any file. Booleans accept true/false, 1/0, yes/no, on/off. Integer settings need integer spelling (12, not 12.0). Rows marked file only are lists or tables and can only come from YAML or legacy TOML; the one list exception is delivery.methods, which also accepts a comma- or space-separated environment value (PRINT_BUDDY__DELIVERY__METHODS=discord,bambu_handoff,printer, #270).
  • Precedence, later wins: vendor and printer model defaults (model), config/home.yaml, the selected config file, environment. Settings are read once at start, so restart the service after a change.
  • A typo or invalid value stops startup and names the setting. YAML holds no secrets; see Secrets.

Schema, validation limits and TOML migration: CONFIGURATION-YAML.md. Standalone bot settings: STANDALONE.md. Printer vendor profiles: PRINTER-PROFILES.md.

YAML keyEnvironment variableDocker valueWhat it does
layout.single_copy_edge_mmPRINT_BUDDY__LAYOUT__SINGLE_COPY_EDGE_MM1.0 modelBed-edge clearance for one copy
layout.multi_copy_edge_mmPRINT_BUDDY__LAYOUT__MULTI_COPY_EDGE_MM3.0 modelBed-edge clearance for several copies
layout.merge_edge_margin_mmPRINT_BUDDY__LAYOUT__MERGE_EDGE_MARGIN_MM8.0 modelEdge margin when merging plates
layout.merge_spacing_mmPRINT_BUDDY__LAYOUT__MERGE_SPACING_MM10.0 modelGap between merged plates' parts
layout.max_merged_hoursPRINT_BUDDY__LAYOUT__MAX_MERGED_HOURS12Merged plates longer than this stay separate
prime_tower.size_mmPRINT_BUDDY__PRIME_TOWER__SIZE_MM45.0 modelPrime tower size
prime_tower.part_clearance_mmPRINT_BUDDY__PRIME_TOWER__PART_CLEARANCE_MM8.0 modelPrime tower to part clearance
prime_tower.edge_mmPRINT_BUDDY__PRIME_TOWER__EDGE_MM10.0 modelPrime tower to bed edge clearance
prime_tower.merge_slack_mmPRINT_BUDDY__PRIME_TOWER__MERGE_SLACK_MM5.0 modelExtra room kept for the tower when merging
printer.firmwarePRINT_BUDDY__PRINTER__FIRMWAREZMod Klipper modelFirmware label shown in job summaries
printer.start_macroPRINT_BUDDY__PRINTER__START_MACROSTART_PRINT modelKlipper start macro for stock Klipper models
printer.end_macroPRINT_BUDDY__PRINTER__END_MACROEND_PRINT modelKlipper end macro for stock Klipper models
printer.namePRINT_BUDDY__PRINTER__NAMEFlashforge AD5X modelPrinter name shown in job summaries
printer.bed_mmfile only[220.0, 220.0] modelUsable print area [x, y] in mm
printer.max_print_height_mmPRINT_BUDDY__PRINTER__MAX_PRINT_HEIGHT_MM220.0 modelTallest allowed print
printer.nozzle_diameter_mmPRINT_BUDDY__PRINTER__NOZZLE_DIAMETER_MM0.4 modelInstalled nozzle; slicing refuses any other
printer.ifs_slotsPRINT_BUDDY__PRINTER__IFS_SLOTS4 modelFilament slots; 1 for a single extruder
printer.modelPRINT_BUDDY__PRINTER__MODELflashforge.ad5xPrinter brand and model: flashforge.ad5x, sovol.sv06, klipper.generic, octoprint.marlin, bambulab.a1, bambulab.p1s (Bambu Lab models are offline only). Sets every model default marked model
printer.vendorPRINT_BUDDY__PRINTER__VENDORflashforge modelVendor part of the model key, set by the model; vendor plus a bare printer name is also accepted
printer.slicerPRINT_BUDDY__PRINTER__SLICERorca modelSlicer: orca everywhere; Bambu Lab printers default to bambu_studio and may pick orca
slicer.flash_studio_pathPRINT_BUDDY__SLICER__FLASH_STUDIO_PATHemptyOptional path to a Flash Studio executable the user already installed. Empty keeps OrcaSlicer. A set but missing or non-executable path is an error, not a fallback. Never downloaded or bundled.
printer.nozzle_typePRINT_BUDDY__PRINTER__NOZZLE_TYPEunsetOptional nozzle material, limited to the model's supported types
orca.templatesPRINT_BUDDY__ORCA__TEMPLATESthe model's folder modelFolder with the Orca machine, process and filament JSON
orca.commandfile only["/usr/local/bin/orca-slicer"]How to start the OrcaSlicer CLI; PRINT_BUDDY_ORCA_CHANNEL selects stable (default) or alpha; both binaries exist only when WITH_ORCA=true
delivery.methodsPRINT_BUDDY__DELIVERY__METHODS["printer"] modelPost-slice options offered, from the vendor profile (for example printer); comma- or space-separated in the environment, an empty value keeps the file value
bambu.commandfile only["/usr/bin/bambu-studio"]Bambu Studio CLI: the default slicer for Bambu Lab printers, Orca's one-shot fallback elsewhere; exists only in a WITH_BAMBU=true image
bambu.lan_hostPRINT_BUDDY__BAMBU__LAN_HOST""Bambu Lab printer LAN address for read-only status (#187); must be set together with lan_serial; empty disables LAN status
bambu.lan_serialPRINT_BUDDY__BAMBU__LAN_SERIAL""The Bambu Lab printer's serial number (stored upper case); used in the MQTT topics, not as a credential
bambu.lan_access_code_envPRINT_BUDDY__BAMBU__LAN_ACCESS_CODE_ENVBAMBU_LAN_PASSWORDName of the environment variable holding the printer's LAN access code; the code itself is never a setting
bambu.start_confirm_sPRINT_BUDDY__BAMBU__START_CONFIRM_S90Bambu Lab LAN print start (#271): how long, in whole seconds (1-300), the printer is polled every 10 s to report the submitted file as preparing or running before the start is left as uncertain; keep it well under the bot's 420 s start budget, which also covers the upload
flashforge_stock.hostPRINT_BUDDY__FLASHFORGE_STOCK__HOST""Stock Flashforge printer LAN address; empty leaves the printer offline. The serial and check code stay in AD5X_SERIAL and AD5X_CHECK_CODE, never in a setting
prusa.link_hostPRINT_BUDDY__PRUSA__LINK_HOST""Prusa printer LAN address for PrusaLink; empty leaves the printer offline (slicing, checks and Discord delivery only). Prusa models only
elegoo_sdcp.hostPRINT_BUDDY__ELEGOO_SDCP__HOST""Centauri printer LAN address for SDCP; empty leaves the printer offline (slicing, checks and Discord delivery only). Elegoo SDCP models only. SDCP has no authentication; there is no key to configure
prusa.api_key_envPRINT_BUDDY__PRUSA__API_KEY_ENV"PRUSA_LINK_API_KEY"Name of the environment variable holding the PrusaLink API key. The key itself is never a setting
paths.hermes_homePRINT_BUDDY__PATHS__HERMES_HOME/data/hermesState folder (state/, logs/); the name is historical, Hermes is not required
paths.archivePRINT_BUDDY__PATHS__ARCHIVE/data/archiveJob archive
paths.records_vaultPRINT_BUDDY__PATHS__RECORDS_VAULT/data/recordsObsidian print records
paths.cachePRINT_BUDDY__PATHS__CACHE/data/cacheRegenerable cache
paths.hermes_binPRINT_BUDDY__PATHS__HERMES_BIN/usr/local/bin/hermesHermes CLI; Hermes installs only, not in the image
paths.ffmpegPRINT_BUDDY__PATHS__FFMPEGffmpegffmpeg binary or name on PATH
paths.hermes_agentPRINT_BUDDY__PATHS__HERMES_AGENT/data/hermes/hermes-agentHermes agent checkout (Hermes installs only)
paths.hermes_restart_helperPRINT_BUDDY__PATHS__HERMES_RESTART_HELPER/data/hermes/restart_hermes.pyHermes restart helper (Hermes installs only)
services.moonraker_urlPRINT_BUDDY__SERVICES__MOONRAKER_URLemptyKlipper printers: Moonraker HTTP URL, e.g. http://printer.example:7125. Required by the listener
services.moonraker_ws_urlPRINT_BUDDY__SERVICES__MOONRAKER_WS_URLemptyMoonraker websocket; derived from moonraker_url when empty
services.camera_snapshot_urlPRINT_BUDDY__SERVICES__CAMERA_SNAPSHOT_URLemptyCamera snapshot URL; derived from the Moonraker host when empty
services.spoolman_urlPRINT_BUDDY__SERVICES__SPOOLMAN_URLemptySpoolman URL. The Docker config and Compose default to http://127.0.0.1:8000, the bundled Spoolman API in the same container. Set another URL, plus PRINT_BUDDY_BUNDLED_SPOOLMAN=false, to use an existing external Spoolman instead
services.openviking_urlPRINT_BUDDY__SERVICES__OPENVIKING_URLemptyOptional OpenViking memory store
services.vision_chat_urlPRINT_BUDDY__SERVICES__VISION_CHAT_URLemptyOpenAI-compatible endpoint for camera checks and roasts; empty disables both
services.stock_api_portPRINT_BUDDY__SERVICES__STOCK_API_PORT8898Flashforge stock API port for IFS presence
services.octoprint_urlPRINT_BUDDY__SERVICES__OCTOPRINT_URLemptyOctoPrint printers (octoprint.marlin): OctoPrint URL. API key: OCTOPRINT_API_KEY secret
discord.chat_idPRINT_BUDDY__DISCORD__CHAT_IDemptyDiscord channel ID
discord.approval_user_idPRINT_BUDDY__DISCORD__APPROVAL_USER_IDemptyDiscord user ID allowed to approve
discord.upload_max_bytesPRINT_BUDDY__DISCORD__UPLOAD_MAX_BYTES9500000Largest upload per file: video is shrunk to it, and a sliced file or Bambu package over it is reported with its host path instead of offered for sending (see PRINTER-PROFILES.md). Keep it under your server's Discord cap (10 MB unboosted)
discord.post_print_quiet_sPRINT_BUDDY__DISCORD__POST_PRINT_QUIET_S7200Quiet time before a chat session resets
discord.daily_reset_hourPRINT_BUDDY__DISCORD__DAILY_RESET_HOUR4Hour of the daily session reset
discord.timezonePRINT_BUDDY__DISCORD__TIMEZONEAmerica/New_YorkDisplay and reset time zone (IANA name)
discord.bot_namePRINT_BUDDY__DISCORD__BOT_NAMEPrint BuddyName the bot uses for itself
discord.question_timeout_sPRINT_BUDDY__DISCORD__QUESTION_TIMEOUT_S1800How long a Discord question waits for a button
discord.safety_confirm_timeout_sPRINT_BUDDY__DISCORD__SAFETY_CONFIRM_TIMEOUT_S600How long a safety confirmation waits
discord.upload_wait_sPRINT_BUDDY__DISCORD__UPLOAD_WAIT_S3600How long an upload-wait freeze stays active
discord.cold_pull_outcome_sPRINT_BUDDY__DISCORD__COLD_PULL_OUTCOME_S1800How long a cold-pull outcome prompt stays open
discord.token_envPRINT_BUDDY__DISCORD__TOKEN_ENVDISCORD_BOT_TOKENName of the environment variable holding the bot token
discord.allowed_user_idsPRINT_BUDDY__DISCORD__ALLOWED_USER_IDSemptyDiscord user IDs allowed to use the standalone bot, comma or space separated
telegram.token_envPRINT_BUDDY__TELEGRAM__TOKEN_ENVTELEGRAM_BOT_TOKENName of the environment variable holding the Telegram bot token
telegram.chat_idPRINT_BUDDY__TELEGRAM__CHAT_IDemptyTelegram chat (group) ID; group and channel IDs are negative
telegram.allowed_user_idsPRINT_BUDDY__TELEGRAM__ALLOWED_USER_IDSemptyTelegram user IDs allowed to use the standalone bot, comma or space separated
telegram.approval_user_idPRINT_BUDDY__TELEGRAM__APPROVAL_USER_IDemptyTelegram user ID allowed to approve
telegram.upload_max_bytesPRINT_BUDDY__TELEGRAM__UPLOAD_MAX_BYTES50000000Largest file the Telegram bot uploads (the Bot API cloud limit)
matrix.homeserver_urlPRINT_BUDDY__MATRIX__HOMESERVER_URLemptyMatrix homeserver base URL, for example https://matrix.org or a self-hosted server
matrix.access_token_envPRINT_BUDDY__MATRIX__ACCESS_TOKEN_ENVMATRIX_ACCESS_TOKENName of the environment variable holding the Matrix access token
matrix.room_idPRINT_BUDDY__MATRIX__ROOM_IDemptyMatrix room ID of the print room (starts with !); the room must be unencrypted
matrix.allowed_user_idsPRINT_BUDDY__MATRIX__ALLOWED_USER_IDSemptyMatrix user IDs allowed to use the standalone bot, full @user:server form, comma or space separated
matrix.approval_user_idPRINT_BUDDY__MATRIX__APPROVAL_USER_IDemptyMatrix user ID allowed to approve
matrix.bot_user_idPRINT_BUDDY__MATRIX__BOT_USER_IDemptyThe bot's own Matrix user ID; empty asks the homeserver (whoami) at startup
matrix.upload_max_bytesPRINT_BUDDY__MATRIX__UPLOAD_MAX_BYTES50000000Largest file the Matrix bot uploads; lowered to the homeserver's media limit when the server reports a smaller one
bot.modePRINT_BUDDY__BOT__MODEhermes; standalone in the imagehermes or standalone; the image and Compose set standalone
bot.platformPRINT_BUDDY__BOT__PLATFORMdiscordChat platform for the standalone bot (#164): discord, telegram or matrix
bot.health_portPRINT_BUDDY__BOT__HEALTH_PORT0Serve GET /healthz on this port; 0 turns the HTTP check off
bot.health_stale_sPRINT_BUDDY__BOT__HEALTH_STALE_S120Bot health fails when its heartbeat is older than this
bot.sync_commandsPRINT_BUDDY__BOT__SYNC_COMMANDStrueRegister the slash commands with Discord at startup
llm.chat_urlPRINT_BUDDY__LLM__CHAT_URLemptyOptional OpenAI-compatible chat URL; empty: unmatched text gets the command list
llm.modelPRINT_BUDDY__LLM__MODELemptyLLM model name, required when chat_url is set
llm.api_key_envPRINT_BUDDY__LLM__API_KEY_ENVLLM_API_KEYName of the environment variable holding the LLM API key
llm.timeout_sPRINT_BUDDY__LLM__TIMEOUT_S20LLM request timeout
listener.tick_sPRINT_BUDDY__LISTENER__TICK_S600Listener housekeeping interval
listener.ifs_presence_poll_sPRINT_BUDDY__LISTENER__IFS_PRESENCE_POLL_S15IFS spool presence poll
listener.spool_nag_sPRINT_BUDDY__LISTENER__SPOOL_NAG_S600Reminder interval for an unanswered spool question
listener.start_claim_ttl_sPRINT_BUDDY__LISTENER__START_CLAIM_TTL_S1800How long a start button stays claimed
vision.modelPRINT_BUDDY__VISION__MODELgemini-latestModel for camera checks
vision.roast_modelPRINT_BUDDY__VISION__ROAST_MODELluna-latestModel for the print-start roast
visual_watch.sensitivityPRINT_BUDDY__VISUAL_WATCH__SENSITIVITY3Camera watchdog sensitivity, 1 (quietest) to 5 (most alerts); also sets the periodic check interval and stall threshold, see the project reference
visual_watch.enabledPRINT_BUDDY__VISUAL_WATCH__ENABLEDtrueCamera monitoring switch; the watchdog is alert-only and never controls the printer
timelapse.archive_hostPRINT_BUDDY__TIMELAPSE__ARCHIVE_HOSTemptySSH host for the timelapse archive; empty disables it
timelapse.archive_dirPRINT_BUDDY__TIMELAPSE__ARCHIVE_DIRemptyArchive folder on that host
timelapse.ssh_keyPRINT_BUDDY__TIMELAPSE__SSH_KEYemptyPath of the SSH key in the container (mount it read-only)
timelapse.render_wait_sPRINT_BUDDY__TIMELAPSE__RENDER_WAIT_S900Wait for the printer to render the timelapse
timelapse.render_poll_sPRINT_BUDDY__TIMELAPSE__RENDER_POLL_S10Poll interval while waiting
timelapse.max_bytesPRINT_BUDDY__TIMELAPSE__MAX_BYTES209715200Largest timelapse kept
timelapse.local_retention_daysPRINT_BUDDY__TIMELAPSE__LOCAL_RETENTION_DAYS1Local copy retention
timelapse.plan_clip_retention_daysPRINT_BUDDY__TIMELAPSE__PLAN_CLIP_RETENTION_DAYS14Plan clip retention
webui.enabledPRINT_BUDDY__WEBUI__ENABLEDfalseOptional Web UI (#286) switch; off by default, and nothing listens while disabled
webui.hostPRINT_BUDDY__WEBUI__HOST127.0.0.1Host the Web UI binds to when enabled; a plain IP address or hostname
webui.portPRINT_BUDDY__WEBUI__PORT0Port the Web UI binds to when enabled; 0 means no port has been chosen yet
webui.access_token_envPRINT_BUDDY__WEBUI__ACCESS_TOKEN_ENVWEBUI_ACCESS_TOKENName of the environment variable holding the optional Web UI access token; the token itself is never a setting
logging.levelPRINT_BUDDY__LOGGING__LEVELINFODEBUG, INFO, WARNING or ERROR
logging.formatPRINT_BUDDY__LOGGING__FORMATtexttext (one readable line per event) or json (one JSON object per line)
logging.filePRINT_BUDDY__LOGGING__FILEemptyAlso write a rotating log file (5 MiB, 3 backups) at this path, for example under /data/hermes/logs; empty logs to stderr only
maintenance.quick_hoursPRINT_BUDDY__MAINTENANCE__QUICK_HOURS25Quick maintenance due after these print hours
maintenance.full_hoursPRINT_BUDDY__MAINTENANCE__FULL_HOURS75Full maintenance due after these print hours
maintenance.full_daysPRINT_BUDDY__MAINTENANCE__FULL_DAYS30Full maintenance due after these days
nozzle_temp_offsets.<type>PRINT_BUDDY__NOZZLE_TEMP_OFFSETS__<TYPE>0.0Temperature offset, −10 to +15 °C, for brass, hardened_steel, stainless_steel, ruby, tungsten_carbide, diamond
material_temps.<MATERIAL>file onlysee config/home.yaml{nozzle, bed} fallback temperatures for PLA, PETG, ABS, ASA, TPU, PA, PC; Spoolman filament values win
cold_pull.<profile>file onlyfrom the vendor profile modelHot and cold cold-pull temperatures; profile names are yours

Compose variables ​

These configure the Compose deployment, not Print Buddy itself. Set them in .env.

VariableDefaultWhat it does
PRINT_BUDDY_IMAGEnone, requiredImage the combined container runs: a locally built tag or a tested immutable digest. No published image exists yet
PRINT_BUDDY_DATA./dataHost folder holding the hermes, archive, records and cache volumes
PRINT_BUDDY_SPOOLMAN_DATA./data/spoolmanHost folder for the bundled Spoolman database, config, logs and backups
PRINT_BUDDY_CONFIG/app/config/docker.yamlSettings file Print Buddy reads (YAML, or legacy .toml)
TZUTCContainer timezone (IANA name), used by the bundled Spoolman; Print Buddy itself uses discord.timezone

Runtime environment ​

VariableDefaultWhat it does
PRINT_BUDDY_ORCA_CHANNELstableSelects the bundled stable or alpha OrcaSlicer at startup; invalid values stop the container
PRINT_BUDDY_BUNDLED_SPOOLMANtruetrue runs the bundled Spoolman API; false uses services.spoolman_url only
SPOOLMAN_HOST127.0.0.1Bundled Spoolman bind address; widen it only together with an approved port mapping, see docs/DOCKER.md

WITH_ORCA=false (default) omits both Orca channels; slicing fails closed without either binary.

Build arguments ​

Image build inputs (docker build --build-arg NAME=value), not runtime settings. PRINT_BUDDY_ORCA_CHANNEL is a runtime environment variable (default stable, accepts alpha) and requires an image built with WITH_ORCA=true.

ArgumentDefaultWhat it does
APP_CHANNELdevelopmentApplication provenance label, stable or development; it does not change the source checkout
WITH_ORCAfalsetrue installs both pinned official prebuilt OrcaSlicer releases (stable 2.4.2 and alpha 2.5.0-alpha, each SHA256 verified in docker/orca-prebuilt.sh); OrcaSlicer is never built from source; false omits it and slicing fails closed
SPOOLMAN_REFbed3f14ee77a3a571d31b14215d54b0b88a7519cPinned Spoolman v0.27.0 source commit; only its Python API backend is installed, never the web UI
ORCA_BUILD_JOBSautoBambu Studio source build only: parallel compile jobs, auto (memory-aware, below the CPU count) or a whole number from 1 to 64
ORCA_BUILD_MEM_PER_JOB_MIB2560Bambu Studio source build only: memory budgeted per job by auto, at least 256
ORCA_CCACHE_MAXSIZE5GBambu Studio source build only: size cap of the compiler cache inside the build cache
WITH_BAMBUfalsetrue builds Bambu Studio from pinned source into /usr/bin/bambu-studio; false omits it and Bambu Lab slicing fails closed
BAMBU_REF926a7192574bcb9b3a732e1ec59a46d79cb45466Pinned Bambu Studio 2.8.2 source commit
BAMBU_BUILD_PROFILErelease-static-fhsNames the Bambu Studio build options; rename it to reset the build trees

Secrets ​

Secrets come from the environment only (Docker: .env, never committed or shared), never from YAML or the image.

VariableUsed for
DISCORD_BOT_TOKENStandalone bot token. The variable name is discord.token_env
TELEGRAM_BOT_TOKENTelegram standalone bot token. The variable name is telegram.token_env
MATRIX_ACCESS_TOKENMatrix standalone bot access token. The variable name is matrix.access_token_env
LLM_API_KEYOptional key for llm.chat_url. The variable name is llm.api_key_env
OCTOPRINT_API_KEYoctoprint.marlin printers: OctoPrint application key
BAMBU_LAN_PASSWORDBambu Lab printers: the LAN access code for read-only status. The variable name is bambu.lan_access_code_env
MOONRAKER_API_KEYMoonraker API key, only when Moonraker requires one
CLIPROXY_API_KEYKey for services.vision_chat_url
OPENVIKING_API_KEYKey for services.openviking_url
AD5X_SERIALStock Flashforge printers: the printer serial number for the stock LAN API. Never a setting; set it together with flashforge_stock.host
AD5X_CHECK_CODEStock Flashforge printers: the printer check code for the stock LAN API. Never a setting

The MakerWorld account token is not an environment variable. It is the file ~/.config/bambu/token (Docker: /data/.config/bambu/token), needed only for MakerWorld links; see MakerWorld account token.

Legacy environment names ​

The names below predate PRINT_BUDDY__SECTION__KEY and still work; new installs should use the long form. The full map is LEGACY_ENV in print_buddy/settings.py, for example MOONRAKER_URL → services.moonraker_url, SPOOLMAN_URL → services.spoolman_url, PRINT_DISCORD_CHAT_ID → discord.chat_id.

Documentation content is copied from catduckgnaf/print-buddy — that repo's docs/ directory is the source of truth.