Installing

You probably should not do this by hand

The install guide is written for an AI agent — it is titled “Installing HBIA — a guide for an AI agent” and addresses one directly. Give any CLI coding agent this line and it does the install, checking each step:

Install HexaEight on this machine by following https://www.hexaeight.com/llms-install.txt — read it first, tell me which OS section applies, and ask me for the licence code and the provider API key before you start.

See Install with an agent.

One step is yours, and only one

Activating the licence. hexaeight-activate newtoken asks for a password that should not pass through an agent, and needs a QR code approved in the Authenticator on your phone. A good agent creates the folder, hands you the command, and waits. Everything else is its work.

You will also be asked for a provider API key, and shown the model list so you can choose the model — that choice is yours, and the list usually spans several vendors at very different prices.

Before anything is installed

Identity lives on your phone, so this comes first — there is no offline mode:

1. "Do you have the HexaEight Authenticator app on your phone?"
   If not: App Store or Google Play, search "HexaEight Authenticator". It is FREE.
2. "Have you set up your email vault in it?"
   The vault IS the person. Every agent becomes a resource under it, which is what puts a
   provable person behind the agent. Without a vault there is nothing to approve with.
3. "Do you have a licence code?"
   Bought at store.hexaeight.com, arrives by email. Licensed BY CPU CORES, so the code must
   cover at least what `hexaeight-activate cpucores` reports on this machine.
4. "What should this agent be called?" — see the next card; do not decide it for them.

The folders

Preferred on a fresh machine — the licence folder holds only the licence, and each component gets its own folder:

folder	what it is
~/hbia-agent	the licence folder. newtoken runs here; it holds the original env-file and hexaeight.mac. Nothing is installed here and nothing runs here — and it must never be moved or renamed
~/heia-agent	the installed agent
~/heia-router	the router
~/heia-runner	a runner agent — one sealed mission for outside callers, optional
~/heia-workspace	the browser UI’s files, optional — its default location is fine too

Keeping the credentials in a folder nothing executes out of makes it obvious what has to be backed up and never moved.

The single-folder layout is also fine. INSTALL.md puts the agent in the licence folder — ~/hbia-agent, ~/hbia-router, ~/hbia-workspace — and says outright that those names are a convention, not a requirement. If you already have that layout, or prefer it, keep it; there is nothing to migrate.

Either way, one thing does not vary. Every component folder gets env-file and hexaeight.mac HARDLINKED from ~/hbia-agent. ln with no -s. Never cp, never mv, never ln -s.

The files are machine-bound; a copy is how an identity ends up failing to validate. A hardlink is the same inode, so there is exactly one set of credentials on the machine. This is what add-runner --from does internally, so it is the supported mechanism.

Or do it yourself

Same procedure, by hand. Start with the section for your machine, then follow Everything after that — identical on all three.

Linux

dotnet tool install --global HexaEight.Activate || dotnet tool update --global HexaEight.Activate
hexaeight-activate cpucores

Linux binaries carry the -linux-x64 suffix. The sandbox is bubblewrap, a sudo install.

On Ubuntu 23.10+ bubblewrap may install successfully and still be unable to run. Check it with the sandbox card BEFORE starting the agent, not after.

Never: do not install on arm64 Linux — there is no build; install-agent exits 2

macOS

dotnet tool install --global HexaEight.Activate || dotnet tool update --global HexaEight.Activate
hexaeight-activate cpucores

Binaries are hexaeight-agent-osx-arm64 / hexaeight-router-osx-arm64. Wherever a guide writes hexaeight-agent-linux-x64, use the osx-arm64 name, or the glob ./hexaeight-agent-*.

The sandbox is sandbox-exec, built into the OS: hexaeight-activate sandbox should say WORKING with nothing to install. There is no bubblewrap on macOS and nothing to apt-get — if you are installing a sandbox on a Mac you are on the Linux path by mistake. There is no /proc, so any recipe reading /proc//exe is Linux-only. ss does not exist; use lsof -ti tcp:<port>.

Never: do not install on an Intel Mac — there is no build; install-agent exits 2

macOS has two extra steps once the agent is installed, below. Skipping either gives a working-looking install where nothing answers.

Windows

wsl --install

Run everything at the WSL prompt. The agent, the router and the workspace all run inside WSL, and the workspace is reachable from the Windows browser on localhost.

Keep all four folders inside the Linux filesystem (/home/you/…), NEVER under /mnt/c/, or file permissions misbehave. Running under WSL is the recommendation, not a workaround. There is no native Windows binary.

Never: never put any of the four folders under /mnt/c/

From the WSL prompt, follow the Linux path above and everything below it.

Everything after that

Identical on every OS, in this order. Each command is checked in the install guide.

