Binions is configured with plain TOML files — one per daemon, plus one shared file for the whole platform. There is no central admin UI and no proprietary config language: you edit ordinary .toml files with the text editor you already know, then apply the change as described below. This page explains where those files live, how to edit them safely, and why your edits survive package upgrades.
Binions is built from small background services — we call them daemons. Each daemon reads its own config file, so you only touch the file for the part of the platform you want to change.
Every Binions install has two layers of configuration. Per-daemon settings belong to a single service; platform-wide settings are shared by all of them.
| Per-daemon config | /opt/binions/<service>-service/config/application.toml — settings for that one daemon (for example, the mailbox daemon’s IMAP/SMTP behaviour, or the scheduler daemon’s timing). Each daemon has its own file. |
| Platform-wide config | /etc/binions/master.toml — shared settings that apply across the whole platform, kept in one place so you don’t repeat them in every daemon. |
The rule of thumb: if a setting changes how one daemon behaves, it goes in that daemon’s application.toml; if it is shared by the whole install, it goes in master.toml. When you install a daemon, its application.toml is created for you from a bundled template (a .example file) with sensible defaults, so there is always a working file to edit.
A daemon’s config directory sits inside its own folder under /opt/binions/, next to the daemon’s other working directories:
/opt/binions/<service>-service/
├── config/ # application.toml + any per-domain config (this page)
├── secrets/ # passwords, API keys, private keys — kept out of config
├── certs/ # TLS certificates for this daemon
├── var/ # runtime scratch (PID files, locks, caches)
├── migrations/ # database migrations (mainly the database daemon)
└── scripts/ # helper scripts (start, health check, rotate)Each daemon runs as its own dedicated system user (for example, the mailbox daemon runs as mailboxsvc), and its config files are owned by that user. The clean way to edit a file is therefore to edit it as that user, so ownership and permissions stay correct. Open the file with your editor:
# Edit the mailbox daemon's config as its service user.
# Replace <service> / <service>svc with the daemon you are configuring.
sudo -u mailboxsvc nano /opt/binions/mailbox-service/config/application.toml
# Or use sudoedit, which copies the file out, lets you edit it,
# and writes it back with the original ownership preserved:
sudo sudoedit /opt/binions/mailbox-service/config/application.tomlInside, you’ll find ordinary TOML — key/value pairs grouped into [sections]. A file looks roughly like this:
# /opt/binions/<service>-service/config/application.toml
# NOTE: keys below are illustrative — the exact section and key
# names depend on the daemon. See /daemons for each daemon's settings.
[service]
log_level = "info" # how chatty this daemon's logs are
[bind]
address = "127.0.0.1" # daemons listen on localhost by default
port = 9107 # health/metrics port for this daemon
[limits]
max_concurrency = 8 # tune to your host's size
request_timeout = "30s"The exact keys depend on the daemon. The snippet above is only to show the shape of a config file. Section names (
[service],[bind]…) and the keys inside them differ from one daemon to the next — always check the Daemons reference for the real keys before changing a value.
Save the file, then restart the daemon so it picks up your changes. Each daemon’s service is named binions-<service>:
# Restart the daemon after editing its config:
sudo systemctl restart binions-mailbox
# Check it came back up cleanly:
sudo systemctl status binions-mailboxWhen you run apt upgrade, Binions does not overwrite your config. The package uses “create only if missing” semantics, so both your application.toml files and master.toml are kept exactly as you left them. New default templates ship as separate .example files you can compare against.
Most daemons need nothing more than their application.toml. A few keep additional, more granular config inside the same config/ directory — one file per “thing” they manage, so you can add, edit, or remove items individually:
config/mailboxes/<id>.toml, so each mailbox you connect has its own settings.config/templates/<name>.toml, kept separate from the daemon’s core settings.config/dynamic/, used to manage routes for the platform’s public HTTP entry point.The exact set of per-domain files a daemon uses is documented with that daemon — see the Daemons reference for details.
For most configuration changes the rule is simple: edit, save, restart the daemon. A restart is the reliable way to be sure a daemon is running with your latest settings.
sudo systemctl restart binions-<service> after editing a daemon’s application.toml or one of its per-domain files.To reload playbooks, first optionally validate your YAML, then emit the reload control event:
# (Optional) Check the playbook file for errors before reloading:
binions-cliconsole validate
# Drop the file into the playbooks directory (owned by the playbook daemon's service user):
sudo install -o playbooksvc -g playbooksvc -m 0640 my-playbook.yaml \
/opt/binions/playbook-service/playbooks/business/
# Signal the daemon to reload — no restart needed:
binions-cliconsole emit-control Control.Playbook.ReloadAn explicit reload command is required. The playbook daemon does not watch its directory for changes automatically. You must run
binions-cliconsole emit-control Control.Playbook.Reloadafter placing or updating a playbook file. Until you do, the daemon continues running with the previously loaded playbooks.
Whether a given change can be applied without a full restart depends on the daemon and the setting. When in doubt, a restart is always safe. The binions-cliconsole tool is introduced in First boot & the CLI console.
Configuration files describe how a daemon behaves; they are not the place for passwords and keys. Wherever practical, keep credentials — database passwords, API keys, private keys — in the daemon’s secrets/ directory rather than inline in application.toml.
secrets/ directory is locked down. It lives at /opt/binions/<service>-service/secrets/, is owned by the daemon’s service user, and is restricted so only that daemon (and root) can read it.application.toml points at credentials by name; the actual secret value stays in the protected directory.Why it matters. Keeping secrets separate means you can edit, share, or version-control your config without exposing credentials. See Secrets & credentials for how the
secrets/directory works.