obachtctl reference
obachtctl is the local CLI of the Obacht agent on a Raspberry Pi or Linux PC. It talks to the running agent over its Unix socket and shows you the same state the dashboard shows, from the device itself. Useful when the device is offline from Obacht's point of view and you want to know why.
Where it lives
The installer puts the agent in /opt/obacht-agent/ and symlinks the CLI to /usr/local/bin/obachtctl, so it is on the path for every user. It talks to the agent through /run/obacht/agent-v2.sock. The agent runs as the system user obacht.
You need no sudo as the obacht user. That is the user you are in the web terminal, and the one your device key logs in as over SSH. The agent only answers to its own user and to root on that socket, so from any other account (say pi or admin) put sudo in front.
system unlock-power, system lock-power and system update-agent call small helpers with sudo themselves. The installer allows exactly those, so they work without a password too.
There is no obachtctl on a Mac. The Mac app has no user-facing shell into the hosting engine.
Subcommands
| Subcommand | What it does |
|---|---|
version | Prints the agent version. Compare with the "Agent Version" tile in the dashboard. |
health | Health check of the running agent. |
instance | Installed app instances (templates) on this device. |
template | Template manifests. |
domain | list, claim, unclaim, bind, unbind, basic-auth. Domains on this device and what they point at. |
ingress | The ingress (Caddy) side of the domains. |
reconcile | Runs a reconcile: compare the desired state in the database with what is actually running. |
audit | The audit log of changes on this device. |
service | systemd services (needs Power Mode). |
system | status, set-power-mode, unlock-power, lock-power, update-agent. |
trust | list, pin, unpin. The user signing keys this device accepts. |
logs | Logs of an app instance. |
Examples
obachtctl version
obachtctl health
obachtctl trust list
obachtctl domain list
obachtctl instance list
obachtctl logs <instance-id>
trust list is the one to run when the dashboard shows "Key mismatch" or "Extra keys" on the trust card. It prints the fingerprints the device has pinned. The dashboard's trust card shows the matching obachtctl trust unpin hint for a key you want gone.
domain list tells you, without the dashboard, whether a domain is claimed on this device and whether it is bound to an instance or a port. Pair it with obachtctl ingress when a certificate does not come up.
Local changes need no signature
Changes from the dashboard are signed with your device key and checked against the pinned key, with a 120 s expiry (see Signed changes and trust). obachtctl is different: whoever can reach the socket on the device can change things directly, without a signature. That covers removing apps, claiming and unbinding domains, switching Power Mode and pinning or unpinning keys.
That is on purpose. Being logged in on the device as obacht or root is the same trust as holding the SD card in your hand, and pinning a key only works this way, never from Obacht's servers. It also means: whoever can log in to the device can change it. Keep SSH access to people you trust.
obachtctl trust unpin removes your key from the device. After that the dashboard can no longer change anything on it until a key is pinned again.