What gets installed

The installer sets up everything an agent needs on one machine: your licence, a model router, the agent with its AI runtime, and the workspace you use in a browser. It never asks for administrator rights — the two system packages it relies on are listed below, for whoever looks after the machine.

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

Run it twice. The first run prepares the machine and stops at the licence, the one step only you can do. Run the same command again and it installs the rest.

Where it runs


Linux	x86_64
Windows	inside WSL (Ubuntu). Install WSL, open the Ubuntu terminal and run everything there. Keep HexaEight in your Linux home folder, not under `/mnt/c`.
macOS	Apple Silicon

Intel Macs and ARM Linux have no build.

Before you run it — once, by an administrator


`curl`	to download the installer
Linux: `bubblewrap` and `libicu`	`sudo apt-get install -y bubblewrap libicu-dev` on Debian or Ubuntu, `sudo dnf install -y bubblewrap libicu` on Fedora or RHEL
Ubuntu that restricts user namespaces — Azure’s Ubuntu 24.04 images do	the installer stops and prints a short AppArmor profile that lets `bubblewrap`, and nothing else, start the sandbox. Apply it once, then run the installer again.
memory	4 GB or more

bubblewrap is the sandbox every AI turn runs in. macOS needs nothing: its sandbox is built in.

The two runs

First run

Checking this machine — the platform, the prerequisites, and that the sandbox can start. It installs .NET 8 into ~/.dotnet and the hexaeight-activate command-line tool.
Licence — it asks for the owner email: the email you sign in with, the one your Authenticator vault uses. Then it stops, and you activate the licence yourself:
Terminal window
```
source ~/.bashrc          # on macOS: source ~/.zshrc
cd ~/hbia-agent && hexaeight-activate newtoken
```
It asks for the resource name from your Authenticator, a password (press Enter and one is generated for you) and your licence code, then shows a QR code to approve in the Authenticator on your phone. When it says the licence works, run the installer again. See Installing for each screen.

Second run — the same command

Model router — either run one here with your own provider key (AWS Bedrock, z.ai, Azure AI Foundry, Azure OpenAI, OpenAI, OpenRouter, or any compatible address), or use a router that already runs elsewhere. The key is typed without being shown and stays with the router.
Agent — downloaded, checked against its published hash, given its starting policy and connected to the router.
Workspace — the browser interface.
Gateway (optional) — makes the agent and the workspace reachable from anywhere.
Start at login — hands everything to the system’s service manager.

It ends with the address of your workspace. Open it, sign in with your Authenticator and ask something: an answer proves the whole chain works.

What ends up where

Folder	What it holds
`~/hbia-agent`	Your licence — `env-file` and `hexaeight.mac`, bound to this machine. Never move, rename or copy them.
`~/heia-router`	The router, and your provider key.
`~/heia-agent`	The agent: its settings (`hexaeight-agent.json`), its policy and its encrypted stores.
`~/.heia/runtime/harness`	The harness — the AI runtime the agent starts for every turn — and, if they download, small local vision models that describe images for models that cannot see them.
`~/.heia/runtime/workspace`	The workspace: the web pages and the small server that serves them.
`~/.hexaeight-harness`	What the harness keeps: your memories, your missions and your conversations.
`~/.heia/bin`	The `heia` command, and the two tunnel programs the gateway uses.
`~/.dotnet`	.NET 8 and `hexaeight-activate`.

The router and the agent each get the licence as a hard link — the same file under a second name, never a copy. A copy of a licence file would be a second licence.

Ports

Port	What answers
5100	the router
8770	the agent
5620	the workspace, at `http://localhost:5620`

The agent’s helper processes listen only on 127.0.0.1. The gateway opens nothing inbound: its tunnels connect outward. The agent’s tunnel carries only messages that are already encrypted end to end; the workspace’s tunnel serves its web pages over HTTPS.

What is on when it finishes

Only you. A starting policy where you, the owner, can sign in and use the agent, and everything else is refused until you allow it.
Machines. This computer is added as a machine you can work on from chat, and every command the AI proposes waits for your approval.
Reachable from anywhere. The agent publishes itself under its name, so your workspace and other agents find it by name. To keep everything on this machine instead:
Terminal window
```
curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash -s -- --skip-gateway
```

The gateway’s addresses are temporary and change when the machine restarts. The agent publishes its new one by itself; for the workspace, run the installer again to get the new link. For a fixed address on your own domain, use a named Cloudflare tunnel.

After the install

heia status                       # what is running
heia restart [agent|router|all]   # restart, through whatever runs it
heia logs [agent|router]          # follow a log

heia works from any folder. Once the service manager runs the services, restart them with heia rather than hexaeight-activate restart — a second copy started beside the first fights it for its port.

On a Linux server the installer also lets the services keep running when nobody is logged in; if it is not allowed to, it says which command an administrator runs.

On Windows, if WSL is not set up to run services, everything keeps running but does not start again by itself. After restarting Windows, open Ubuntu and run heia start all.

Running it again

Safe at any time. It compares what is installed with the latest releases, downloads only what has a newer one, and keeps each previous binary beside the new one. See Lifecycle.