Lifecycle

Start order

Router, then agent, then workspace. An agent started without its router reports a licence error that has nothing to do with the licence.

hexaeight-activate restart router
hexaeight-activate restart agent
hexaeight-activate restart workspace

autostart writes units that do this at login, in that order.

Check that an installed unit sources env-file. A unit whose ExecStart does not will fail exactly like a wrong working directory — the identity is simply absent.

Always from the component’s own folder

Every command acts on the current directory. Starting a router from an agent folder, or an agent from your home directory, gets you the wrong identity or none.

Stopping one thing without stopping the others

On a machine with several agents, read the output rather than assume. A folder-scoped restart says what it spared:

runner (services: {}) - stopping only this folder's agent and its tunnel
stopped agent (43369, 43370)
left alone: agent belonging to another folder (1987, 2001, 2027)

Never stop an agent with a pattern match on the process name. The daemon’s command line is a relative path, so a pattern broad enough to catch it is broad enough to catch every other agent — and, run from a shell, the pattern matches the shell itself.

Stop a component with hexaeight-activate stop from its own folder, which knows which processes belong to it. If you must find one by hand, find it by the port it listens on, not by its name.

Upgrading a component

hexaeight-activate update agent

Downloads, verifies against the published hash, replaces, restarts that component only.

Doing it by hand, two things bite:

• cp cannot overwrite a running binary. It fails Text file busy, and a script that ignores the failure prints a success line built from the unchanged file. Stage beside it and mv over the path.
• Killing the resident process is not enough. An agent keeps a resident engine; replacing the file without restarting the agent leaves the old one serving. Restart the agent.

Then verify the hash on disk changed. Do not trust the message.

Rolling back

Keep the previous binary beside the current one. Rollback is the same staged mv in reverse, plus a restart. A timestamped copy before every replacement makes this a thirty-second operation.

Revoking access

Revocation is a policy edit, not a key rotation:

./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule '<principal>,<object>,inbound,deny'
hexaeight-activate list-policy --subject <principal>

Deny beats allow. Confirm with list-policy — it prints what the enforcer decides, not what is written.

To withdraw a binary rather than a principal, remove its hash from the approved list. That list is fetched at runtime, so peers stop accepting it without anyone redeploying.

After a reboot

Nothing survives a reboot unless you installed units. /tmp is wiped — anything staged there is gone. Bring things up in order and check the four lines that matter:

[policy]   N rule(s)                                    router
[licence]  … N policy rule(s) in force                  agent
[reach]    mode=… tunnel up https://…                   agent
[register] OK -> https://registry.fastagents.net …      agent   (only if you opted in)

Where the record is

Nothing is hidden behind a dashboard. Two plain files hold what happened:

per session	a JSONL trail — one line per turn, with what was asked, what the engine did, and the tokens it reported
usage.jsonl	beside the router — one line per model call

Both are plain text, one JSON object per line. Total them however you like.

Health checks worth scheduling

command	cost
verify-license	one round trip — the fast one
verify-libs	no licence call, cheap enough to run on a timer
verify-env	four round trips, minutes on an agent folder — not for a schedule