3 · Connect a model

Your identity exists and the agent is installed, but not started. The router comes first.

Agents never hold model credentials. An agent asks for a route name; the router resolves that to a real provider and decides whether this agent, acting for this person, may use it.

When you can skip this step. The router exists to reach a model. An engine that does its own work and never calls one — a search service, a calculation, an integration — needs no router at all. Everything on this page applies the moment a model is involved, which includes the built-in chat and mission engines.

That indirection is what lets you rotate a provider key in one place, swap models without touching any agent, and see who spent what.

Two ways to run this

Both give the agent a model. They differ in who holds the provider key, which is a commercial decision as much as a technical one.

	you hold the keys	someone else does
provider account	yours	theirs
who sees your end users	only you	only you, if you choose
read	this page, then Run your own router	Forward to an external router

If you are unsure, run your own. It is fewer moving parts, and you can add forwarding later without changing any agent.

1 · Install the router in its own folder

The router is a separate component with its own directory:

mkdir my-router && cd my-router
hexaeight-activate install-router

Intel Macs and arm64 Linux have no published build. The command exits 2 and points you at support rather than installing a near-match.

2 · Give the router an identity

The router runs under a HexaEight identity, the same as an agent.

If it shares a machine with your agent, it can share that licence — by hardlinking the two identity files, never copying them:

ln ../my-agent/hexaeight.mac hexaeight.mac
ln ../my-agent/env-file      env-file

A hardlink is a second name for the same file. ln without -s makes one. This matters because hexaeight.mac is machine-bound: a second name on the same machine is fine, a copy on another machine is not.

On a separate machine, activate it normally instead:

hexaeight-activate newtoken

3 · Add a provider

hexaeight-activate upstreams

It asks which provider you want — anthropic, openai, azure, bedrock, openrouter or ollama — and for the key, then writes upstreams.yaml beside the binary. (The router binary’s own --setup does the same thing and writes the same file.)

ollama is the option to pick if you want a local model and no provider account.

Then see what it will serve, and what your routes are called:

hexaeight-activate upstreams --list     # the route names you use below
hexaeight-activate models               # what each provider will serve

4 · Decide how callers are identified

Before exposing it, decide whether agents may keep their own callers private. Add one line at the top of upstreams.yaml — the same file, read alongside the upstreams:

requireIdentifiedCaller: true

you are running	setting	why
your own router	true	you are accountable for what it is used for, and you want per-person metering
a router serving other people’s agents	leave it off	their customer list is not yours to require

It rejects rather than downgrades: an anonymous session against a router that requires identification is refused outright, and the log says why. Full reasoning in Forward to an external router.

5 · Start the router

hexaeight-activate restart router

Run it from the router’s own folder. It starts the router in the background and leaves your terminal free — running the binary directly works too, but holds the terminal for as long as the router runs.

Confirm it is enforcing, in router.log:

Authorization: Casbin (encrypted policy at …/router-policy.he, bootstrap=False)
[policy] 9 rule(s):

bootstrap=True, or a rule whose sender is *, means the router is open to anyone who can reach it — the state a fresh install begins in.

Close it with one command, from the router’s folder:

cd my-router
set -a; . ./env-file; set +a
./hexaeight-router-linux-x64 --init-policy

The env-file line loads the router’s identity — without it the command cannot read the sealed policy.

It asks who may use the router, which models, and who may vouch for them, then writes the rules and removes the two bootstrap wildcards. Nothing is written until you confirm. Full walkthrough in Run your own router.

6 · Tell the agent which route to use

Back in the agent’s folder:

cd ../my-agent
hexaeight-activate engine --add chat \
    --name  chat \
    --model "<your-route>|<the provider model id>" \
    --router "web0-quiet-amber-fern42|http://127.0.0.1:5100"

flag	meaning
--name	what the workspace will call this engine
--model	route|model. The left half is one of your route names from upstreams --list; the right half is the provider’s real model id, from hexaeight-activate models
--router	identity|url — the router’s identity and where it listens. If you hardlinked under Give the router an identity above, that is the same name as your agent

7 · Now start the agent

hexaeight-activate restart agent

[licence] personal licence - N policy rule(s) in force - agent may be exposed normally
[identity-agent] <your-agent-name> listening on :8770

the line says	meaning
N policy rule(s) in force	permissions are being enforced. 0 means they are not
listening on :8770	the agent is up

Output goes to agent.log in the agent’s folder, and router.log in the router’s.

Order matters, every time. Router, then agent, then workspace. An agent started before its router reports a licence error that has nothing to do with the licence — if you see one, check the router is running before you check anything else.

---

Next: 4 · Connect the workspace — a browser interface to the agent you just started.