```
The secret is typed at a prompt that does not show it. The client is tried before the route is saved,
and a call refused with 401 is retried once with a fresh token. For an API that takes a key in a header
instead, `--secret-header` asks for the header's value the same way.
## Your API learns who asked
When another agent's request reaches your API through your agent, the call carries headers that say who
asked: `X-HexaEight-Caller` (the agent that asked), `X-HexaEight-Caller-ClientId` (its OAuth client,
when it is linked), `X-HexaEight-Forwarded-By` (an agent that passed the request on) and
`X-HexaEight-Request-Id`, which ties the call to the same request in every agent's audit trail.
These headers come only from your agent: any `X-HexaEight-*` header that arrives from outside is removed
first.
==============================================================================
SECTION: Security and compliance
==============================================================================
------------------------------------------------------------------------------
PAGE: Compliance
URL: /docs/concepts/compliance/
ABOUT: What the architecture provides toward GDPR, HIPAA, DPDPA and the EU AI Act — what it does not provide, and what remains yours.
------------------------------------------------------------------------------
:::note[What this page is, and is not]
This maps **architectural properties** to specific regulatory obligations. It is not legal advice, and
no certification is claimed. Compliance is a property of a *deployment*, not of software — nothing
here makes an operator compliant on its own.
The limitations section is not an appendix. Read it.
:::
## Start here — what you actually have to do
**If you are a developer: mostly nothing.** The properties below are how the system behaves by
default. You do not switch on encryption or the audit trail, and there is no compliance mode to
enable.
What you *do* control is four choices, each of which changes your obligations:
| Choice | Effect |
|---|---|
| **Where you run the agent** | It runs on your infrastructure, so that is where personal data sits. This is your residency answer. |
| **Which model the router points at** | Point it at an on-box model and **no personal data reaches a third party** — the sub-processor question disappears. Point it at a hosted provider and that provider becomes a sub-processor you must disclose. |
| **Who may reach it** | The installer writes a starting policy that admits you, the owner, and refuses everything else. Each further [policy rule](/docs/operate/policy/) admits a person or an agent by name. An agent with no rules at all enforces nothing, so never run one without them. |
| **How long data is kept** | The agent deletes nothing on its own: conversations, memories and the audit trail stay until you remove them. The one exception is sessions held for outside callers, which are kept for 365 days by default (`external.retentionDays`, 1 to 365). Deciding how long to keep the rest, and deleting it, is yours. |
And three things remain yours no matter what:
- **Conversations and work files on disk.** Settings, policy, sessions, approvals and consent records
are sealed. Conversations, memories and work folders are ordinary files on the agent's machine, so
protect that disk; an encrypted disk covers them. If you bring your own engine, whatever it writes
is yours too.
- **Your own application's logs.**
- **The host the agent runs on.** These guarantees assume it is intact.
## What you can show an auditor
- **The [audit trail](/docs/operate/audit/).** A sealed, chained record of sign-ins, turns, approvals,
commands, agent-to-agent calls and changes to settings, without the content of any message. You can
export it, verify it and send it to your SIEM.
- **The [compliance report](/docs/operate/compliance-reports/).** The controls in force, read from what
the running agent recorded, checked line by line against SOC 2, HIPAA, the EU AI Act and India's DPDP
Act.
- **The [access review](/docs/operate/compliance-reports/#the-access-review).** Who may sign in, every
policy rule, every signed-in session, every standing approval.
- **Consent records.** Each person's acceptance of the workspace terms, with the exact words and their
hash, and any withdrawal.
- **The [admin settings](/docs/operate/admin-settings/).** Idle sign-out, the privacy notice and the AI
notice, which you can lock against change.
**If you are filling in a security questionnaire or DPIA**, the sections below are written to be
cited: each row names the specific obligation it speaks to. Read *What this does NOT do* before you
answer anything — several questions are best answered by the limitations rather than the properties.
## What it looks like
Real screens and real output. Private values are blurred, not removed.
Consent. Each person accepts the terms before using the workspace. The acceptance is kept, sealed, with the exact words and their hash.
The AI notice. Under every message box, people are told they are working with an AI system.
Every step shown. The Advanced view lists each step the agent took and the sources it used.
Nothing runs unasked. A drafted job does nothing until a person presses Start.
Secrets stay sealed. An API key is sent encrypted and never shown again.
The record. One conversation in the audit trail: who, when, which engine and model, and the question and the reply only as hashes.
The report. The compliance report checks the controls in force against each framework, line by line.
---
## The shift this makes
Most privacy regulation asks you to promise things and keep records showing you tried. Several of
those promises become **properties you can demonstrate mechanically** — the difference between *"our
policy says staff don't read customer messages"* and *"the software cannot read them."*
Two properties carry most of the weight.
### Breach safe harbour
Anything that carries messages between two agents, whether a tunnel, a gateway or the network,
holds only ciphertext it cannot decrypt. Under **GDPR Art. 34(3)(a)**, notification to data
subjects is not required where measures such as encryption render the data unintelligible to
unauthorised persons. **HIPAA** works the same way: PHI secured to NIST standards is not *unsecured*
PHI, so its exposure is not a reportable breach.
This is the single largest practical benefit, and it applies to the party most likely to be breached
— the one in the middle.
### Consent as an artifact, not a log row
Approval is a cryptographic operation only the user can perform. **GDPR Art. 7(1)** requires the
controller to be able to *demonstrate* consent; **DPDPA §6(1)** requires clear affirmative action.
A checkbox produces a database row that anyone with database access could have written. This produces
an artifact that only the data subject could have produced.
---
## GDPR
| Obligation | What the architecture provides |
|---|---|
| **Art. 25** — protection by design *and by default* | The sealed path is the only path. No setting lets anything between two agents read their messages. |
| **Art. 5(1)(c)** — data minimisation | A mission searches only the memories it lists. A memory served by another agent answers questions without its documents leaving that agent. The audit trail keeps a hash of each message, never its content. |
| **Art. 4(5), 32(1)(a)** — pseudonymisation | An engine receives a hash of the identity, never the address. It can distinguish, meter and tier customers without holding personal data. |
| **Art. 32(1)(a)** — encryption | End to end between identities. At rest, settings, policy, sessions, approvals, consent records and the audit trail are sealed. Conversations and memories are ordinary files, so encrypt the disk they sit on. |
| **Art. 7(1)** — demonstrable consent | See above. Each person's acceptance of the workspace terms is also kept, sealed, with the exact words and their hash. |
| **Art. 7(3)** — withdrawal of consent | **Privacy**, at the bottom of the workspace, as easy as accepting. Recorded in the audit trail. Offered by default on a business licence; see [Admin settings](/docs/operate/admin-settings/). |
| **Art. 22** — solely automated decisions | Where approval is required, a decision is **not** based solely on automated processing. The agent enforces it rather than leaving it to procedure: a command that is not already allowed waits for a person. |
| **Art. 34(3)(a)** — breach notification | See above. |
| **Chapter V** — international transfers | EDPB Recommendations 01/2020 name encryption with keys held solely by the exporter or data subject as an effective supplementary measure. Data crossing a border is sealed, with no key at the transit party. |
| **Art. 30, 35** — records and DPIAs | Remain yours, but the audit trail and the [compliance reports](/docs/operate/compliance-reports/) give you the raw material, and the properties above are what a DPIA can rely on. |
---
## HIPAA
| | |
|---|---|
| **§164.312(a)(2)(iv), (e)(2)(ii)** — encryption at rest and in transit | In transit: end to end. At rest: the agent's stores and the audit trail are sealed; conversations and memories need an encrypted disk. |
| **§164.312(a)(2)(iii)** — automatic logoff | The workspace signs people out when idle: after 15 minutes by default on a business licence. |
| **Breach Safe Harbor** (45 CFR §164.402 and HHS guidance) | Secured PHI is not unsecured PHI. A breach of ciphertext held without keys is not reportable. |
| **§164.502(b)** — minimum necessary | A mission searches only the memories it lists. |
| **§164.312(b)** — audit controls | A sealed, chained [audit trail](/docs/operate/audit/) of sign-ins, turns, approvals, commands and agent-to-agent calls, which you can export, verify and send to your SIEM. |
| **§164.308(a)(4)** — access management | Per-identity policy. The starting policy admits only the owner; everyone else needs a rule. The [access review](/docs/operate/compliance-reports/#the-access-review) lists who has access. |
:::caution[Business Associate status]
HHS guidance is explicit that a provider storing encrypted PHI **without the key is still a Business
Associate**. The "conduit" exception is narrow and does not apply here.
What this architecture does is **narrow what a Business Associate can access** and simplify the
associated risk analysis. It does not remove BA status, and you should not represent that it does.
:::
---
## India DPDPA 2023
| Section | Fit |
|---|---|
| **§5** — notice | The terms screen shows a privacy notice before anyone accepts: the standard one, or your organisation's own. |
| **§6(1)** — free, specific, informed, unambiguous, by clear affirmative action | Approval is an affirmative cryptographic act. Each acceptance of the terms is kept with the exact words and their hash. |
| **§6(4)** — withdrawal as easy as giving | A person withdraws in the workspace (**Privacy**) as easily as they accepted. The workspace then shows only the terms until they accept again, and the withdrawal is recorded in the audit trail. |
| **§8(5)** — reasonable security safeguards | Encryption end to end; the agent's stores and the audit trail sealed at rest. |
| **§8(2)** — responsibility for processors | A processor that cannot read content is a smaller surface to stand behind. |
| **§2(g), §6(9)** — Consent Manager | The user-side consent model maps closely to this role. India is the only major regime that names it explicitly. |
---
## EU AI Act
Relevant because engines are models.
- **Art. 14 — human oversight.** Where approval is required, an agent cannot act without the person.
Oversight is enforced, not documented.
- **Art. 10 — data governance.** A mission's memories bound what it can draw into a model's context.
- **Art. 12 — record-keeping.** The [audit trail](/docs/operate/audit/) records each turn, approval and
command automatically.
- **Art. 50 — transparency.** The workspace tells people they are working with an AI system and labels
exported conversations as AI-generated.
- **Practical effect on prompt injection:** a compromised model can *ask* for anything, but it reaches
only what policy allows, and a command that is not already allowed waits for a person.
---
## Deployment choices that change the analysis
**Run a local model and no personal data reaches a third party.** Model choice lives in the router,
per engine. Point it at an on-box model and the sub-processor question disappears entirely — the
strongest available answer for health data and Art. 9 special categories.
**Sub-processor disclosure becomes a config file.** Because model routing is explicit and per-engine,
you can enumerate exactly which providers see what, rather than investigating it.
**Data stays where you put it.** The agent runs on your infrastructure. Personal data does not leave
your control by default, which answers residency and sovereignty questions without a contractual
clause.
---
## What this does NOT do
Three different kinds of limitation. Only the third is future work.
### Inherent — permanent trade-offs, disclosed
**Metadata is not hidden.** Who contacted whom, when, and how often is visible to the agents
involved. Content is sealed; the communication graph is not. Under GDPR, that metadata is still
personal data.
**Your own agent reads your own session.** Sealing applies to content arriving from other parties.
Your agent processes your own conversation in the clear, because it must.
**The engine reads session content in plaintext — it must, to be useful.** You cannot reason over
data without seeing it; homomorphic encryption and trusted enclaves are not practical answers here,
and enclaves relocate trust rather than removing it.
What the architecture does instead is **assume the engine may be hostile and bound what it can do**.
The identity files are hidden from it and it runs in a sandbox. A command that is not already
allowed waits for a person's approval, and every call it makes to another agent must pass both
agents' policy rules.
The residual risk is that a hostile engine can *influence what a person approves*. Showing the exact
command in each approval reduces this, but does not eliminate it.
**Access and portability get harder, not easier.** Where only the user can decrypt, a controller may
be **unable** to produce data in response to an Art. 15 or Art. 20 request. Encryption you do not
hold keys to cuts both ways.
**Key loss is data loss.** There is no recovery path. That is a design decision with a compliance
consequence.
**Rotation is the agent's choice, not forced.** Key material is derived per generation window, so keys
obtained at different times differ. Keys already held can be reused — including straight through a
platform outage — and nothing evicts a key a session is already using.
This is a current limitation rather than a design position: periodic re-keying during a live session
is anticipated, but it is not implemented and its operational effects are not yet established. If
your control framework requires enforced rotation of keys in active use, treat this as not available
today.
### Bounded — true, and the scope is the answer
**A local session is as trusted as the machine it runs on.** An agent on a compromised host offers
nothing. The isolation properties assume the host is intact.
**Policy is only as good as its rules.** An agent with no rules at all enforces nothing; the
installer's starting policy admits only the owner. Every rule you add admits someone, so review them;
the [access review](/docs/operate/compliance-reports/#the-access-review) lists them all.
### Open — being worked on
**Terminating a session at another party.** A user should be able to end a conversation they started
at a remote agent, and receive acknowledgement. The proof mechanism for this exists and is used
elsewhere in the system; extending it to cross-agent sessions is in progress. Until it ships, treat
Art. 17 erasure across agents as an operator process rather than an automated one.
**Identifiers in operational logs.** Most log output truncates identities. A small number of paths
still emit full addresses to stdout, which is personal data with no stated retention (Art. 5(1)(e)).
Being addressed.
---
## What remains yours
No architecture discharges these:
- lawful basis, and records of processing (Art. 30)
- data protection impact assessments (Art. 35) — likely required for agentic processing
- processor agreements and BAAs
- breach detection and the 72-hour notification clock
- retention schedules, and honouring data subject requests
- securing the host the agent runs on
## On SOC 2 and ISO 27001
Those certify an **organisation operating a service**. Self-hosted software is not in scope for
either. Your own deployment may be certified, and these properties support that — but the software
itself is not, and no vendor can hand you one for something you run yourself.
The [compliance report](/docs/operate/compliance-reports/) checks the agent's controls against the
SOC 2 criteria, line by line, as evidence for your own audit.
---
*Mapped against GDPR (EU 2016/679), the HIPAA Security and Breach Notification Rules as amended,
India's DPDPA 2023, and the EU AI Act as adopted. Reviewed August 2026. Regulations change; verify
against current text.*
## Next
- [Audit trail](/docs/operate/audit/) — what is recorded, and how to export and verify it
- [Compliance reports](/docs/operate/compliance-reports/) — the controls in force, and who has access
- [Admin settings](/docs/operate/admin-settings/) — idle sign-out, privacy notice, consent
- [Dead Drop Encryption](/docs/concepts/dde/) — the key exchange underneath these properties
- [Policy and approved builds](/docs/operate/policy/) — access control in practice
- [HexaEight and OAuth](/docs/concepts/oauth/) — how the two work side by side
------------------------------------------------------------------------------
PAGE: Audit trail
URL: /docs/operate/audit/
ABOUT: A sealed, tamper-evident record of what your agent allowed, ran and refused, without the content of any message. Export it, verify it, and send it to your SIEM.
------------------------------------------------------------------------------
Every agent keeps an **audit trail**: a record of what it allowed, what it ran and what it refused. It is
on from the first start, and there is nothing to set up.
It records **who did what, and what was decided**. It never stores what anyone wrote: a message or a
reply goes into the trail only as its SHA-256 hash. Commands are the exception, because approving a
command is the thing being audited, so they are recorded in full.
## What is recorded
| | Entries |
|---|---|
| **Sign-in and access** | every refused sign-in and every refused operation. An allowed one is recorded once an hour for the same person and operation, because the check runs on every request. |
| **Conversations** | when each turn starts and ends, which engine answered, how long it took, and who the session belongs to. The message and the reply appear only as hashes. |
| **Commands** | in conversations and HexaPilot jobs: every approval or refusal a person gives, and every command the agent checked or ran. An approval and the command it allowed carry the same request id. |
| **Other agents** | calls in and out, who was admitted or refused, requests passed on, calls to an API behind the agent, and each OAuth check |
| **Consent and sign-out** | terms accepted or withdrawn, and idle sign-outs |
| **The agent itself** | at each start: its version, the SHA-256 of the running binary, a fingerprint of every settings and policy file, and the controls in force. While it runs, any change to one of those files is recorded with its old and new hash. |
| **Security events** | a key that failed the agent's check, a store that would not open or was restored, ten refusals for one caller within a minute, a public address that stopped reaching the agent and was replaced |
| **Heartbeat** | every five minutes, from each of the agent's processes |
## Why you can trust it
- **Sealed.** Each entry is encrypted (AES-256-GCM) with a key that only this agent's identity can
obtain. Only the owner, in the agent's folder, can read the trail.
- **Chained.** Each entry carries the hash of the one before it, and a sealed head file holds the
number and hash of the last entry. If a line is removed or edited, the chain breaks. If the end is
cut off, it no longer matches the head. A single changed byte stops the line from decrypting.
- **Never in the way.** Entries are written in the background, so recording never slows a turn down.
If the disk is full, entries wait and are written once there is room.
- **Never deleted.** The agent does not delete trail files. How long you keep them, or your SIEM's
copy, is your decision.
The trail lives in the agent's folder, in `audit/`, one file per day for each of the agent's
processes.
## Export and verify
From the agent's folder:
```bash
cd ~/heia-agent
./hexaeight-agent-linux-x64 audit-export > trail.jsonl
```
On macOS the binary is `hexaeight-agent-osx-arm64`. Run the export while the agent is running or
stopped, but not while it is starting.
The export decrypts every entry, checks every chain against its head, and writes one JSON line per
entry in time order. A person's address is added to every row of their session. The verdict is printed
separately:
```
OK 'main': 1234 entries, chain verified
RESULT every chain verified
```
A problem appears as a `BROKEN` line naming the file and line, and the command exits with status 2.
| Option | What it does |
|---|---|
| `--from 2026-10-01` · `--to 2026-10-31` | a date range |
| `--session ` | one work session (every entry of a session carries its id) |
| `--router-usage ~/heia-router/usage.jsonl` | adds the router's model calls for the same sessions: model, tokens and time |
### A real export
The question about annual leave from the [workspace tour](/docs/start/workspace/), exported with the
router's calls joined in. This is real output: the email addresses and one folder name are blurred,
nothing else is changed.
Read from the top, the first turn says:
| time (UTC) | entry | what it records |
|---|---|---|
| 13:58:33 | `session.user` | whose session this is |
| 13:58:33 | `turn.start` | a turn began on the `chat` engine. The question appears only as its SHA-256 hash |
| 13:58:40 | `turn.end` | the turn finished `ok` in 7.1 seconds. The reply appears only as its hash |
| 13:58:40 | `llm.call` | from the router: route `glm-ant-aws`, model `zai.glm-5`, 13,906 tokens in and 21 out, 3.2 seconds |
`seq` and `prev` are the chain: each entry carries its number and the hash of the entry before it.
## Send it to your SIEM
The agent can push the trail to your log pipeline as it is written, as one HTTPS POST of JSON entries
with one header of your choice. Any collector that accepts that will work, for example Splunk (the HEC
raw endpoint), Datadog, Sumo Logic, or the HTTP input of Logstash, Fluent Bit, Vector or Cribl.
From the agent's folder:
```bash
./hexaeight-agent-linux-x64 audit-sink set # asks for the URL and one header; the values are not shown
./hexaeight-agent-linux-x64 audit-sink test # sends one test event: OK, or FAILED with the HTTP status
./hexaeight-agent-linux-x64 audit-sink off # stops sending; the setting is kept, and set turns it on again
```
- **HTTPS only.** Plain HTTP is accepted only for a collector on the same machine.
- **Newline-delimited JSON** by default. `set --format json-array` sends a JSON array instead.
- **No restart.** The running agent picks up a change within a minute.
- **Nothing lost, nothing out of order.** The agent moves on only after your collector accepts a batch.
After an outage or a restart it resumes where it stopped. Each entry has an `id`, so your collector
can drop one that arrives twice.
- **The setting stays secret.** The URL, the header and its value are sealed in the agent's folder,
not in `hexaeight-agent.json`, and no command or log line ever shows them.
Your collector receives each entry as readable JSON, with the agent's name added. HTTPS protects the
entries on the way.
## The router keeps one too
The router records who each session is for, every model call (route, model, tokens and time taken)
and every refusal, using the same session id as the agent, so the two join up. It has the same
commands, run from the router's folder:
```bash
cd ~/heia-router
./hexaeight-router-linux-x64 audit-export > router-trail.jsonl
./hexaeight-router-linux-x64 audit-sink set
```
## Turning it off
`"audit": false` in `hexaeight-agent.json` turns the agent's trail off from the next start. The
[compliance reports](/docs/operate/compliance-reports/) then show it as a gap.
## Next
- [Compliance reports](/docs/operate/compliance-reports/): what is in force, read from this trail
- [Admin settings](/docs/operate/admin-settings/): who may sign in, idle sign-out, privacy notice
and consent
------------------------------------------------------------------------------
PAGE: Compliance reports
URL: /docs/operate/compliance-reports/
ABOUT: Two read-only reports for an auditor. One shows the controls in force, checked against SOC 2, HIPAA, the EU AI Act and India's DPDP Act. The other shows who has access.
------------------------------------------------------------------------------
Your agent can produce two reports for an auditor. Both are **read-only**: they change nothing, and
neither is a certification. They report the technical controls. The rest of a compliance programme
stays with your organisation, and the reports list it so the picture is complete.
Run both from the agent's folder. They open the agent's sealed records, so only the owner can run
them. On macOS the binary is `hexaeight-agent-osx-arm64`.
## The compliance report
```bash
cd ~/heia-agent
./hexaeight-agent-linux-x64 hexaeight-agent.json --compliance-info all
```
Instead of `all`, name one framework: `soc2`, `hipaa`, `eu-ai-act` or `dpdpa` (India's DPDP Act
2023). Add `--json` for a machine-readable copy.
Real output from a running agent. The host name and the email addresses are blurred; nothing else is
changed.
**It reports what is in force, not what a file says.** The figures come from the
[audit trail](/docs/operate/audit/), from what the running agent recorded about itself:
- **The running build**: its version and the SHA-256 of the binary, so you can match it to a
published release
- **Heartbeats**: when each of the agent's processes was last seen
- **Controls in force**: sign-in, policy, approved builds, engine isolation, the SIEM sink, the idle
sign-out, the privacy notice and more, as recorded at the agent's last start
- **Changes since then**: every settings or policy file that changed, with its old and new hash
- **The last 30 days**: turns, approvals, commands, refusals, consents and withdrawals, idle sign-outs
and security events
- **Consent records**: who accepted which terms and when, with a hash of the exact words
Then comes a checklist for each framework. Every line gives its evidence and one of these statuses:
| Status | Meaning |
|---|---|
| **In place** | the control is on, and the evidence shows it |
| **Partial** | part of it is covered; the evidence says which part is not |
| **Gap** | this agent does not cover it today |
| **Organisation** | your own obligation, such as a risk analysis, training, a contract or a procedure |
| **N/A** | it does not arise for this agent, for example consent withdrawal on a personal licence that only its owner uses |
Two of the checklists from the same report:
Start the agent at least once with the current release before running the report. Until then, the
report says there is no record of controls yet.
## The access review
```bash
./hexaeight-agent-linux-x64 hexaeight-agent.json --access-review
```
It lists who and what can reach this agent:
- who may sign in to the workspace
- every policy rule
- the approved builds, and whether only those may connect
- every signed-in session, newest activity first, and how many distinct people they belong to. Each
session is shown by a short hash: never a code, a login token or a key.
- consent records, including withdrawals
- command approvals, and every standing ("always") approval
- the machines this agent can reach
- whether other software can call it, and which agents may reach it or be called by it
Add `--json` for a machine-readable copy.
From a running agent, with email addresses, other agents' names, machines and their addresses blurred:
To remove someone's access, remove each of their policy rules with `--remove-rule`, written exactly as
it was added, and run the review again to confirm:
```bash
./hexaeight-agent-linux-x64 hexaeight-agent.json --remove-rule 'person@example.com,*,inbound,allow'
```
See [Policy](/docs/operate/policy/).
## The router's report
The router has its own report, run from the router's folder:
```bash
cd ~/heia-router
./hexaeight-router-linux-x64 --compliance-info all
```
It shows the same kind of record for the router: its build, heartbeat, controls, changes, model calls
and tokens over the last 30 days. It also lists **every model provider in its configuration** with the
provider and region inferred from the address, so you can answer where data is sent. Confirm each one
against the provider's terms. The report shows how each provider is reached, never its key.
From a running router, with the host name and private provider resource names blurred:
## Next
- [Audit trail](/docs/operate/audit/): export it, verify it, and send it to your SIEM
- [Admin settings](/docs/operate/admin-settings/): the controls an admin sets
- [Compliance](/docs/concepts/compliance/): what the design provides, and what remains yours
------------------------------------------------------------------------------
PAGE: Admin settings
URL: /docs/operate/admin-settings/
ABOUT: The controls an administrator sets for the people who use a workspace (who may sign in, idle sign-out, the privacy notice and consent, the AI notice) and how to lock them.
------------------------------------------------------------------------------
When people other than the agent's owner use its workspace, for example the staff of an organisation,
a few settings matter. They all live in `hexaeight-agent.json` in the agent's folder, which only
whoever runs the machine can change. Every change to that file is recorded in the
[audit trail](/docs/operate/audit/) with its old and new hash.
The defaults follow the licence. A **business** licence assumes many people on shared machines. A
**personal** licence assumes one person, the owner, on their own machine.
| | Business licence | Personal licence |
|---|---|---|
| **Idle sign-out** | after 15 minutes | after 8 hours |
| **Privacy notice and consent withdrawal** | offered | not offered |
An agent that has not been told its licence type gets the business defaults.
## Who may sign in
`owner` decides who may sign in to the workspace: one address, or `*@yourcompany.com` for anyone at
your domain. What each person may do once signed in is decided by the
[policy rules](/docs/operate/policy/). Without `owner`, the sign-in check lets anyone in. That is meant
only for development, and the [compliance report](/docs/operate/compliance-reports/) shows it as a gap.
## Idle sign-out
```json
"sessionIdleMinutes": 30
```
Set it to between 1 and 1440 minutes, or to 0 to turn the sign-out off. The new value applies from the
agent's next start. A value outside that range is ignored and the licence default applies. The
compliance report names the value it ignored.
After that much time without activity, the workspace signs the person out. The session key in the
browser is dropped, so coming back takes this device and the phone. A turn that is already running
finishes first. Each idle sign-out is recorded in the audit trail.
## Terms, privacy notice and consent
Everyone who signs in to the workspace accepts its terms before they begin. Each acceptance is kept,
sealed: who accepted, which version, when, and the exact words with their hash.
**The privacy notice** appears on the terms screen, before anyone accepts. The standard notice says
what is collected, why, where it goes, how to withdraw consent, and what other rights people have. It
names no contact person, so an organisation should use its own:
- Put your text in `privacy-notice.txt`, next to `hexaeight-agent.json`. It replaces the standard notice
completely, up to 50,000 characters.
- It is read on every request, so no restart is needed.
- The notice is part of what people accept. Change it, and everyone is asked to accept again.
- If the file is empty, too long or unreadable, the standard notice is shown instead, and the
compliance report names the problem.
**Withdrawing consent.** Anyone can withdraw consent at any time by choosing **Privacy** at the bottom
of the workspace. After that, the workspace shows only the terms until they accept again. Withdrawing
does not undo what was done before. HexaPilot jobs they already started keep running, so pause those in
HexaPilot. Each withdrawal is recorded in the audit trail and kept beside the acceptance.
**On or off.** The notice and withdrawal always come together. A personal licence leaves them off,
because usually the only person who signs in is the owner. If your organisation gives personal
licences to its staff, turn them on:
```json
"privacyNotice": true
```
`false` turns both off. The setting applies from the agent's next start.
## The AI notice
The workspace tells people they are working with an AI system, both in the terms they accept and under
every message box. It also labels exported conversations as AI-generated, on the page and in the file's
metadata.
Answers that your own applications receive through the agent's API are not labelled. Label them where
you show them.
## Lock the settings
The running agent only reads `hexaeight-agent.json`. The installer and the setup commands are what
write it. Once setup is done, an administrator can lock the file. After that, nothing running as the
agent's user can change or replace it: not the agent, not its engines, and not a command someone
approves in the workspace.
On Linux:
```bash
sudo chattr +i hexaeight-agent.json
```
On macOS:
```bash
sudo chown root hexaeight-agent.json && sudo chflags uchg hexaeight-agent.json
```
Lock `privacy-notice.txt` the same way if you use one. Unlock the file before you change a setting or
run the installer again:
- **Linux:** `sudo chattr -i hexaeight-agent.json`
- **macOS:** `sudo chflags nouchg hexaeight-agent.json && sudo chown $USER hexaeight-agent.json`
**On Windows, in WSL**, the lock works the same way inside WSL's own filesystem. However, the Windows
account that owns WSL can always become root inside it. The lock stops everything that runs as the
agent's user, but not that Windows account.
Every change to the file shows up in the audit trail. While the agent runs, a change is recorded with
the old and new hash. If someone changes the file while the agent is stopped, the fingerprint taken at
the next start is different. With the [SIEM sink](/docs/operate/audit/#send-it-to-your-siem) on, that
record also leaves the machine.
## Next
- [Compliance reports](/docs/operate/compliance-reports/): check that these settings are in force
- [Audit trail](/docs/operate/audit/): where every change and sign-out is recorded
==============================================================================
SECTION: Running it
==============================================================================
------------------------------------------------------------------------------
PAGE: Lifecycle
URL: /docs/operate/lifecycle/
ABOUT: Start, stop, update, roll back and renew the licence, and where the records of what happened are kept.
------------------------------------------------------------------------------
## Start, stop, status
After the [installer](/docs/start/what-gets-installed/), the system's service manager runs the router,
the agent and the workspace. That is systemd on Linux and launchd on macOS. It starts them at login and
brings them back if they stop. Manage them with `heia`, from any folder:
```bash
heia status # what is running, and its addresses
heia restart [agent|router|workspace|all] # agent by default; restarting the router restarts the agent too
heia start [agent|router|workspace|all]
heia stop [agent|router|workspace|all]
heia logs [agent|router|workspace] # follow a log; Ctrl-C to leave
```
`heia` keeps the order that works: router, then agent, then workspace.
- **Use `heia`, not a second copy.** A binary started by hand beside the service manager fights it for
its port. Never stop a component with a pattern match on its process name either, because that can
catch other agents.
- **On Windows, in WSL**, if WSL is not set up to run services, nothing starts by itself after Windows
restarts. Open Ubuntu and run `heia start all`.
- **Agent and router commands act on the folder they run in.** Run `./hexaeight-agent-…` from the
agent's folder (`~/heia-agent`) and `./hexaeight-router-…` from the router's (`~/heia-router`).
## Update
Run the installer again:
```bash
curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash
```
It compares what is installed with the latest releases and downloads only what has a newer one. Each
download is checked against its published hash, and the previous binary is kept beside the new one.
The agent records its version and the SHA-256 of its binary each time it starts. The
[compliance report](/docs/operate/compliance-reports/) shows them, so you can confirm that the build
running is the one published.
## Roll back
The previous binary stays in the same folder. Its name ends with the release it was and the time it
was replaced, for example `hexaeight-agent-linux-x64.agent-r36-linux-x64.20261012_101500`. To go
back, put it back under its original name while the component is stopped:
```bash
heia stop agent
cd ~/heia-agent
mv hexaeight-agent-linux-x64 hexaeight-agent-linux-x64.set-aside
mv hexaeight-agent-linux-x64.agent-r36-linux-x64.20261012_101500 hexaeight-agent-linux-x64
heia start agent
```
## Renew the licence
**When it ends.** The agent says when the licence probably ends, at every start and once a day, in its
log. In the last 7 days of a monthly licence, or the last 15 days of a yearly one, it also records a
warning in the [audit trail](/docs/operate/audit/). You can ask at any time:
```bash
cd ~/hbia-agent
hexaeight-activate verify-license
```
This prints whether the licence works and its probable end date. The date is an estimate, because the
platform does not report it. It is worked out from when the licence was installed on this machine:
30 days later for a monthly licence, or 365 days for a yearly one. A renewal before the end adds a
period to that end. A renewal after the end starts a new period from the day of the renewal.
`newtoken` and `renewtoken` ask whether the licence is yearly and remember the answer. If the answer
was never recorded, both possible dates are shown.
**Renew it** in the licence folder:
```bash
cd ~/hbia-agent
hexaeight-activate renewtoken
```
Once the renewed licence verifies, `renewtoken` finds the other folders that hold this licence as a
hard link, which are the router's and the agent's, and links them to the renewed file. It never copies
the file. It lists the folders it updated. Restart what runs there so it uses the new licence:
```bash
heia restart router # the router, then the agent
```
If the licence has already ended, the agent cannot fetch its keys and does not start. Its log names
the licence as the likely cause. Renew, then start it again.
## Remove someone's access
Remove their policy rules, written exactly as they were added, then confirm:
```bash
cd ~/heia-agent
./hexaeight-agent-linux-x64 hexaeight-agent.json --remove-rule 'person@example.com,*,inbound,allow'
./hexaeight-agent-linux-x64 hexaeight-agent.json --access-review
```
See [Policy](/docs/operate/policy/) and [Compliance reports](/docs/operate/compliance-reports/).
## Where the records are
| | |
|---|---|
| **What was allowed, run and refused** | the [audit trail](/docs/operate/audit/), in `audit/` in the agent's folder and the router's: sealed, chained, never the content of a message |
| **Conversations** | `~/.hexaeight-harness`, one file per conversation, as plain JSON lines |
| **Model calls** | `usage.jsonl` in the router's folder: one line per call, with the model, the tokens and the time it took |
| **What a component is doing** | `heia logs agent`, `heia logs router` |
## Checks worth scheduling
| Command | Cost |
|---|---|
| `hexaeight-activate verify-license` | one round trip. It also prints the licence's probable end. |
| `hexaeight-activate verify-libs` | no licence call, so it is cheap enough to run on a timer |
| `heia status` | a look at the ports, and a check that the public addresses answer |
## Next
- [Encrypted stores](/docs/operate/stores/): when the agent will not start
- [Troubleshooting](/docs/operate/troubleshooting/)
------------------------------------------------------------------------------
PAGE: Encrypted stores
URL: /docs/operate/stores/
ABOUT: The agent opens every encrypted store before it starts. What happens when one will not open, and how to put a last-good copy back.
------------------------------------------------------------------------------
The agent keeps its access rules, engines, sessions, approvals, consent records and other settings in
**encrypted stores**: the `.he` files in its folder. Each one opens only with this agent's identity.
## The check at every start
Before the agent opens its port, it opens every store, one at a time. **If one does not open, the
agent does not start**, and it says which store and what to do. Starting without it would leave the
agent broken in a way nobody notices: a policy that cannot be read looks like no rules, and a terms
store looks like nobody ever accepted.
- **The key is tried first.** A store that does not open gets freshly fetched keys, three tries 20
seconds apart, before anything is decided about the file.
- **Every store is checked**, even after one fails, so one message lists everything to fix.
- **Last-good copies.** After every start that passes, the agent keeps two copies of each store that
opened: `.lastgood` and `.lastgood.2`.
- **Nothing is repaired without you.** Putting a copy back is a person's decision, made with
`restore-store` (below). The one exception is the signed-in sessions file (`sessions.he`): if it
does not open but its last-good copy does, the agent puts the copy back itself.
The reason for a stop is in the agent's log and in `startup-check.json` in the agent's folder.
## When the agent does not start
| What the check finds | What to do |
|---|---|
| A store's key cannot be fetched | Start the agent again in a few minutes. The keys that worked are kept, so only the missing one is fetched. If it keeps failing, check the licence: `hexaeight-activate verify-license`. |
| A store does not open, but one of its last-good copies does | The key is fine and the latest file is not. Start the agent again to retry. If it still stops, put the copy back with `restore-store`. |
| A store does not open, and neither do its last-good copies | Those copies opened before, so the key is the problem, not the files. Start the agent again. |
| The folder's stores belong to a different identity from the one in `env-file` | Another identity's keys cannot open them. Put back the `env-file` of the identity the stores belong to, or start the new identity from a folder of its own. |
| The licence has expired | Renew it with `hexaeight-activate`, then start the agent again. |
The exit status tells a script or service manager which case it is: **75** means a key could not be
fetched (try again later), **65** means a store did not open while its copy did, and **78** means the
folder belongs to another identity.
**What does not stop a start:**
- **A store with no last-good copy to compare with**, for example a file from an older version. The
agent starts without what that store holds, as older versions did. The file is not touched, and it
is named in the log and in the [audit trail](/docs/operate/audit/).
- **Preferences** (`prefs.he`). If they do not open, the file is renamed aside, never deleted, and a
new one is written. This happens only on a start where every other store opened.
- **A store that does not exist yet.**
## Check the stores yourself
```bash
cd ~/heia-agent
./hexaeight-agent-linux-x64 hexaeight-agent.json check-stores
```
It runs the same check and reports the result. It changes nothing, so it is safe while the agent runs.
On macOS the binary is `hexaeight-agent-osx-arm64`.
## Put a last-good copy back
Stop the agent first, then run this in a terminal:
```bash
./hexaeight-agent-linux-x64 hexaeight-agent.json restore-store policy.csv
```
Name the store the message named. Before changing anything, `restore-store`:
- tries fresh keys on the current file, and does nothing if it opens
- shows the copy it would use and when it was taken. Anything written after that time is not in the
copy.
- waits until you type `restore`
The file that did not open is kept beside it, renamed, never deleted. The restore is recorded in the
audit trail. Then start the agent.
## Next
- [Lifecycle](/docs/operate/lifecycle/): start, stop, update
- [Troubleshooting](/docs/operate/troubleshooting/)
------------------------------------------------------------------------------
PAGE: Capacity
URL: /docs/operate/capacity/
ABOUT: What one machine actually serves, measured rather than estimated.
------------------------------------------------------------------------------
Sizing questions usually arrive as "how many users per machine". The honest answer depends on one
number you control and one you do not.
## What a turn costs
A turn is a question and everything the agent does to answer it — searches, document reads, model
calls. Measured on a mid-size agent with memory search enabled:
| | |
|---|---|
| wall time | ~75–150 s for a typical question |
| memory | ~450 MB resident per concurrent turn |
| tokens | 100 K–200 K input for a well-scoped mission |
The spread matters more than the average. A well-scoped mission over a curated corpus answered in
**11 turns and 118 K tokens**. The same engine against a 512 K-document corpus, on a question whose
vocabulary did not match the documents, took **39 turns and 1.8 M tokens** — fifteen times the cost
for a worse answer.
**Scope is the lever.** A fence that narrows what a mission may search does more for capacity than
a bigger machine.
## Concurrency
Little's Law: `concurrent turns = arrival rate × turn duration`. Eight users asking one question a
minute each, at 120 s a turn, is **16 concurrent turns** — not 8.
At ~450 MB per concurrent turn that is ~7 GB of turn memory, before the agent, the router, and the
operating system.
## What the model does not grow with
Two things that are commonly assumed and are not true:
- **Memory does not grow with conversation length.** Measured across a 30-turn session: flat.
- **Tokens do not grow unboundedly** on a session with memory enabled — a measured 30-turn run
*fell* to 0.55× the opening turn as summarisation engaged.
The cost driver is the *shape of the work*, not the length of the conversation.
## The embedding model is shared
One ONNX model is loaded per process however many memories it opens — about **180 kB private** per
additional engine. Do not budget a copy per agent.
## Sizing a machine
Start from concurrent turns, not users:
```
RAM ≈ (concurrent turns × 0.45 GB) + 2 GB agent/router + OS
```
RAM is the binding constraint, not CPU — a turn spends most of its life waiting on a model call, so
vCPU rarely decides the ceiling. As a rough floor, allow **1 vCPU per 2 concurrent turns**.
On a 16 vCPU / 32 GB machine, RAM allows roughly `(32 - 2 - 4) / 0.45` ≈ **57 turns** in theory;
in practice budget **20–25**, because turn memory spikes during document reads and you do not want
to be near the limit when it does. At 120 s a turn that is
roughly **600 questions an hour**, which serves several hundred people asking a handful of
questions a day.
> Model throughput is usually the real ceiling. Rate limits and per-model concurrency at the router
> bite long before RAM does.
## Ingest is a different workload
Building a corpus is not serving one, and sizing for the first does not size the second.
A **merge** of 8 shards and 24 M chunks needed more than **58 GB** and was killed by the kernel
twice on a 61 GB machine — after concatenation had already succeeded. A **group** over the same
shards took **5 MB and about ten minutes**.
Prefer the group unless you can prove you need a merge.
------------------------------------------------------------------------------
PAGE: Troubleshooting
URL: /docs/operate/troubleshooting/
ABOUT: The real messages, what each one actually means, and the fix. Most of these name something other than the cause.
------------------------------------------------------------------------------
Grouped by what you see. Several of these name something unrelated to the real problem, which is
why they are written down.
## Nothing answers after a restart
`heia status` shows what is up. On Windows, if WSL is not set up to run services, nothing starts by
itself after Windows restarts. Open Ubuntu and run `heia start all`.
## The agent does not start: "NOT STARTED"
```
[startup-check] NOT STARTED — …
```
One of the agent's encrypted stores did not open. The message names the store and what to do, and
`startup-check.json` in the agent's folder holds the same. Usually the fix is to start the agent again.
See [Encrypted stores](/docs/operate/stores/).
## The licence is about to end, or has ended
The agent's log carries a `[licence]` line at every start and once a day. Renew in the licence
folder with `hexaeight-activate renewtoken`, then `heia restart router`. See
[Renew the licence](/docs/operate/lifecycle/#renew-the-licence).
## The workspace signed me out
That is the idle sign-out. By default it happens after 15 minutes without activity on a business
licence, and after 8 hours on a personal one. Sign in again with your phone. An administrator can change the time
with `sessionIdleMinutes`; see [Admin settings](/docs/operate/admin-settings/).
## The workspace shows only the terms
Either you withdrew your consent, or the terms or the privacy notice changed. Accept the terms again
to continue.
## The agent is up but nobody can reach it
```
[reach] cloudflared could not start (… No such file or directory)
[register] SKIPPED - nothing to publish (reach mode 'cloudflared(failed)', no 'myUrl')
```
The binary named in `reach.bin` is missing. No tunnel means no public URL, so registration is
skipped — the agent is healthy and simply not listed. Put the binary where `reach.bin` points.
A quick tunnel's hostname **changes on every restart**; the registry is updated each time, but
anything holding the old URL needs the new one.
## "Licence is not currently valid" and the licence is fine
Almost always the **wrong working directory**. The identity comes from `env-file`, which is read
from the current folder. Start a component from its own licensed folder.
Same cause: an agent started **before its router**. Order is router, then agent, then workspace.
## A turn returns instantly and does nothing
A couple of seconds, a small response, nothing in the wrapper's log. The mission never ran. In
order of likelihood:
1. The engine was re-sealed **without `--file`**, unbinding the wrapper
2. The wrapper's `harness-root` is empty — nothing to navigate
3. The agent binary **predates the sealed-mission feature** — it logs `-> process` instead of
`runs ONE mission (sealed): `
## "may not post to session"
```
[external] '' may not post to session 'ext-s-…'
```
A **cached session** outlives a policy change, a re-seal, or a restart, and does not self-heal.
Retire the entry under `/peer-sessions/` and the next call mints a fresh one.
## The door answers your own question back to you
```json
{"ok":true,"accepted":"response"}
```
The caller and the door share a `HEIA_DIR`. The caller's "expecting a reply" record and the door's
inbox are the same file, so your question lands on your own expectation. Give each its own store.
## "REFUSED to register router session … default-deny"
The router approved it and the **agent** refused. The `sha512(email)` subject has no inbound rule
on the serving agent:
```bash
./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule "${SUB},,inbound,allow"
```
## "not permitted to act on behalf of that subject"
The vouch was sealed for the **email** but the turn binds to `sha512(email)`. Seal the hash.
## Restarting one agent stops another
Some builds match agents by process name, so `restart` from a runner folder also stops the
workspace agent. **Read the output to tell which you have** — a folder-scoped restart names what
it left alone:
```
left alone: agent belonging to another folder (1987, 2001, …)
```
## "Text file busy" when replacing a binary
`cp` cannot overwrite a running executable. Worse, a script that ignores the error goes on to print
a success line built from the **unchanged** file — so the swap looks done and is not.
Stage a copy beside it and `mv` over the path, which replaces the directory entry rather than
writing into the open file. Then **verify the hash changed on disk** rather than trusting the
message.
## A merge or ingest that says it finished, and did not
`manifest.json` is written when concatenation ends, **before** the index build. A store with no
`terms.idx`, `centroids.bin` or `ivf-vectors.bin` is unfinished whatever the manifest says.
If it vanished mid-build, check for the kernel:
```bash
sudo dmesg -T | tail -30 # look for: Out of memory: Killed process … (hexaeight-engin)
```
A merge needs roughly **twice the shard total in RAM and on disk**. A group needs neither — prefer
it.
## An edited card still returns the old text
`chunks.jsonl` is **append-only**. `--memory-refresh` adds new chunks and leaves the old ones
retrievable, so a search can still return pre-edit text after a refresh that reported success.
Rebuild the memory, or import under a fresh name.
Also check *which copy* you edited: a memory's `manifest.json` records the **source path it was
ingested from**. Editing a copy elsewhere changes nothing.
## Reading logs
Read the **tail**, or the whole file. Do not grep for the keyword you expect: the line that explains
a failure usually sits next to the one you searched for, and filtering hides it.
==============================================================================
SECTION: Reference
==============================================================================
------------------------------------------------------------------------------
PAGE: hexaeight-activate — the whole CLI
URL: /docs/reference/activate/
ABOUT: Every command, grouped by what you are trying to do — activate an identity, install a component, define an engine, provision an agent, set policy, run it.
------------------------------------------------------------------------------
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](/docs/start/what-gets-installed/) runs most of these for you; the agent's and the
router's own commands are [at the end](#the-agents-own-commands).
```bash
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`, 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](/docs/operate/lifecycle/#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.mac` **are** 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.
---
## 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.
```bash
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 ~/heia-runner \
--file ~/heia-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:
```bash
./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 --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 [--copy]`, `--unshare `. 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. |
```bash
hexaeight-activate add-external-agent \
--from ~/hbia-agent \ # identity only — hardlinked, never copied
--dir ~/heia-runner \
--mission My_Mission \
--license personal \
--owner you@example.com \
--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=-frontdoor/heia`).
See [The external front door](/docs/extend/external-callers/) 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 |
|---|---|
| `mission-export` (alias `agskill-export`) | Export a mission as a portable `.zip` bundle: `--mission [--out .zip] [--no-data] [--include-large]` |
| `mission-import` (alias `agskill-import`) | Import one: `--in [--root ] [--force]` |
```bash
hexaeight-activate mission-export --mission My_Workflow --out My_Workflow.zip
hexaeight-activate mission-import --in My_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](/docs/concepts/missions/).
### 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 --venv PATH` | Use a Python environment you already have (it must import the framework); nothing is installed into it. |
| `enable --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](/docs/extend/frameworks/).
---
## Policy — who may do what
| command | what it does |
|---|---|
| `add-policy --owner ` | 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:
```bash
hexaeight-activate list-policy --subject you@example.com
```
Rules are default-deny. See [Policy](/docs/operate/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.
> **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](/docs/operate/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.
---
## The agent's own commands
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.
| command | what it does |
|---|---|
| `hexaeight-agent.json --add-rule ''` · `--remove-rule ''` · `--list-rules` | add, remove or list a policy rule. See [Policy](/docs/operate/policy/). |
| `hexaeight-agent.json --compliance-info all` | the [compliance report](/docs/operate/compliance-reports/): `soc2`, `hipaa`, `eu-ai-act`, `dpdpa` or `all`, and `--json` |
| `hexaeight-agent.json --access-review` | who and what can reach this agent |
| `audit-export` | decrypt and verify the [audit trail](/docs/operate/audit/): `--from`, `--to`, `--session`, `--router-usage` |
| `audit-sink set` · `test` · `off` | send the audit trail to your SIEM |
| `hexaeight-agent.json check-stores` | open every encrypted store and report; changes nothing |
| `hexaeight-agent.json restore-store ` | put a store's last-good copy back. See [Encrypted stores](/docs/operate/stores/). |
| `hexaeight-agent.json oauth-link set` · `status` · `dns` · `test` | link the agent to your company's OAuth app. See [HexaEight and OAuth](/docs/concepts/oauth/). |
| `vouch allow` · `vouch list` | who may act on behalf of whom |
## The router's own commands
Run from the router's folder. The binary is `hexaeight-router-linux-x64`, or
`hexaeight-router-osx-arm64` on macOS.
| command | what it does |
|---|---|
| `--setup` | write the router's configuration the first time |
| `--init-policy` | the router's own rules; prints the current ones before asking anything |
| `--compliance-info all` | the router's compliance report, including every model provider and its region |
| `audit-export` | decrypt and verify the router's audit trail |
| `audit-sink set` · `test` · `off` | send it to your SIEM |
------------------------------------------------------------------------------
PAGE: Settings — every file, every key
URL: /docs/reference/settings/
ABOUT: Which file each setting lives in, what it does, and which tool changes it. The answer to "where does this go?
------------------------------------------------------------------------------
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](/docs/operate/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](/docs/operate/audit/) 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](/docs/concepts/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](/docs/router/forward/#keep-outside-callers-private) |
| `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](/docs/operate/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`.
------------------------------------------------------------------------------
PAGE: Glossary
URL: /docs/concepts/glossary/
ABOUT: Every term the docs use, in one place — agent, runner, engine, mission, memory, route, vouch, subject, and the rest.
------------------------------------------------------------------------------
Terms in the order you meet them, not alphabetically — each one builds on the ones above it.
## Identity
**Identity (vault)** — an email address, protected by a password, held in the Authenticator on your
phone. The app titles the list *Identities*; the button says *+ New Email Vault*. Same thing. **A
person has one; an agent does not.**
**Resource** — a name assigned to your identity, which an agent then runs under. Two kinds:
**generic** (the name is generated, like `api12-lock-java-pressure83`) and **domain** (a name on a
domain you control, proven by a DNS TXT record checked when a licence is granted).
**Subject** — how a person is named inside the system: `sha512(their email)`, never the address
itself. Policy rules and vouches use the hash.
**Agent token** — lets a browser app authenticate **to your agent**. Created in the Authenticator
under a resource. Not how people sign in — that is alt-auth.
**ASK (Asymmetric Shared Key)** — the key material one identity fetches to talk to another. It
is issued per *(sender, recipient, time window)*, rotates every 15 minutes, and is derived from the
sending machine's fingerprint, its resource name and its password — so the same resource name on a
different machine, or with a different password, produces a different ASK. **The 15-minute window
governs when the platform will issue it, not how long it works:** an ASK you already hold decrypts
its messages permanently. The corollary matters — if you need to read those messages after the
window closes, **keep the ASK with the ciphertext**, because the platform will not reissue it and
there is no escrow.
**Dead Drop Encryption (DDE)** — how two identities exchange a message without exchanging keys.
Each pair derives a shared key for a 15-minute window from their identities alone, so you can
encrypt to a name **before that name exists**, the recipient need not be online, and the platform
that issues keys is never in the data path. It is the primitive underneath every other term here.
## The parts you run
**Agent** — a running identity. It proves who is calling, decides whether they are allowed, and
hands the work to an engine. One folder, one identity, its own policy.
**Runner** — a second agent whose job is to serve outside callers, with its own ports and policy and
**one sealed engine**. Branching one off is how you let users in without exposing your workspace.
**Engine** — the unit of work an agent encloses. You do not write an agent; you write or seal an
engine, and the agent wraps it in identity and policy. Every agent ships with the built-in
[harness engine](/docs/concepts/harness/) (`hexaeight-engine`): memories, sessions, the tool loop and missions.
**Router** — holds the model credentials so no agent does. Agents ask for a *route name*; the router
resolves it to a provider and decides whether that caller may use it. Runs under its own identity,
in its own folder.
**Route** — a glob you choose (`*-ant-aws`, `glm5br*`) that names an upstream in `upstreams.yaml`.
An engine sends `route|model`; the router matches the left half and puts the right half on the wire.
**Harness** — the AI runtime that ships with every agent and runs on your machine, in a sandbox. The
agent starts it for each question; it searches memories, follows missions and reaches the model only
through the router. See [The harness](/docs/concepts/harness/).
**Workspace** — the browser console for the operator. A client, not the agent. It holds no identity
and no model keys. See [The workspace](/docs/start/workspace/).
**`heia`** — the command the installer adds to start, stop, restart and check the router, the agent
and the workspace, from any folder. See [Lifecycle](/docs/operate/lifecycle/).
## What an agent works with
**Memory** — how an agent reaches information: a named, searchable body of documents, an API, or
another agent. **Local** (ingested on this machine) or **served** (held by another agent and reached
by name over an encrypted channel). See [Memories](/docs/extend/documents/).
**`connect-to-agent`** — the memory every agent has built in, through which it asks another agent a
question by name.
**Shard** — one part of a large collection, indexed by its own process. The shards are then searched
together as one memory.
**Mission / procedure** — a written-down method an agent follows instead of improvising: a
**flowchart** (which card handles which question), **cards** (the steps), and a **fence** (what it
may touch), plus optionally the **files** it carries and a **command set** sealed in the agent. The
CLI and log lines say *mission*; some pages say *procedure*. Same thing. See
[Missions](/docs/concepts/missions/).
**Mission Runner** — the place in the workspace where you run a mission and check its answers.
**HexaPilot** — long jobs the agent runs on its own. You describe the job and approve its flowchart
once; it then plans, works and checks its own work inside its own folder.
**Guided / direct mission** — in a *guided* mission the agent's model walks the map and the card's
steps. A *direct* mission has one card with `mode: direct`: every message is written to a file and
handed to one approved command, with no model step in the harness. Framework runners are direct.
**Mission files** — files kept beside a mission's cards (a framework's `runner.py`, say). They travel
with the mission and are copied fresh into every turn's working folder.
**Card (capability card)** — one procedure, for one kind of question: intent, match cues, resources,
steps, dos and don'ts, and a done-check. The decisions a mission makes are made on its cards.
**Fence** — the `_manifest.md` listing the only memories and commands a mission may use. Not a
guideline: a limit.
**Cmdset** — the set of shell commands a mission is permitted to run, sealed in the agent (never in
the mission's bundle) and each pinned to the sha256 of the file it runs. No cmdset means no shell at
all, which is the default. `cmdset seal` records one; `enable` does it for a framework mission.
**Runner store** — a runner's own harness root. A runner sees only its mission until a memory is
exported into it with `runner-memory --share` (a served memory's pointer, or a local memory linked or
copied).
## Letting others in
**BYOA** — *bring your own auth*. You keep whatever login you already have; your backend calls the
runner and names the user. Your users notice nothing.
**alt-auth** — the other door. Users sign in with the HexaEight Authenticator: the agent seals a
one-time code to their address, they type it in, and no password ever reaches you.
**Front door** — the `/external/*` surface a runner exposes, which both BYOA and alt-auth arrive at.
**Vouch** — permission for one identity to act **on behalf of** a subject. It is what makes a turn
bind to a person rather than to the agent.
**Opaque caller** — a caller the agent keeps private: it sends `:opaque:` to the router instead of who
the caller is, and the router records the call against the agent. An agent does this for outside
callers when `external.opaqueCallers` is on.
**OAuth link** — an agent linked to your company's OAuth app, so that other agents can check, on every
message, that your company still stands behind it. See [HexaEight and OAuth](/docs/concepts/oauth/).
## Records and controls
**Audit trail** — the agent's sealed, chained record of what it allowed, ran and refused. It never
holds the content of a message. See [Audit trail](/docs/operate/audit/).
**SIEM sink** — where the audit trail is sent as it is written: your log pipeline, over HTTPS.
**Compliance report** — a read-only report of the controls in force, checked against SOC 2, HIPAA,
the EU AI Act and India's DPDP Act. See [Compliance reports](/docs/operate/compliance-reports/).
**Access review** — a read-only list of who and what can reach an agent: rules, sessions, approvals
and machines.
**Approval** — a person's yes or no to something the agent wants to do, such as a command or the first
use of the web. Approvals in conversations and HexaPilot are recorded in the audit trail.
**Startup check** — before it starts, the agent opens every encrypted store. If one does not open, it
does not start. See [Encrypted stores](/docs/operate/stores/).
**Last-good copy** — one of the two copies of a store kept after a start that passed. `restore-store`
puts one back.
**Idle sign-out** — the workspace signs a person out after a period without activity. See
[Admin settings](/docs/operate/admin-settings/).
**Privacy notice** — what the terms screen tells people before they accept. It can be the standard one
or your organisation's own, and it goes together with consent withdrawal.
## Files and places
**`env-file`** and **`hexaeight.mac`** — the identity, machine-bound. Never copied; hardlinked when
one machine needs them in two folders.
**`upstreams.yaml`** — the router's only config: its upstreams, and its own settings such as
`requireIdentifiedCaller`.
**`router-policy.he`** — the router's rules, sealed under the router's own key. Read it by starting
the router (it prints every rule) or with `--init-policy`.
**`engines.he`**, **`policy.csv`**, **`vouch.he`** — some of the agent's sealed stores. Changed
through the CLI or the workspace, never with an editor. See [Every setting](/docs/reference/settings/).
**`hexaeight-agent.json`** — the agent's settings, in plain JSON. The running agent only reads it,
and every change to it is recorded in the audit trail.
**Harness root** — where an engine keeps its memories, missions and sessions. Passed as `--root`.
A runner usually has its own, separate from the workspace agent's.
**`HEIA_DIR`** — an agent's own store for sessions and skills. A caller and the door it calls
**must not share one**, or the door answers your question back to you.
**Sealed** — encrypted under the agent's own key, so only the agent can read or change it. Sealed
files are edited through the CLI.
**Jail** — every engine turn runs with the identity folder masked, so a turn cannot read `env-file`
even though it runs as the agent.
------------------------------------------------------------------------------
PAGE: For AI agents
URL: /docs/llm/
ABOUT: A machine-readable index of these docs, and the full text in one file — for an agent helping someone install or integrate HexaEight.
------------------------------------------------------------------------------
If you are pointing an AI agent at this documentation, give it one of these:
| | |
|---|---|
| **[/llms.txt](/llms.txt)** | the index — what each page covers, small enough to paste into a prompt whole |
| **[/llms-full.txt](/llms-full.txt)** | every page concatenated in reading order, for ingesting in one fetch |
Both are generated from these pages, so they cannot drift from what you are reading.
## What the index carries
Beyond the page list, `llms.txt` states the facts an integration usually gets wrong: that identity files are machine-bound, that nothing is enforced until the first policy rule exists, that a person appears in policy as `sha512(email)`, that the router's only config file is `upstreams.yaml`, and that the start order is router, agent, workspace.
## Sections, in reading order
- **Start here** — what this is, and the shortest path, POINT AN AGENT AT THIS TO INSTALL — the whole procedure as cards, per OS, installing, by hand or by agent, with the per-OS differences…
- **Extending an agent** — give it documents to search (memories), put an HTTP service you already run behind it, put your OWN code behind it: a process, declared argv in, JSON out…
- **Model access** — run your own router; write its rules, forward to someone else's router, keeping your user list private…
- **How it works** — why the existing stack cannot do this, the parts, one at a time, THE HARNESS ENGINE: the built-in runtime — memories, sessions, tool loop, missions, command gate, jail, harness root…
- **Operating it** — who may do what, start, stop, upgrade, revoke, measured cost per turn, and sizing…