Lifecycle

Start, stop, status

After the installer, the system’s service manager runs the router, the agent and the workspace. That is systemd on Linux and launchd on macOS. It starts them at login and brings them back if they stop. Manage them with heia, from any folder:

heia status                                    # what is running, and its addresses
heia restart [agent|router|workspace|all]      # agent by default; restarting the router restarts the agent too
heia start   [agent|router|workspace|all]
heia stop    [agent|router|workspace|all]
heia logs    [agent|router|workspace]          # follow a log; Ctrl-C to leave

heia keeps the order that works: router, then agent, then workspace.

• Use heia, not a second copy. A binary started by hand beside the service manager fights it for its port. Never stop a component with a pattern match on its process name either, because that can catch other agents.
• On Windows, in WSL, if WSL is not set up to run services, nothing starts by itself after Windows restarts. Open Ubuntu and run heia start all.
• Agent and router commands act on the folder they run in. Run ./hexaeight-agent-… from the agent’s folder (~/heia-agent) and ./hexaeight-router-… from the router’s (~/heia-router).

Update

Run the installer again:

curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash

It compares what is installed with the latest releases and downloads only what has a newer one. Each download is checked against its published hash, and the previous binary is kept beside the new one.

The agent records its version and the SHA-256 of its binary each time it starts. The compliance report shows them, so you can confirm that the build running is the one published.

Roll back

The previous binary stays in the same folder. Its name ends with the release it was and the time it was replaced, for example hexaeight-agent-linux-x64.agent-r36-linux-x64.20261012_101500. To go back, put it back under its original name while the component is stopped:

heia stop agent
cd ~/heia-agent
mv hexaeight-agent-linux-x64 hexaeight-agent-linux-x64.set-aside
mv hexaeight-agent-linux-x64.agent-r36-linux-x64.20261012_101500 hexaeight-agent-linux-x64
heia start agent

Renew the licence

When it ends. The agent says when the licence probably ends, at every start and once a day, in its log. In the last 7 days of a monthly licence, or the last 15 days of a yearly one, it also records a warning in the audit trail. You can ask at any time:

cd ~/hbia-agent
hexaeight-activate verify-license

This prints whether the licence works and its probable end date. The date is an estimate, because the platform does not report it. It is worked out from when the licence was installed on this machine: 30 days later for a monthly licence, or 365 days for a yearly one. A renewal before the end adds a period to that end. A renewal after the end starts a new period from the day of the renewal. newtoken and renewtoken ask whether the licence is yearly and remember the answer. If the answer was never recorded, both possible dates are shown.

Renew it in the licence folder:

cd ~/hbia-agent
hexaeight-activate renewtoken

Once the renewed licence verifies, renewtoken finds the other folders that hold this licence as a hard link, which are the router’s and the agent’s, and links them to the renewed file. It never copies the file. It lists the folders it updated. Restart what runs there so it uses the new licence:

heia restart router      # the router, then the agent

If the licence has already ended, the agent cannot fetch its keys and does not start. Its log names the licence as the likely cause. Renew, then start it again.

Remove someone’s access

Remove their policy rules, written exactly as they were added, then confirm:

cd ~/heia-agent
./hexaeight-agent-linux-x64 hexaeight-agent.json --remove-rule '[email protected],*,inbound,allow'
./hexaeight-agent-linux-x64 hexaeight-agent.json --access-review

See Policy and Compliance reports.

Where the records are

What was allowed, run and refused	the audit trail, in audit/ in the agent’s folder and the router’s: sealed, chained, never the content of a message
Conversations	~/.hexaeight-harness, one file per conversation, as plain JSON lines
Model calls	usage.jsonl in the router’s folder: one line per call, with the model, the tokens and the time it took
What a component is doing	heia logs agent, heia logs router

Checks worth scheduling

Command	Cost
hexaeight-activate verify-license	one round trip. It also prints the licence’s probable end.
hexaeight-activate verify-libs	no licence call, so it is cheap enough to run on a timer
heia status	a look at the ports, and a check that the public addresses answer

Next

• Encrypted stores: when the agent will not start
• Troubleshooting