Settings — every file, every key

Three tools touch settings, and knowing which one owns what removes most of the confusion:

tool	what it is for
hexaeight-activate	almost everything — identity, install, engines, policy, running components
./hexaeight-agent-...	the agent’s own sealed stores: policy rules, vouches, engine entries
./hexaeight-router-...	the router’s sealed policy, and its upstreams

The rule of thumb: hexaeight-activate unless the thing is sealed under a component’s own key, because then only that component can write it.

---

hexaeight-agent.json — the agent’s configuration

Plain JSON in the agent’s folder. Edit it with any editor, then restart the agent.

key	what it does
port	the agent’s main port
owner	the address policy is enforced against. Without it, no rule applies at all
license.type	personal or business — decides who may sign in to the workspace
register	publish this agent to the registry so others can find it by name
external.retentionDays	How long external session transcripts are kept before the agent prunes them. 1 to 365, default 365. Does not touch the harness .jsonl trails, which nothing expires
reach.mode	how the outside world reaches it — cloudflared, tailscale, ngrok, local (publishes this machine’s LAN address) or none (publishes nothing; it calls out but accepts nothing). See Architecture
reach.bin	path to the tunnel binary. If it is missing, the tunnel silently does not start and registration is skipped
jail.enabled	mask the identity folder from engine turns. Leave it on
llmPort, sharedMcpPort, externalMcpPort, bindPort, missionStatePort	its own ports, so several agents can share a machine
services	{} on a runner — no Node-RED, browser or memory service
external.engine	which sealed engine serves external callers
external.allowTools	tools an external turn may use, e.g. service_call
external.authTiers	dde-auth,byoa — who may call. Absent on an API agent
api.tiers	["dde-auth"] for agent-to-agent calls. This exact string
external.api.enabled	the API layer. A sealed route with this off is invisible

upstreams.yaml — the router’s only config

In the router’s folder, written by hexaeight-activate upstreams (or the router’s --setup). There is no router.yaml — settings and upstreams share this one file.

key	what it does
requireIdentifiedCaller	true refuses opaque callers, so everything is metered per person. Leave it off on a router serving other people’s agents
upstreams[].match	the route name — a glob you choose, like *-ant-aws or glm5br*
upstreams[].shape	the API the caller speaks: anthropic, openai, res
upstreams[].translate	rewrite to another provider’s dialect, e.g. bedrock
upstreams[].url	the provider endpoint
upstreams[].auth	bearer, none
upstreams[].secret	the key. Literal, or ${ENV_VAR} read at startup

This file holds provider keys in clear. Restrict its permissions, keep it out of version control, and out of backups that travel.

Sealed stores — CLI only

Encrypted under the owning component’s key. No editor will help.

file	holds	changed with
policy.csv	who may reach this agent, and what it may reach	hexaeight-activate add-policy, or the agent’s --add-rule
vouch.he	who may act on behalf of whom	the agent’s vouch allow
engines.he	sealed engine entries: model, router, mission, wrapper	hexaeight-activate engine --add
router-policy.he	the router’s rules	the router’s --init-policy

Read them back: hexaeight-activate list-policy for the agent, and for the router, its startup output or --init-policy, which prints the current rules before asking anything.

Environment

variable	what it does
HEIA_DIR	an agent’s own store. A caller and the door it calls must not share one
HEIA_POLICY_MODE	enforce (the default) or audit
LLM_ROUTER_CONFIG	point the router at an upstreams.yaml elsewhere

The identity itself comes from env-file, which is read from the current directory — which is why every command is run from its component’s own folder.

Where things are written

my-agent/
  hexaeight-agent.json     you edit this
  env-file  hexaeight.mac  the identity — never copy, hardlink
  policy.csv vouch.he      sealed
  engines.he               sealed
  agent.log                what it did

my-router/
  upstreams.yaml           you edit this — upstreams AND settings
  env-file  hexaeight.mac  hardlinked from the agent, or its own
  router-policy.he         sealed
  router.log               what it did