commands	what it gives you
mkdir -p ~/hbia-agent cd ~/hbia-agent && hexaeight-activate newtoken ls -l ~/hbia-agent/env-file ~/hbia-agent/hexaeight.mac && cd ~/hbia-agent && hexaeight-activate verify-license	The licence — the ONE step the human runs, not the agent
mkdir -p ~/heia-router ln ~/hbia-agent/env-file ~/heia-router/env-file ln ~/hbia-agent/hexaeight.mac ~/heia-router/hexaeight.mac ls -li ~/hbia-agent/hexaeight.mac ~/heia-router/hexaeight.mac hexaeight-activate install-router --dir ~/heia-router cd ~/heia-router && hexaeight-activate upstreams cd ~/heia-router && hexaeight-activate models	Install the router into ~/heia-router and give it a provider key
mkdir -p ~/heia-agent ln ~/hbia-agent/env-file ~/heia-agent/env-file ln ~/hbia-agent/hexaeight.mac ~/heia-agent/hexaeight.mac ls -li ~/hbia-agent/hexaeight.mac ~/heia-agent/hexaeight.mac hexaeight-activate install-agent --dir ~/heia-agent cd ~/heia-agent && hexaeight-activate sandbox `ls -l ~/.claude/settings.json 2>/dev/null
cd ~/heia-agent && hexaeight-activate install-workspace	Put the browser workspace up, and prove the whole chain end to end
cd ~/heia-agent && hexaeight-activate autostart on	Make it all come back after a reboot

Order matters. The router must answer before the agent starts, and the agent must be sealed before the workspace shows anything. Without hexaeight-activate autostart on, nothing comes back after a reboot.

macOS only — the two that fail silently

Do both before the first turn. Each leaves every component running and every check green, and each surfaces as a turn that will not answer.

1. Clear quarantine and ad-hoc re-sign the binary

cd ~/heia-agent
xattr -d com.apple.quarantine ./hexaeight-agent-osx-arm64 2>/dev/null
codesign -s - -f ./hexaeight-agent-osx-arm64
codesign --verify --strict ./hexaeight-agent-osx-arm64 && echo "signature OK"

2. Mask the credential FILES, not the folder

cd ~/heia-agent
cp hexaeight-agent.json hexaeight-agent.json.bak_$(date +%Y%m%d_%H%M%S)
python3 - <<'PY'
import json, os
p = 'hexaeight-agent.json'
d = json.load(open(p))
mask = sorted(os.path.join(b, f)
              for b in {os.path.realpath('.'), os.path.abspath(os.path.expanduser('~/heia-agent'))}
              for f in ('env-file', 'hexaeight.mac', 'agent.uuid'))
d['jail'] = {'enabled': True, 'mask': mask}
json.dump(d, open(p, 'w'), indent=2)
print(json.dumps(d['jail'], indent=1))
PY

By default the jail hides the agent’s whole current directory. On Linux the engine is moved out of that folder before it starts, so it never notices. On macOS it is NOT moved, so it starts inside a directory it may not read and dies immediately with EPERM.

Mask the credential FILES instead of the folder — same protection, and the engine can start. List both path forms (/Users/… and /Volumes/Macintosh_HD/Users/…): macOS reaches one directory by two names through a firmlink. Back up hexaeight-agent.json first.

3. Prove BOTH halves — the engine starts AND the credentials stay hidden

cd ~/heia-agent
M=$(python3 -c "import json;print(' '.join('(subpath \"%s\")'%m for m in json.load(open('hexaeight-agent.json'))['jail']['mask']))")
P="(version 1)(allow default)(deny file-read* $M)"
/usr/bin/sandbox-exec -p "$P" ~/.heia/runtime/node_modules/.bin/claude --version
/usr/bin/sandbox-exec -p "$P" /bin/cat env-file

A version number from the first command PLUS ‘Operation not permitted’ from the second is the pass. Both halves matter; one without the other is a failure.

A version with a READABLE env-file means the mask is wrong and the engine can read the licence — stop and fix it. EPERM from the FIRST command means the mask still covers the whole folder. This is narrower than the Linux default: the engine can still read other files in the folder (sessions.he, engines.he), which are encrypted at rest.

Linux and WSL skip both.

Adding a runner

Add a runner in ~/heia-runner — a second agent serving one sealed mission to outsiders Optional, and not part of a first install.

hexaeight-activate add-runner --from ~/hbia-agent --dir ~/heia-runner
ls -li ~/hbia-agent/hexaeight.mac ~/heia-runner/hexaeight.mac

A runner is its OWN folder and its own agent process, sharing the identity by hardlink. add-runner --from does the hardlinking itself — do not pre-create the files.

—from supplies the IDENTITY ONLY: its hexaeight.mac and env-file are hardlinked into the new folder, never copied. Two agents under one identity that share a folder also share sessions, engines and ports — which is why the runner gets its own.

hexaeight-activate stop and restart are FOLDER-BLIND on a multi-agent machine.

They match every agent process, so running them from the runner folder also stops the main agent. On a machine with a runner, stop a component by its own PID or use a per-folder script. True as of Activate 1.0.65.

Upgrading

cd ~/heia-agent
hexaeight-activate whats-new
hexaeight-activate update

Per-release ordering is not guessable from the tool’s output — read UPGRADE.md for the release in hand. On macOS, re-sign the binary again after every upgrade, or it dies with Killed: 9.

Removing it: UNINSTALL.md.

---

Next: 1 · Your identity starts on your phone