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	who may sign in to the workspace: one address, or *@yourcompany.com for anyone at that domain. Without it, no rule applies at all
license.type	personal or business. Sets the defaults below, and is written by the setup
sessionIdleMinutes	idle sign-out: 1 to 1440 minutes, or 0 for off. Default 15 on a business licence, 480 on a personal one. See Admin settings
privacyNotice	true or false: the privacy notice on the terms screen, and consent withdrawal. Default on for a business licence, off for a personal one
audit	false turns the audit trail off. On by default
register	publish this agent to the registry so others can find it by name
external.retentionDays	how long sessions held for outside callers are kept before the agent removes them. 1 to 365, default 365. Workspace conversations are not affected; nothing expires them
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
external.opaqueCallers	true: the model router is not told who outside callers are, and records their calls against this agent. Off by default. See Use someone else’s router
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 and --remove-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
audit-sink.he	where the audit trail is sent	the agent’s audit-sink set, off
oauth-link.he	the link to your company’s OAuth app	the agent’s oauth-link set
fleet.he	Machines: addresses and how to sign in to them	Machines in the workspace
secrets.he	API keys the agent’s work may use	Keys in the workspace
acceptance.he	each person’s acceptance of the terms, and withdrawals	the workspace’s terms screen
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. The agent opens every one of them before it starts; see Encrypted stores.

Environment

variable	what it does
HEIA_DIR	an agent’s own store. A caller and the door it calls must not share one
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

~/heia-agent/
  hexaeight-agent.json     you edit this
  privacy-notice.txt       optional: your own privacy notice
  env-file  hexaeight.mac  the licence: hard links, never copies
  policy.csv  *.he         sealed stores, and their last-good copies
  audit/                   the audit trail
  startup-check.json       what the last start checked
  agent.log                what it did, when no service manager runs it

~/heia-router/
  upstreams.yaml           you edit this: upstreams AND settings
  env-file  hexaeight.mac  hard links to the same licence
  router-policy.he         sealed
  audit/                   the router's audit trail
  usage.jsonl              one line per model call
  router.log               what it did, when no service manager runs it

With a service manager, read the logs with heia logs agent and heia logs router.