Before you begin
Four things. Ten minutes to gather, and it saves backtracking later.
1 · A machine
Section titled “1 · A machine”| Linux | as written throughout these docs |
| macOS | nothing changes. Same commands, same layout — only the binary name differs |
| Windows | run it under WSL. That is the recommendation, not a workaround |
Windows
Section titled “Windows”Install WSL, then work inside it exactly as these docs describe — the agent, the router and the
workspace all run there, and the workspace is reachable from your Windows browser on localhost.
wsl --installEverything from that point on happens at the WSL prompt. Keep your agent folder inside the Linux
filesystem (/home/you/...), not under /mnt/c/, so file permissions behave.
Confining what a turn can do
Section titled “Confining what a turn can do”Every engine turn runs sandboxed, so it cannot read the identity files even though it runs as the agent. The mechanism differs by platform — bwrap on Linux, and on Windows because everything runs under WSL; macOS uses its own. Check yours:
hexaeight-activate sandboxWhere there is no build
Section titled “Where there is no build”Components ship as self-contained binaries, and install-agent and install-router download the
one for your platform and verify it before it can run.
Intel Macs and arm64 Linux have no published build. The command exits
2and points you at support rather than installing a near-match.
2 · .NET
Section titled “2 · .NET”hexaeight-activate is a .NET global tool:
dotnet tool install --global HexaEight.ActivateIf you do not have the .NET SDK, install it from dotnet.microsoft.com first. Everything else — the agent, the router, the workspace — is self-contained and needs nothing installed.
Check the machine reports the core count your licence must cover:
hexaeight-activate cpucores3 · The HexaEight Authenticator, on your phone
Section titled “3 · The HexaEight Authenticator, on your phone”Your identity lives on your phone, and activation is approved there rather than in the terminal. There is no way to complete the first step without it.
Search for HexaEight Authenticator in the App Store or Google Play.
What it does, and why it is not optional, is covered in The Authenticator.
4 · A licence
Section titled “4 · A licence”Buy at store.hexaeight.com. The licence code arrives by email and
is what newtoken asks for in step 2.
You buy by CPU cores, which is why cpucores matters: the licence must cover at least the
count that command reports. Current pricing is on the store.
Which licence
Section titled “Which licence”The difference is only about who may sign in to the workspace. It is not a cap on how many people your agents can serve.
| Personal | Business | |
|---|---|---|
| workspace sign-in | the owner’s address only | multiple addresses |
| people your agents can serve | unlimited | unlimited |
| cost of those people | free | free |
This surprises people, so it is worth stating plainly. A personal licence does not mean “one user”. It means one person uses the workspace. You can stand up a runner agent and let unlimited users authenticate for free through it — see Your own users. There is no per-user charge and no cap.
Choose Business when several colleagues each need their own workspace sign-in.
Adding a colleague
Section titled “Adding a colleague”There is no per-person setup. The default policy admits nobody but you, so adding someone is one rule: name their address, or their whole domain, and they sign in with their own HexaEight identity.
# one colleague
# or everyone at your domainhexaeight-activate add-policy --owner '*@yourcompany.com'They need an identity of their own in the Authenticator, which is free. Nothing else is provisioned for them, and nothing is charged per person. See Who may do what.