The first time you bring Binions up, there is very little to configure. Each daemon is its own package, and when you install it the package sets itself up — it creates its service user, lays out its directories, writes a starter configuration file, and generates its private credentials for you. So “first boot” is mostly two things: enable the daemon so it starts, and check that it is healthy. This page explains what install does on your behalf and introduces binions-cliconsole, the operator command-line tool you use to inspect and steer the platform.
Note. This page explains the first-boot model. If you just want a tick-box list to confirm a fresh install is healthy, jump to the Post-install checklist.
Binions daemons are self-provisioning. The moment apt finishes installing a daemon package, that package has already prepared everything the daemon needs to run. You do not edit a config file before the service can start. Installing a daemon does the following, automatically:
root — so one daemon cannot read another’s data.0750 permissions and owned by that service user.application.toml is copied from the package’s example template, so the daemon has sensible defaults out of the box./etc/binions/master.toml — but only if it does not already exist.Your edits are safe. Because
master.tomlis written only when it is missing, and each daemon’sapplication.tomlis treated as a config file you own, your changes are preserved across upgrades. Updating a package never overwrites settings you have changed.
After installing a daemon, it is not started yet — you turn it on with systemctl. Enable the daemon together with its bundled Redis instance in one command. Using the logger daemon as the example:
sudo apt install binions-logger
sudo systemctl enable --now binions-logger redis-binions-loggerTwo things are worth knowing about that second line:
enable --now. enable tells systemd to start the service automatically on every boot; --now also starts it immediately, so you do not need a separate systemctl start.redis-binions-<service>, here redis-binions-logger — which is the daemon’s internal event bus. You enable them together so the daemon always has its bus available. You never install or manage Redis separately.That is the whole pattern, and it is identical for every daemon — install the package, then enable --now the daemon alongside its Redis. The full per-daemon installation reference is in Install on a single host.
Once a daemon is running, you interact with the platform through binions-cliconsole — the operator command-line tool. It is installed at /usr/bin/binions-cliconsole and is available on your PATH as soon as its package is on the host. It is a short-lived command, not a background service: you run it, it does one thing, and it exits. Use it to see the platform at a glance, list recent events, validate a playbook, and emit events by hand.
See everything at a glance. status polls each daemon’s health endpoint and prints a table of what is up and what is down — the fastest way to read the state of the whole platform:
binions-cliconsole statusList recent events. Every action and result flows through the event bus. ls events shows you the most recent entries on a stream, which is invaluable when you are checking whether a playbook actually fired:
binions-cliconsole ls events --stream events:logs --count 10Check a playbook before you deploy it. validate parses a playbook file and reports any problems — a typo-catcher you run before putting a playbook live:
binions-cliconsole validate playbooks/business/invoice.yamlA clean run prints OK; if something is wrong it lists each violation and exits with a non-zero status, so you can use it in scripts.
binions-cliconsole has two distinct subcommands for publishing events onto the bus, and it is important to use the right one:
emit publishes Action.*, Fact.*, and Log.* events — the day-to-day signals that trigger playbooks, record facts, and write log entries. Use this for testing a workflow without waiting for a real trigger.emit-control sends Control.* events that direct a daemon to take an operational action at runtime. These are operator commands, not data signals, and require the dedicated subcommand.For example, to send a smoke event that confirms the logger is wired up, use plain emit:
binions-cliconsole emit Log.Smoke.Hello --payload '{"hello":"from binions"}'To reload all playbooks after you have added or changed a playbook file, use emit-control with the playbook reload control event:
binions-cliconsole emit-control Control.Playbook.ReloadThis is the authoritative way to pick up new or modified playbook files at runtime. The pattern applies to any Control.* event: always use emit-control, never plain emit.
Tip. Run
binions-cliconsole --helpat any time to see the available subcommands and their options on the version you have installed.
After enabling a daemon, three quick checks confirm it really came up. First, ask systemd whether the daemon and its Redis are active:
systemctl is-active binions-logger redis-binions-loggerYou should see active printed twice. Next, call the daemon’s readiness endpoint. Each daemon exposes health on the loopback address on its own port in the 91xx range — the logger answers on :9100:
curl -sf http://127.0.0.1:9100/health/ready && echo OKIf the daemon is up and its event bus is reachable, you will see OK. Finally, glance at the daemon’s own log to confirm it started cleanly:
journalctl -u binions-logger -n 20 --no-pagerFor a complete, ordered set of checks across permissions, health, and logging on a fresh host, work through the Post-install checklist.
You rarely need to touch configuration on first boot, but it helps to know where it lives. Binions keeps configuration in two layers:
| Per-daemon config | Each daemon’s own application.toml, holding settings specific to that daemon — this is the file you own and the one preserved across upgrades. |
| Platform config | /etc/binions/master.toml — platform-wide settings shared by every daemon on the host. |
For what each file contains and which settings live where, see Per-daemon configuration. Secrets — API keys, mailbox passwords, and the like — are kept apart from ordinary config; see Secrets & credentials for how those are stored and protected.