HexaEight.Activate 1.0.15

HexaEight.Activate

One tool for HexaEight identities: install the agent and the router, activate a machine token, verify what is installed, lock an agent down, and control which builds it will accept messages from.

dotnet tool install --global HexaEight.Activate

Command name is hexaeight-activate. Requires .NET 8 or later.

Start to finish

dotnet tool install --global HexaEight.Activate
mkdir my-agent && cd my-agent

hexaeight-activate cpucores           # how many cores must the licence cover?
hexaeight-activate newtoken           # INTERACTIVE - activate the identity FIRST
hexaeight-activate install-agent      # download + verify the binary for this platform
hexaeight-activate install-examples   # a local model + examples - no API key needed
hexaeight-activate init-policy        # deny everyone, admit one owner, gate on this build
./hexaeight-agent-linux-x64

The identity comes before the binary. An agent with no identity cannot start, so installing it first only produces something that will not run — and the folder you activate in is the folder the agent must live in.

install-examples is what makes the first run worth doing: it downloads a small model that runs on CPU, points the agent at it, and writes runnable examples beside it. Nothing to sign up for. It is for seeing the wiring work - production wants a real provider key.

The router is a separate product, installed the same way:

hexaeight-activate install-router
./hexaeight-router-linux-x64 --setup

newtoken cannot be automated: it prompts for a resource name, password and licence code, and requires scanning a QR code in the HexaEight Authenticator app. Everything else here can run unattended.

Commands

Every command runs in the current working directory, which must be the folder holding env-file and hexaeight.mac. Running elsewhere fails with "no identity in this folder" - the single most common mistake.

Installing

hexaeight-activate install-agent               # into the current folder
hexaeight-activate install-agent --dir /opt/hbia
hexaeight-activate install-agent --force       # replace a different file at that path

The expected hash ships inside this package, not alongside the download. A checksum published next to the file it describes proves only that the two were produced together - whoever can replace one can replace the other. Because the value arrives through nuget.org, the release server only has to serve bytes; a substituted file fails the comparison and is deleted before it can run.

Behaviour worth relying on:

• A failed hash check deletes the download and exits 1. Nothing unverified is left on disk.
• Re-running on a good install prints "Already installed and verified" and exits 0 without re-downloading. Safe in a provisioning script.
• A different file already at the target path is refused rather than overwritten (--force overrides).
• Downloads to <name>.partial first, so an interrupted run never leaves a half file in place.

Published builds: win-x64, linux-x64, osx-arm64. Intel macOS and arm64 Linux are not published - those exit 2 and tell you to email support@hexaeight.com, who will build one. No near-match is installed: the attestation hash is per architecture, so no other build can stand in, including the arm64 build under Rosetta.

The router is fetched and verified the same way. It is not gated on an approved-build list yet - deliberate and deferred, so nobody mistakes its absence for a gate that is protecting them.

Locking an agent down

hexaeight-activate init-policy                                   # asks who
hexaeight-activate init-policy --kind personal --owner you@co.com
hexaeight-activate init-policy --kind business --owner '*@co.com'
hexaeight-activate add-policy --owner colleague@co.com           # widen it later

A fresh agent is reachable and accepts anyone who can authenticate, from any build. init-policy closes both halves, which are different questions:

• Who is calling - identity. Everything is denied; the owner is the single exception. That covers /api/incoming and /external/incoming too.
• What is calling - origin. The build installed here is approved, along with every officially published build, and the permissive wildcard is dropped.

Personal admits one email. Business takes an email or a whole domain as *@company.com. Either way you can widen it afterwards with add-policy, and a running agent picks up both the policy and the build list without a restart.

It writes owner into hexaeight-agent.json as well as the encrypted policy. Both are required: with the policy alone the agent starts in developer mode and admits anyone, which looks locked and is not.

Verifying an installation

./hexaeight-agent --probe ; echo $?    # 0 = the platform trusts this build, 2 = it does not
hexaeight-activate verify-libs         # every library matches what we published to nuget.org

Run --probe before verify-libs: a single-file agent only writes its assemblies to disk when it first runs, and there is nothing to check until then.

verify-libs finding nothing is itself a finding. Official releases place their assemblies on disk precisely so they can be checked; a build with nothing to check was not packaged the way we publish, and should be treated as suspect rather than convenient.

verify-env does the licence check first, then everything verify-libs does, and refreshes the approved-build list as a side effect - which is why it is the right thing to run on a schedule.

Approved builds

Every envelope carries a PROTECTION HASH: the hash of the executable that sent it, derived by the library rather than claimed by the caller. An identity can be told which builds it accepts, making "only official builds may call our service" enforceable rather than a policy document.

hexaeight-activate approve-builds --list        # current rules, and the list this tool carries
hexaeight-activate approve-builds --tighten     # ENFORCE: refuse anything not listed
hexaeight-activate approve-builds --allow-any   # back to accepting any build
hexaeight-activate approve-builds --add-hash <128-hex>   # approve a build you trust
hexaeight-activate approve-builds --add-file <path>      # ...by hashing a file

Until --tighten runs, everything is accepted - a fresh identity is not gated.

Prefer --add-hash. Which file a build attests depends on how it was published:

--add-file has to infer this, and a wrong guess writes a rule that silently never matches: the peer is refused forever with nothing in the log to explain it. A value read from the peer's own PROTECTIONHASH cannot be wrong.

The official hashes ship inside this package and are applied by verify-env, so keeping a machine current means updating the tool - no hash is ever copied by hand. Older releases stay approved deliberately: dropping a build would refuse every peer still running it.

Writing your own engine

You do not need to modify or rebuild the agent, and that is not the supported path. Write an engine and let the agent enclose it - the contract is one function:

invoke(sessionId, message) -> reply

The agent supplies identity, encrypted transport, sessions and policy. You supply the capability. install-examples writes a complete working engine to examples/my_engine.py in about thirty lines.

If you genuinely need a custom agent rather than an engine, the only supported SDK is .NET and the libraries are published - contact support@hexaeight.com and we will show you how.

For automation

Safe to run unattended, in this order:

hexaeight-activate install-agent --dir "$DIR" || exit 1
cd "$DIR" && ./hexaeight-agent --probe || echo "unblessed build"
hexaeight-activate verify-libs || echo "library mismatch"
hexaeight-activate init-policy --kind personal --owner "$OWNER" --no-prompt

Not automatable: newtoken and renewtoken (QR approval in the Authenticator app).

Notes for scripted use:

• Never copy hexaeight.mac between machines. It is machine-bound and copying it breaks the identity. To share one licence between programs on the same machine, hardlink it.
• env-file and hexaeight.mac are credentials. Keep them out of version control and images.
• --probe caches its verdict for 60 seconds in .probe.state; delete that file when retrying.
• Exit codes are meaningful - branch on them rather than parsing output.

Diagnosing

Links

• Agent releases: https://github.com/HexaEightTeam/hbia-agent/releases
• Router releases: https://github.com/HexaEightTeam/hbia-router/releases
• HexaEight.Bridge: https://www.nuget.org/packages/HexaEight.Bridge
• Docs: https://hexaeight.com/docs

Apache-2.0. The cryptographic libraries it links against are governed by the HexaEight identity licence.