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.
`runner-memory`	Decide which memories a runner can see: `--list`, `--share <name> [--copy]`, `--unshare <name>`. A runner sees only its own mission until you share something into it.
`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 — pass --model to choose the runner’s own. Ports are chosen (or, with --base-port, checked) before anything is created. The runner’s external callers may use service_call and who_am_i; modify-agent --allow-tools changes that.

Start it with restart agent in the runner’s folder. It stops and starts only that folder’s agent, and gives a runner its own store (HEIA_DIR=<runner>-frontdoor/heia).

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, the fence and the mission’s own files. 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 What a mission is.

Agent frameworks as sealed missions

command	what it does
`enable crewai` · `langgraph` · `pydanticai` · `agno`	Install that framework’s published mission in one step: a pinned environment, the verified bundle, the mission installed and indexed on this machine, and its one command sealed by the agent.
`enable <framework> --venv PATH`	Use a Python environment you already have (it must import the framework); nothing is installed into it.
`enable <framework> --force`	Replace an installed mission that differs from the published one. The old one is kept under `~/.hexaeight-harness/backups/`.

Run it from your agent’s folder — or from a runner’s folder, where it installs into that runner’s own store. Re-running it is safe: a mission already installed with the published runner is left as it is. See Your framework already works.

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  |  enable <framework>        it follows a procedure / runs a framework
              ↓
          runner-memory --share                        a runner sees what you chose, nothing more
              ↓
          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.