hexaeight-activate — the whole CLI

One tool does the whole lifecycle: activate an identity, install the components, define engines, provision agents, set policy, and run them. This page is the map.

dotnet tool install --global HexaEight.Activate
hexaeight-activate help

Almost every command acts on the current directory. An agent folder is an identity, and you run these commands inside it. On a machine with several agents that is not a nicety — it is what keeps one agent’s command from touching another.

Identity

command	what it does
`newtoken`	Activate an identity. Prompts for resource name, password and licence code, then a QR approval from the Authenticator app. Writes `env-file` and `hexaeight.mac`.
`renewtoken`	Renew an expiring licence with a new code. Updates `HEXAEIGHT_MACHINETOKEN` in `env-file`.
`verify-license`	The fast check. One call: does this licence work? Use this one.
`verify-env`	The wide check — licence, approved builds, libraries against nuget, tool version. Four round trips, and on an agent folder the library check can take minutes.
`verify-libs`	Libraries only, no licence call. Cheap enough to schedule. `--restore` replaces mismatches.
`cpucores`	What this machine reports. Your licence must cover at least this many.

env-file and hexaeight.mac are the identity, and both are machine-bound. Never copy them to another machine or another folder — hardlink hexaeight.mac if one machine needs the same identity in two places.

Install a component

command	installs
`install-agent`	the identity agent, verified against a published hash before it runs
`install-router`	the LLM router
`install-workspace`	the web workspace
`install-examples`	a local model and runnable examples

Every download is hash-verified. A binary that does not match the published hash is deleted rather than run, and the hash list is fetched at runtime — so a bad build can be withdrawn centrally without anyone redeploying.

install-workspace --force overwrites config.js. Back it up first if you have edited it.

The router — which models an agent may reach

command	what it does
`upstreams`	Which providers this router can reach. Pick from a list. `--list` prints route names.
`models`	Ask each configured provider what it will actually serve.

The router holds the model credentials so no agent ever does. An agent asks for a route name; the router decides whether that agent, acting for that person, may use that model.

Engines — what an agent can actually do

An engine is the unit of work an agent encloses. engine defines one and seals it.

hexaeight-activate engine --add runmission \
    --name  missionrun-external \
    --model "glm5br|zai.glm-5" \
    --router "web0-quiet-amber-fern42|http://127.0.0.1:5100" \
    --mission Support_Triage_v3 \
    --dir   /home/you/my-runner \
    --file  /home/you/my-runner-frontdoor/mission-runner.sh

flag	meaning
`--name`	what skills and the workspace will call it
`--model`	`route\|model` — the route the router resolves
`--router`	`agent-name\|url`
`--mission`	seals it to one mission; external callers cannot choose another
`--file`	a wrapper script to run instead of the engine binary
`--dir`	which agent folder to seal into

Omitting --file on a re-seal silently unbinds the wrapper. Nothing errors. The turn returns a permissions frame in a couple of seconds and no work happens. If you re-seal an engine that had a wrapper, pass --file again.

Changing one field without retyping the rest

The agent binary can export the sealed entries as plaintext for audit, and re-seal a modified one verbatim. This is how you change a mission or a model without losing anything else:

./hexaeight-agent-linux-x64 export --plaintext --out ./dump.json
# edit the one field in ./dump.json, drop the "router" key into a variable
./hexaeight-agent-linux-x64 add-engine --name <name> --router "<router>" --json @./entry.json

The export is plaintext. It contains everything sealed in the entry, including any headers you attached to a route. Write it somewhere you control, use it, and remove it — not to a shared temporary directory.

add-engine seals the object verbatim, so everything you did not touch survives byte-for-byte. There is no plaintext import — the dump is for reading, and re-sealing goes through the agent’s own key.

Provision another agent

command	what it does
`add-external-agent` (alias `add-runner`)	Create a runner: a second agent serving one sealed mission to outside callers.
`add-api`	Seal an existing HTTP service as a named route on this agent.
`modify-agent`	Change a provisioned agent’s peer, owner, tiers, tools or ports.

hexaeight-activate add-external-agent \
    --from /home/you/my-agent      \   # identity only — hardlinked, never copied
    --dir  /home/you/my-runner     \
    --mission  My_Mission          \
    --license  personal            \
    --owner    [email protected]     \
    --base-port 8930

--from supplies the identity only: its hexaeight.mac and env-file are hardlinked. It may be a bare licence folder. --model and --router are read from the source agent’s sealed engines when it has any.

See The external front door for the full path, including the parts provisioning does not do for you.

Missions — a procedure an agent follows every time

command	what it does
`agskill-export`	Export a mission as a portable `.zip` bundle.
`agskill-import`	Import one: `--in <bundle.zip> [--root <harness>] [--force]`

hexaeight-activate agskill-import --in mission-My_Workflow.zip --root ~/.hexaeight-harness

It refuses to overwrite an existing mission — mission memory exists (use --force to overwrite). Read that line: without --force your import did nothing and the old version is still live.

A bundle carries the procedure cards, the flowchart and the fence. It does not carry the corpora they search, and policy grants never travel — they are identity-specific and must be added on both agents. See Missions.

Policy — who may do what

command	what it does
`add-policy --owner <email>`	Write the baseline rules for this agent.
`add-policy base-default`	The full baseline set.
`list-policy`	Who may reach this agent — and what the enforcer actually decides.
`front-door-policy`	Who may sign in through the alt-auth front door.

list-policy is the one to trust. A rule that is present but does not match reads as protection and is not. Check with the subject you care about:

hexaeight-activate list-policy --subject [email protected]

Rules are default-deny. See Policy.

Running it

command	what it does
`restart`	Restart a component: `agent`, `workspace`, `router`.
`stop`	Stop one and leave it stopped.
`update`	Replace one component and restart only that one.
`autostart`	Start router, then agent, then workspace at login — in that order.
`sandbox`	Can turns be confined on this machine, and does the sandbox work?

Order matters: router first, then agent, then workspace. An agent that starts without its router reports a licence error that has nothing to do with the licence.

On a machine running several agents, read the output. A folder-scoped restart names what it left alone:
stopped agent (43369, 43370)
left alone: agent belonging to another folder (1987, 2001, 2027)
No left alone: line means it may have stopped every agent on the machine — check the others are still up before carrying on.

The order you will actually use them

newtoken  →  install-agent  →  add-policy            an identity, with rules in force
              ↓
          install-router  →  upstreams  →  engine      it can reach a model
              ↓
          restart router  →  restart agent             in that order, always
              ↓
          install-workspace                            you can talk to it
              ↓
          add-api  |  add-external-agent               it can serve others
              ↓
          agskill-import                               it follows a procedure
              ↓
          list-policy                                  confirm who may reach it

add-policy is near the top on purpose: an agent with no rules enforces nothing, so it is written before the agent first starts rather than bolted on afterwards.