# Startup configuration reference

> Command-line flags, environment variables, and port derivation for headless and packaged Buttons deployments, set before launch.

This page covers configuration that's set at launch, before Buttons is running, for packaged and headless deployments: command-line flags, environment variables, and port derivation. It doesn't cover the in-app Settings pages you configure once Buttons is already running; see Find your way around Settings for those. Headless CLI flags ( watchdog-cli ) The headless Linux binary takes two required positional arguments and a set of flags. Flags can be written as -name or --name , in any position: watchdog-cli [options] <address> <port> <address> : the listen address: 0.0.0.0 (all interfaces), localhost , or 127.0.0.1 . No other value is accepted. <port> : the HTTP port for the editor, 1–65535. Flag Default What it does -httpsPort none HTTPS port for the editor. If omitted, HTTPS uses the HTTP port plus three (for example, HTTP 8000 → HTTPS 8003 ). -publicHostname empty The hostname this installation is reachable at. -publicEndpoint empty Used for redirecting after signing in. -logsDir none Overrides the logs directory path. -databaseDir none Overrides the database directory path. -modulesDir none Overrides the modules directory path. -processesFile none Points at a specific processes.json file, overriding the PROCESSFILE environment variable. -migrate none When upgrading, imports the configuration shown under that number in the console (only importable configurations are numbered). Use 0 for a new, empty configuration. -help none Shows the full help text and exits. Note This page describes watchdog-cli , the headless binary used for headless Linux installs. The packaged macOS/Windows desktop app takes no command-line flags at all: its equivalent settings are configured live through its own Environment Settings screen instead, covered next. Environment variables Variable Controls Default if unset PROCESSFILE Path to the processes.json topology file (see below). Overridden by -processesFile if both are set. processes.json , relative to the executable WWW_PORT Initial HTTP port: only read the very first time the packaged desktop app starts, before it has its own saved configuration. 4440 WWW_HTTPS_PORT Initial HTTPS port, same first-run-only scope as WWW_PORT . HTTP port + 3 EDITOR_HOSTNAME Initial public hostname, same first-run-only scope. empty EDITOR_PUBLIC_ENDPOINT Initial public endpoint, same first-run-only scope. empty STORAGE_PATH Base directory for the login keypair and other stored configuration. See the note below: the packaged installs set it in processes.json , which takes priority. ./storage , only when nothing else sets it Note WWW_PORT , WWW_HTTPS_PORT , EDITOR_HOSTNAME , and EDITOR_PUBLIC_ENDPOINT only matter on the packaged desktop app's very first launch, before it has saved its own configuration file. After that first run, the same settings are edited live through that app's own Environment Settings screen instead: these environment variables have no effect on a system that's already been configured once. STORAGE_PATH is also set in the shipped processes.json , and that value takes priority over an environment variable of the same name. On the packaged Linux, macOS, and Windows installs it points at: Platform Storage path Linux ~/.config/bitfocus-buttons/data macOS ~/Library/Application Support/Bitfocus Buttons/data Windows %APPDATA%\Bitfocus\Buttons\data Setting STORAGE_PATH in the environment has no effect on those installs. Port derivation HTTPS defaults to the HTTP port plus three: set <port> to 8000 and, unless you override it, HTTPS listens on 8003 . This same relationship applies whether the port comes from the CLI's positional argument or from WWW_PORT / WWW_HTTPS_PORT on first launch. Configuration files The packaged desktop app persists its own settings (listen address, ports, hostname, public endpoint) to a configuration file it manages itself, edited through its Environment Settings screen: not something you hand-edit directly. processes.json describes the full set of child processes Buttons runs and how they're wired together. This file is generated at build time and shipped inside the release package: it's an internal deployment artifact, not a documented, hand-editable configuration surface. The only supported override is its location , via -processesFile or the PROCESSFILE environment variable. The file must be inside the folder that holds the Buttons executable (on macOS, the app bundle's Resources folder also works): Buttons refuses to start with a path outside it, to prevent path traversal. If you get stuck What you see What to try You want to see every available flag at a glance. Run watchdog-cli -help (or --help ). You set WWW_PORT or a related environment variable, but it had no effect. These only apply on the very first launch before a configuration file exists: after that, change them through the app's own Environment Settings screen instead. HTTPS is listening on a port you didn't expect. Confirm whether you set -httpsPort explicitly: without it, HTTPS is always the HTTP port plus three. You need Buttons to use a custom processes.json . Place it next to the Buttons executable and point at it with -processesFile or PROCESSFILE , rather than editing the shipped copy in place. A path outside the executable's folder is refused at startup. Where to go next Network ports reference , for every port Buttons and its related tools use, and how these ports fit into the rest. Install Buttons on Debian or Ubuntu First-time setup