Installing

Installing takes one command, run twice. In between, you activate your licence with the HexaEight Authenticator on your phone.

1 · Set up the Authenticator on your phone

Install HexaEight Authenticator from the App Store or Google Play. It is free.

Enter your email

Verify it, set a password

Your identity is ready

Add a resource

1. Create your identity. Enter your email address. Use a real, permanent one: an identity cannot be deleted without reinstalling the app.
2. Verify it and set a password. Open the email from [email protected] (check spam) and scan its QR code, or tap the link if you read it on the same phone.
3. Add a resource for your agent. Tap + Add and choose Generic Resource. The app gives it a name such as api12-lock-java-pressure83: that becomes your agent’s name. You will type it in step 4.

To use a name on your own domain, such as agent.yourcompany.com, add a Domain Resource instead. It needs an email address on that domain and a DNS record; see The Authenticator.

2 · Get a licence

Buy one at store.hexaeight.com. The licence code arrives by email. Licences are sold by CPU cores; the installer shows how many this machine has when it starts.

3 · Run the installer

On Linux (x86_64), on Windows in the WSL Ubuntu terminal, or on a Mac with Apple Silicon:

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

It checks the machine, installs what it needs, asks for your email address (the one in your Authenticator) and stops at the licence:

━━ 2 · Licence
  The owner is the email you sign in to the workspace with — the one your Authenticator vault uses.
  Owner email: [email protected]
  ✓ owner: [email protected]

  Now activate the licence — this step is yours.

      source ~/.bashrc
      cd ~/hbia-agent && hexaeight-activate newtoken

  When it says the licence works, run this installer again — it carries on from here.

On Linux it also checks for bubblewrap and libicu, which an administrator installs once; it says so if they are missing.

4 · Activate the licence

Run the two lines it showed you (on macOS the first is source ~/.zshrc):

source ~/.bashrc
cd ~/hbia-agent && hexaeight-activate newtoken

It asks three things:

                    Machine Token License Activation
----------------------------------------------------------------------
Enter Resource Name : api12-lock-java-pressure83
Enter New Password For Your Resource : [Press Enter to Generate a Password]
Enter the License Code Received in your Email : ••••••••
----------------------------------------------------------------------
                    Do You Want to Display A QRCode ? [Y/N]

1. Resource name: the name from step 1.
2. Password: just press Enter, and a password is generated for you.
3. Licence code: the code from your email.

Answer Y to show the QR code. On your phone, open the Authenticator, tap your resource (it says Tap to scan) and scan the QR code. When the app has approved it, press any key in the terminal.

It asks whether your licence is yearly, then checks that the licence works:

  Is this a yearly licence? [y/N]: n

Activation completed. Running a quick license verification...

  Identity: api12-lock-java-pressure83

  Congratulations — your HexaEight license is installed and working.

5 · Run the installer again

The same command:

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

It sets up the router (you choose your model provider and type its key, which is not shown), installs and starts the agent and the workspace, makes them reachable from anywhere, and has them start at login. It ends like this:

━━ 6 · Gateway (reachable from anywhere)
  ✓ agent reachable at https://<four-words>.trycloudflare.com
  ✓ registered as api12-lock-java-pressure83 — other agents find it by name
  ✓ workspace reachable at https://<four-words>.trycloudflare.com

━━ 7 · Start at login
  …

  Done.  Open https://<four-words>.trycloudflare.com and sign in as [email protected] with your Authenticator.
  Ask it something — an answer in the browser proves the whole chain.

The address after Open is your workspace. It works from any browser, including your phone. On the machine itself, http://localhost:5620 works too. heia status shows the addresses again at any time.

6 · Sign in

1. Open that address and enter your email.
2. Choose Scan with HexaEight Authenticator. A QR code appears.
3. In the Authenticator, tap Scan to authenticate on your identity and scan it.
4. Type the access code the app shows, and choose Continue.

Then ask something: an answer proves the whole chain works. See The workspace for what is where.

Options

keep everything on this machine, with no public address	curl -fsSL …/install.sh | bash -s -- --skip-gateway
do not add this computer under Machines	curl -fsSL …/install.sh | ENABLE_FLEET=0 bash

With --skip-gateway, the workspace is at http://localhost:5620 on that machine only.

After the install

heia status                       # what is running, and its addresses
heia restart [agent|router|all]   # restart, through the service manager
heia logs [agent|router]          # follow a log

The public addresses 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.

To update, run the same command again: only what has a newer release is downloaded. To remove everything, follow UNINSTALL.md. For what was installed where, see What gets installed.