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. The
installer runs most of these for you; the agent’s and the
router’s own commands are at the end.
Terminal window
hexaeight-activatehelp
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.
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, and asks whether the licence is yearly.
renewtoken
Renew the licence with a new code, and say whether it is yearly. Once the renewed licence verifies, the other folders that hold it as a hard link are linked to the renewed file, never copied. See Renew the licence.
verify-license
The fast check. One call: does this licence work? It also prints the licence’s probable end. 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.macare the identity, and both are machine-bound. Never copy them
to another machine or another folder. If one machine needs the same identity in two folders,
hard-link both files.
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 --forceoverwrites config.js. Back it up first if you have edited it.
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.
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.
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:
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.
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.
Terminal window
hexaeight-activateadd-external-agent\
--from~/hbia-agent\ # identity only — hardlinked, never copied
--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 agentin 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
hexaeight-activatemission-import--inMy_Workflow.zip# on the other agent
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 flowchart, the cards, the mission’s own files and the memories it names: your
own documents, and a pointer to each memory another agent serves. Very large memories are left out
unless you add --include-large; --no-data keeps only the pointers. Keys, secrets, policy rules
and command approvals never travel — they are set up again on the agent that imports it. See
Missions.
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.
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.
After the installer, use heia instead (heia restart, heia stop, heia status). The
service manager runs the components then, and a copy started beside it fights it for the port. See
Lifecycle.
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.
Run from the agent’s folder. The binary is hexaeight-agent-linux-x64, or hexaeight-agent-osx-arm64
on macOS. These open the agent’s sealed stores, so only its owner can run them.