# HexaEight documentation — full text Every page in reading order. Routes are given so you can cite them. ============================================================================== SECTION: Get started ============================================================================== ------------------------------------------------------------------------------ PAGE: HexaEight Documentation URL: /docs/ ABOUT: An AI agent with its own identity, running on your machine. It searches the memories you give it, follows the missions you design and talks to other agents with end-to-end encryption, under policy at every layer. ------------------------------------------------------------------------------ HexaEight gives you an **AI agent that runs on your own machine and has its own identity**. You talk to it in a browser. It searches the information you give it, follows the processes you design, works on your servers and talks to other agents securely, under rules you set. ## The picture ```mermaid flowchart LR W["Workspace
your browser"] <-->|"encrypted end to end"| A["Your agent
its own identity"] A <--> H["Harness
AI runtime, on your machine"] H <--> M["Memories
documents · APIs · other agents"] A <-->|"encrypted"| R["Router
holds the model key"] A <-->|"by name, encrypted"| O["Other agents"] ``` 1. **Your agent has an identity.** It is installed on your machine and bound to it, under a name on your own domain (`agent.yourcompany.com`) or a generated one. It publishes itself under that name, so your workspace and other agents can find it, and every message between them is encrypted end to end and proves who sent it. → [Identity](/docs/concepts/identity/) 2. **It all runs on your machine.** Your browser talks to your agent. The agent runs the AI runtime, the **harness**, for every question, and reaches the model only through your **router**, which holds the provider key. The answer comes back encrypted end to end. → [The harness](/docs/concepts/harness/) · [What gets installed](/docs/start/what-gets-installed/) 3. **Nothing to wire up.** There are no MCP servers, skill files or instruction files to write. The agent reaches information through **memories**, and it decides which to search for each question. → [Memories](/docs/extend/documents/) 4. **Memories from your documents.** Add files and they are indexed on your machine, on the CPU. The agent searches them and cites what it used. 5. **Memories that reach further.** An API you already run, documents another agent serves, or another agent itself can all be memories, searched by name and encrypted end to end. Very large collections are split into shards and searched as one. → [An API you already run](/docs/extend/api/) 6. **You see every step, and nothing is allowed until you allow it.** The workspace shows which memory the agent searched and what came back. Policy applies at every layer: who may sign in, which agents may call it or be called by it, which commands may run. What it allowed, ran and refused is recorded in a sealed audit trail. → [Policy](/docs/operate/policy/) · [Audit trail](/docs/operate/audit/) 7. **Missions instead of prompts.** Describe a process in plain words, and it becomes a flowchart of **capability cards** that make the decisions, with the memories it may search. It runs the same way every time. Test it in Mission Runner, or hand a long job to HexaPilot. → [Missions](/docs/concepts/missions/) 8. **Bring your framework.** CrewAI, LangGraph, Pydantic AI and Agno run on the same harness, with the same identity, memories and policy. → [Frameworks](/docs/extend/frameworks/) ## Install it One command, run twice, on Linux (x86_64), Windows (in WSL) or an Apple Silicon Mac: ```bash curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash ``` The first run prepares the machine and stops at the licence, the one step only you can do. The second run installs the rest and ends with the address of your workspace. See [What gets installed](/docs/start/what-gets-installed/). You will need the **HexaEight Authenticator** app on your phone, which holds your identity, and a **licence code**. See [Installing](/docs/start/install/). ## Find your way | | | |---|---| | **Use it** | [The workspace](/docs/start/workspace/) · [Memories](/docs/extend/documents/) · [Missions](/docs/concepts/missions/) | | **Connect it** | [An API you already run](/docs/extend/api/) · [Two agents talking to each other](/docs/extend/agents-talking/) · [Your own users](/docs/extend/your-users/) · [Other software calling it](/docs/extend/external-callers/) · [Frameworks](/docs/extend/frameworks/) | | **Models** | [The router](/docs/router/overview/) · [Run your own](/docs/router/own/) · [Serve models to agents](/docs/router/providers/) · [Use someone else's router](/docs/router/forward/) | | **Security and compliance** | [Compliance](/docs/concepts/compliance/) · [Audit trail](/docs/operate/audit/) · [Compliance reports](/docs/operate/compliance-reports/) · [Admin settings](/docs/operate/admin-settings/) · [HexaEight and OAuth](/docs/concepts/oauth/) | | **Run it** | [Lifecycle](/docs/operate/lifecycle/) · [Encrypted stores](/docs/operate/stores/) · [Capacity](/docs/operate/capacity/) · [Troubleshooting](/docs/operate/troubleshooting/) | | **Understand it** | [Why this exists](/docs/concepts/problem/) · [Components](/docs/concepts/components/) · [Architecture](/docs/concepts/architecture/) · [Dead Drop Encryption](/docs/concepts/dde/) · [Trust and permission](/docs/concepts/trust/) | | **Look it up** | [Every command](/docs/reference/activate/) · [Every setting](/docs/reference/settings/) · [Glossary](/docs/concepts/glossary/) | ## What this is not It is not a framework you have to write your agent in. Keep what you already have, whether that is a Python service, a REST API or an agent framework, and HexaEight puts an identity, memories and a policy boundary around it. Calling an agent is an authenticated request in and an answer out, in any language. Putting your own code behind one is a process the agent runs; see [Bring your own engine](/docs/extend/own-engine/). ------------------------------------------------------------------------------ PAGE: Installing URL: /docs/start/install/ ABOUT: Set up the Authenticator on your phone, get a licence, and run one command twice. That is the whole install, on Linux, Windows (in WSL) or an Apple Silicon Mac. ------------------------------------------------------------------------------ Installing takes **one command, run twice**. In between, you activate your licence with the HexaEight Authenticator on your phone. ## 1 · Set up the Authenticator on your phone Install **HexaEight Authenticator** from the App Store or Google Play. It is free.
Create your identity: an email address and an optional display name.
Enter your email
Verify your email and set a password: a verification email is on its way.
Verify it, set a password
Identities: the new email vault, active, with Scan to authenticate.
Your identity is ready
A generic resource under the email vault, named api12-lock-java-pressure83, with Tap to scan.
Add a resource
1. **Create your identity.** Enter your email address. Use a real, permanent one: an identity cannot be deleted without reinstalling the app. 2. **Verify it and set a password.** Open the email from `DONOTREPLY@hexaeight.com` (check spam) and scan its QR code, or tap the link if you read it on the same phone. 3. **Add a resource for your agent.** Tap **+ Add** and choose **Generic Resource**. The app gives it a name such as `api12-lock-java-pressure83`: that becomes your agent's name. You will type it in step 4. To use a name on your own domain, such as `agent.yourcompany.com`, add a **Domain Resource** instead. It needs an email address on that domain and a DNS record; see [The Authenticator](/docs/concepts/authenticator/). ## 2 · Get a licence Buy one at [store.hexaeight.com](https://store.hexaeight.com). The licence code arrives by email. Licences are sold by CPU cores; the installer shows how many this machine has when it starts. The HexaEight Store: the Personal Licence, priced by CPU cores. ## 3 · Run the installer On Linux (x86_64), on Windows in the WSL Ubuntu terminal, or on a Mac with Apple Silicon: ```bash curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash ``` It checks the machine, installs what it needs, asks for your email address (the one in your Authenticator) and stops at the licence: ```text ━━ 2 · Licence The owner is the email you sign in to the workspace with — the one your Authenticator vault uses. Owner email: you@example.com ✓ owner: you@example.com Now activate the licence — this step is yours. source ~/.bashrc cd ~/hbia-agent && hexaeight-activate newtoken When it says the licence works, run this installer again — it carries on from here. ``` On Linux it also checks for `bubblewrap` and `libicu`, which an administrator installs once; it says so if they are missing. ## 4 · Activate the licence Run the two lines it showed you (on macOS the first is `source ~/.zshrc`): ```bash source ~/.bashrc cd ~/hbia-agent && hexaeight-activate newtoken ``` It asks three things: ```text Machine Token License Activation ---------------------------------------------------------------------- Enter Resource Name : api12-lock-java-pressure83 Enter New Password For Your Resource : [Press Enter to Generate a Password] Enter the License Code Received in your Email : •••••••• ---------------------------------------------------------------------- Do You Want to Display A QRCode ? [Y/N] ``` 1. **Resource name:** the name from step 1. 2. **Password:** just press **Enter**, and a password is generated for you. 3. **Licence code:** the code from your email. Answer **Y** to show the QR code. On your phone, open the Authenticator, tap your **resource** (it says *Tap to scan*) and scan the QR code. When the app has approved it, press any key in the terminal. It asks whether your licence is yearly, then checks that the licence works: ```text Is this a yearly licence? [y/N]: n Activation completed. Running a quick license verification... Identity: api12-lock-java-pressure83 Congratulations — your HexaEight license is installed and working. ``` ## 5 · Run the installer again The same command: ```bash curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash ``` It sets up the router (you choose your model provider and type its key, which is not shown), installs and starts the agent and the workspace, makes them reachable from anywhere, and has them start at login. It ends like this: ```text ━━ 6 · Gateway (reachable from anywhere) ✓ agent reachable at https://.trycloudflare.com ✓ registered as api12-lock-java-pressure83 — other agents find it by name ✓ workspace reachable at https://.trycloudflare.com ━━ 7 · Start at login … Done. Open https://.trycloudflare.com and sign in as you@example.com with your Authenticator. Ask it something — an answer in the browser proves the whole chain. ``` **The address after `Open` is your workspace.** It works from any browser, including your phone. On the machine itself, `http://localhost:5620` works too. `heia status` shows the addresses again at any time. ## 6 · Sign in 1. Open that address and enter your email. 2. Choose **Scan with HexaEight Authenticator**. A QR code appears. 3. In the Authenticator, tap **Scan to authenticate** on your identity and scan it. 4. Type the access code the app shows, and choose **Continue**. Then ask something: an answer proves the whole chain works. See [The workspace](/docs/start/workspace/) for what is where. ## Options | | | |---|---| | keep everything on this machine, with no public address | `curl -fsSL …/install.sh \| bash -s -- --skip-gateway` | | do not add this computer under **Machines** | `curl -fsSL …/install.sh \| ENABLE_FLEET=0 bash` | With `--skip-gateway`, the workspace is at `http://localhost:5620` on that machine only. ## After the install ```bash heia status # what is running, and its addresses heia restart [agent|router|all] # restart, through the service manager heia logs [agent|router] # follow a log ``` The public addresses change when the machine restarts. The agent publishes its new one by itself; for the workspace, run the installer again to get the new link. To update, run the same command again: only what has a newer release is downloaded. To remove everything, follow [UNINSTALL.md](https://github.com/HexaEightTeam/hbia-agent/blob/main/UNINSTALL.md). For what was installed where, see [What gets installed](/docs/start/what-gets-installed/). ------------------------------------------------------------------------------ PAGE: What gets installed URL: /docs/start/what-gets-installed/ ABOUT: One command, run twice — what it puts on your machine, where each part lives, which ports it uses and what it switches on. Linux, Windows through WSL, and Apple Silicon Macs. ------------------------------------------------------------------------------ The installer sets up everything an agent needs on **one machine**: your licence, a model router, the agent with its AI runtime, and the workspace you use in a browser. It never asks for administrator rights — the two system packages it relies on are listed below, for whoever looks after the machine. ```bash curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash ``` **Run it twice.** The first run prepares the machine and stops at the licence, the one step only you can do. Run the same command again and it installs the rest. ## Where it runs | | | |---|---| | **Linux** | x86_64 | | **Windows** | inside **WSL** (Ubuntu). Install WSL, open the Ubuntu terminal and run everything there. Keep HexaEight in your Linux home folder, not under `/mnt/c`. | | **macOS** | Apple Silicon | Intel Macs and ARM Linux have no build. ## Before you run it — once, by an administrator | | | |---|---| | `curl` | to download the installer | | **Linux:** `bubblewrap` and `libicu` | `sudo apt-get install -y bubblewrap libicu-dev` on Debian or Ubuntu, `sudo dnf install -y bubblewrap libicu` on Fedora or RHEL | | **Ubuntu that restricts user namespaces** — Azure's Ubuntu 24.04 images do | the installer stops and prints a short AppArmor profile that lets `bubblewrap`, and nothing else, start the sandbox. Apply it once, then run the installer again. | | memory | 4 GB or more | `bubblewrap` is the sandbox every AI turn runs in. macOS needs nothing: its sandbox is built in. ## The two runs **First run** 1. **Checking this machine** — the platform, the prerequisites, and that the sandbox can start. It installs .NET 8 into `~/.dotnet` and the `hexaeight-activate` command-line tool. 2. **Licence** — it asks for the **owner email**: the email you sign in with, the one your Authenticator vault uses. Then it stops, and you activate the licence yourself: ```bash source ~/.bashrc # on macOS: source ~/.zshrc cd ~/hbia-agent && hexaeight-activate newtoken ``` It asks for the resource name from your Authenticator, a password (press Enter and one is generated for you) and your licence code, then shows a QR code to approve in the Authenticator on your phone. When it says the licence works, run the installer again. See [Installing](/docs/start/install/#4--activate-the-licence) for each screen. **Second run** — the same command 3. **Model router** — either run one here with your own provider key (AWS Bedrock, z.ai, Azure AI Foundry, Azure OpenAI, OpenAI, OpenRouter, or any compatible address), or use a router that already runs elsewhere. The key is typed without being shown and stays with the router. 4. **Agent** — downloaded, checked against its published hash, given its starting policy and connected to the router. 5. **Workspace** — the browser interface. 6. **Gateway** (optional) — makes the agent and the workspace reachable from anywhere. 7. **Start at login** — hands everything to the system's service manager. It ends with the address of your workspace. Open it, sign in with your Authenticator and ask something: an answer proves the whole chain works. ## What ends up where | Folder | What it holds | |---|---| | `~/hbia-agent` | **Your licence** — `env-file` and `hexaeight.mac`, bound to this machine. Never move, rename or copy them. | | `~/heia-router` | The **router**, and your provider key. | | `~/heia-agent` | The **agent**: its settings (`hexaeight-agent.json`), its policy and its encrypted stores. | | `~/.heia/runtime/harness` | The **[harness](/docs/concepts/harness/)** — the AI runtime the agent starts for every turn — and, if they download, small local vision models that describe images for models that cannot see them. | | `~/.heia/runtime/workspace` | The **workspace**: the web pages and the small server that serves them. | | `~/.hexaeight-harness` | What the harness keeps: your **memories**, your **missions** and your conversations. | | `~/.heia/bin` | The `heia` command, and the two tunnel programs the gateway uses. | | `~/.dotnet` | .NET 8 and `hexaeight-activate`. | The router and the agent each get the licence as a **hard link** — the same file under a second name, never a copy. A copy of a licence file would be a second licence. ## Ports | Port | What answers | |---|---| | **5100** | the router | | **8770** | the agent | | **5620** | the workspace, at `http://localhost:5620` | The agent's helper processes listen only on `127.0.0.1`. **The gateway opens nothing inbound**: its tunnels connect outward. The agent's tunnel carries only messages that are already encrypted end to end; the workspace's tunnel serves its web pages over HTTPS. ## What is on when it finishes - **Only you.** A starting policy where you, the owner, can sign in and use the agent, and everything else is refused until you allow it. - **Machines.** This computer is added as a machine you can work on from chat, and every command the AI proposes waits for your approval. - **Reachable from anywhere.** The agent publishes itself under its name, so your workspace and other agents find it by name. To keep everything on this machine instead: ```bash curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash -s -- --skip-gateway ``` The gateway's addresses are temporary and change when the machine restarts. The agent publishes its new one by itself; for the workspace, run the installer again to get the new link. For a fixed address on your own domain, use a named Cloudflare tunnel. ## After the install ```bash heia status # what is running heia restart [agent|router|all] # restart, through whatever runs it heia logs [agent|router] # follow a log ``` `heia` works from any folder. Once the service manager runs the services, restart them with `heia` rather than `hexaeight-activate restart` — a second copy started beside the first fights it for its port. On a Linux server the installer also lets the services keep running when nobody is logged in; if it is not allowed to, it says which command an administrator runs. **On Windows**, if WSL is not set up to run services, everything keeps running but does not start again by itself. After restarting Windows, open Ubuntu and run `heia start all`. ## Running it again Safe at any time. It compares what is installed with the latest releases, downloads **only** what has a newer one, and keeps each previous binary beside the new one. See [Lifecycle](/docs/operate/lifecycle/). ============================================================================== SECTION: The agent ============================================================================== ------------------------------------------------------------------------------ PAGE: Memories URL: /docs/extend/documents/ ABOUT: How your agent reaches information — your documents, documents another agent serves, an API, another agent — all as memories it searches by name, and cites. ------------------------------------------------------------------------------ A **memory** is how your agent reaches information. There are no tools to wire up and no prompts to write: you give the agent memories, and for each question it decides which ones to search. | A memory can be | What the agent does with it | |---|---| | **your documents** | searches them, on this machine | | **documents another agent serves** | searches them through that agent — by name, encrypted end to end. The documents stay where they are. | | **an API** | calls it through the agent that serves it, the same way | | **another agent** | asks it a question. Every agent has the `connect-to-agent` memory built in. | ## How a memory is used Every memory has a **name** and a one-line **description**. When you ask something, the agent's [harness](/docs/concepts/harness/) sees the list of memories with their descriptions, picks the ones that fit, searches them, reads what it found and searches again until it can answer — and it cites where each piece came from. In the workspace you can follow this as it happens: which memory it searched, and what came back. A conversation can search **any** memory by name. You can also attach one memory that it consults on **every** turn: the memory chip under the message box. ## Your documents In the workspace, open **Memory**: 1. **New memory** — give it a name (lower-case letters, digits, `-` and `_`) and a one-line description. 2. **Add documents** — **Upload** files from your computer, or **Add Files From Agent** to pick files or whole folders on the agent's machine. Markdown, text and PDF. 3. **Save & embed.** The documents are indexed on the agent's machine, on the CPU — no GPU needed. You can leave the page; it keeps going. Then ask about them from a chat or a mission. After you change the documents, **Rebuild index**. **Delete** removes the memory. ## Write the description for the model The description is what the model reads when it decides whether a question belongs to this memory. - **Say what is inside, in the words the documents use.** "Company handbook" tells it little. "Policies, benefits, travel, expenses, leave — what an employee is entitled to and how to claim it" tells it when to reach for this memory. - **Say what to cite.** If your documents carry ids or numbers, say so, and ask for them to be quoted. - **Warn about your own vocabulary.** A question about a "time limit" will not find documents that call it a "timebox". One line in the description fixes that. ## Documents another agent serves Some collections are too large, too private or too widely shared to copy to every machine. Another agent can serve one, and yours searches it **through that agent** — by name, encrypted end to end, and under both agents' policies. Your agent holds only a pointer, never the documents, and never learns where the other agent runs. In **Memory**, add it with the name of the agent that serves it and the service's name on that agent. If that agent is not in the registry, give its address instead. **Refresh description** fetches the latest description from the serving agent; **Unregister** removes the pointer here and leaves the collection untouched. Both agents' policies have to allow the call — see [Two agents talking to each other](/docs/extend/agents-talking/). ## An API An API you already run becomes a memory the same way: put it behind an agent ([An API you already run](/docs/extend/api/)), and other agents add it as a served memory. Callers reach it by the agent's name, encrypted, and never see its host, its port or its key. ## Another agent Your agent can put a question to any other agent, by name, through the built-in `connect-to-agent` memory. There is nothing to set up beyond the policy rules that allow it — see [Two agents talking to each other](/docs/extend/agents-talking/). ## Large collections Indexing runs on the CPU and handles very large collections by splitting them into **shards**. Each shard is indexed by its own process, and the shards are then searched together as one memory. ```bash E=~/.heia/runtime/harness/hexaeight-engine R=~/.hexaeight-harness # index the collection as 8 shards — run one command per shard, 0 to 7 $E --addmemory mycorpus-sh0 --file /path/to/documents --shard 0/8 --defer-index --root $R # …the same for 1/8 to 7/8, each into its own memory: mycorpus-sh1 … mycorpus-sh7 # search them together as one memory $E --memory-group mycorpus --members 'mycorpus-sh*' --root $R $E --memory-group-router mycorpus --root $R ``` The group needs no copy and almost no extra disk. ## Check a memory ```bash $E --memory-list --root $R $E --memory-search --root $R -p "a real question" ``` If a search finds nothing, check in this order: the memory's name, that the agent serving it is reachable, and whether the documents use different words than the question. ------------------------------------------------------------------------------ PAGE: Missions URL: /docs/concepts/missions/ ABOUT: There are no prompts to write. Chat when you want to talk; build a mission when a piece of work must be done the same way every time — you describe it, it becomes a flowchart of capability cards, and the agent follows it. ------------------------------------------------------------------------------ HexaEight has **no prompts to write**. In a chat you just talk to your agent and get the work done. When a piece of work has to be done **the same way every time** — reviewing a request, checking a document against a policy, answering one kind of question for your customers — you do not write a long prompt and hope it is followed. You build a **mission**: you describe how the AI should go about the work, the agent turns that into a flowchart of **capability cards**, and from then on it follows that flowchart. The same kind of question takes the same path, every time. | | **Chat** | **Mission** | |---|---|---| | **what you do** | talk | describe the process once | | **what the agent does** | works out each answer as it goes | follows the flowchart and its cards | | **good for** | research, drafting, one-off questions | repeatable work — the same steps and the same checks, every time | ## What a mission is made of ```mermaid flowchart TD Q["A question comes in"] --> MAP{"The flowchart:
which card handles it?"} MAP --> C1["Card
search a memory · check · decide"] MAP --> C2["Card
search a memory · check · decide"] C1 --> A["The answer, with its sources"] C2 --> A ``` - **The flowchart** — which card handles which kind of question. - **Capability cards** — one for each kind of question: what to search, what to check, what to decide and what to answer with. The decisions are made on the cards. - **Its memories** — the [memories](/docs/extend/documents/) it may search, and only those. - **Its commands** *(optional)* — the exact commands it may run, approved on your agent. There is no code to write. You describe the process in plain words and correct it in the same conversation. ## Build one In the workspace, open **Missions** and choose **Build a new mission**: 1. **Describe the process** in plain words — what comes in, what to check, what to decide, what to answer. 2. **Review the flowchart.** The cards take shape beside the conversation. Change anything by saying so. 3. **Ingest the mission.** It becomes a mission your agent can run. ## Run it and check it Open **Mission Runner**, start a session, pick the mission from the list above the message box and ask it the questions it is meant to answer. Check the answers. If one is wrong, correct the card in **Missions** and ingest again — the next run follows the corrected card. ## What keeps it on track - **Only its own memories.** A mission searches only the memories it lists. - **Only approved commands.** A mission runs a command only if that exact command was approved on your agent, pinned to the exact file it runs: change one byte of that file and it will not run until it is approved again. - **Its own folder.** Each run works in a folder of its own, inside the agent's sandbox. ## Long jobs — HexaPilot For a job that runs for a long time on its own, open **HexaPilot**: describe the job, review its flowchart, press **Start**, and watch it — or come back later. It plans, works and checks its own work, inside its own folder. You can ask how it is going, or stop it, at any time, and every command it runs goes through the same command gate, always enforced. ## Move it, share it ```bash hexaeight-activate mission-export --mission --out .zip hexaeight-activate mission-import --in .zip # on the other agent ``` 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` leaves out your documents and keeps only the pointers. A bundle never carries keys or secrets, policy rules, or permission to run a command. Those are set up again on the agent that imports it. ## The two kinds | | **Guided** | **Direct** | |---|---|---| | **a card says** | steps: search this, read that, decide, answer | `mode: direct`, and one command | | **who decides** | the agent's model, following the flowchart and the card | nobody: every message goes to the command | | **the model** | the harness's model works through the card | the harness makes no model call; the command may call one | | **typical use** | research, runbooks, compliance checks | a framework that does the work itself | | **cards** | as many as the work needs | exactly one | A direct card: ```yaml ## card: ask-runner id: ask-runner mode: direct direct_input: question.txt direct_run: "python3 runner.py --question-file question.txt" resources: files: [runner.py] commands: ["python3 runner.py --question-file question.txt"] ``` The harness writes the message to `question.txt`, so the message never reaches a shell. It runs the one command through the command gate and returns what it printed, unchanged. ## Frameworks as missions An agent framework you already use — CrewAI, LangGraph, Pydantic AI or Agno — can run as a mission: ```bash hexaeight-activate enable crewai ``` This installs the framework's mission and has your agent approve the one command it runs. The framework does the work; identity, memories, policy and approvals come from HexaEight. See [Frameworks](/docs/extend/frameworks/). ## Let other software use it A mission can be offered to other software through a **runner**: an agent sealed to that one mission. Callers choose the question, never the mission. See [Other software calling it](/docs/extend/external-callers/). ## Next - [A procedure it follows](/docs/extend/procedure/) — the flowchart and the cards, field by field - [Memories](/docs/extend/documents/) — what a mission searches ------------------------------------------------------------------------------ PAGE: A procedure it follows URL: /docs/extend/procedure/ ABOUT: Write down the right way to do something once, and the agent follows it every time instead of improvising a new route to the answer. ------------------------------------------------------------------------------ Ask a model the same question twice and it will take two different routes to the answer. Where there is a *right* way to do something — a research procedure, an incident runbook, a compliance check — that variability is the problem. A **procedure** is that method, written down, which the agent navigates instead of inventing one. > **Procedure and mission are the same thing.** These pages say *procedure*; the CLI flags and log > lines say *mission* (`--mission`, `runs ONE mission (sealed)`). > > This page is the **guided** kind — cards the agent's model walks through. For the whole picture, > including **direct** missions (one card, one approved command, no model step — how framework > runners work), the files a mission carries and its command set, see > [What a mission is](/docs/concepts/missions/). A mission has two lives, and both matter: | | | |---|---| | **in the workspace** | a **build session**. You describe what you want, it takes shape beside the conversation, and what you settle on is saved as the cards below | | **sealed onto a runner** | a **fixed procedure**. An outside caller asks a question and gets that method every time, and cannot ask for a different one | The first is how you make one; the second is how you ship it. This page is what sits in between — the cards themselves, which are worth being able to read even though you did not type them. ## What it is made of Three things, and the agent reads all three: | part | file | what it does | |---|---|---| | **the map** | `_flowchart.md` | which card handles which kind of question | | **the cards** | one `.md` each | the actual steps for one kind of question | | **the fence** | `_manifest.md` | what this procedure may touch, and nothing else | ``` My_Workflow/ sources/ _flowchart.md the map _manifest.md the fence find-case-law.md a card lookup-statute-text.md a card chunks.jsonl searchable index, built from the above vectors.bin ``` The agent searches a procedure the way it searches anything else: it finds the map, locates the question on it, walks to the right card, and executes that card's steps in order. ## 1 · The map ```mermaid flowchart TD start([Question arrives]) --> check{has a document id} check -->|yes| fetch[(memory: docs)] check -->|no| search[(memory: corpus)] search --> extract[[method: extract ids from hits]] extract --> fetch fetch --> scan[[method: scan all sections]] scan --> verify{answer found} verify -->|yes| done([Return answer with citation]) verify -->|more candidates| fetch verify -->|no| ask([Ask for clarification]) ``` Three node shapes carry meaning: | shape | means | |---|---| | `[(name)]` | search or read a collection of documents | | `[[method: x]]` | apply a rule defined in the card | | `{question}` | a decision the model makes | ## 2 · A card, field by field ```yaml ## card: find-case-law id: find-case-law intent: "Find decided cases on a point of law" match_cues: ["find a case", "is there authority", "what did the court hold"] domain: legal resources: memories: ["judgments", "judgment-full-text"] methods: - id: terminology-variations kind: rule apply: "The question may use everyday words where the source uses terms of art. Search several phrasings before concluding nothing exists." steps: - n: 1 do: "Search the judgments collection for the proposition" via: "memory: judgments" extract: " - candidate cases with their ids" then: "step 2" - n: 2 do: "Read the full text of the most relevant case" via: "memory: judgment-full-text" query: "" extract: " - what the court actually held" then: "step 3" - n: 3 do: "Confirm the holding answers the question as asked" via: "ai: verify relevance" then: "branch: found -> return, more candidates -> step 2, none -> ask user" dos: - "Cite the case id with every proposition" - "Read the full text before relying on a summary" donts: hard: - "do NOT query the full-text collection with a question - it takes ids only" soft: - "do not stop at the first plausible case" done_check: "A holding, with its case id, that answers the question as asked" ``` | field | what it is for | |---|---| | `id` | how the map refers to this card | | `intent` | one line: what this card is *for*. The model matches on this | | `match_cues` | phrasings that should land here. Write how people actually ask | | `resources.memories` | which collections this card may use — must also be in the fence | | `methods` | named rules the steps refer to, so a rule is written once and reused | | `steps` | the procedure. `do` = what, `via` = with which resource, `query` = what to send it, `then` = where next | | `dos` / `donts` | `hard` is never to be done; `soft` is a strong preference | | `done_check` | how the agent knows it is finished — not "did it try" but "does it have the answer" | > **`via:` names the resource; `query:` says what to send it.** A step that names a collection > without saying what to pass has been observed to make the model invent a call that does not > exist, get an error, and answer from partial results instead. ## 3 · The fence ``` ## memories judgments judgment-full-text case-summaries ## commands (none) ``` The runner may use **only** what is listed here. Not "should" — may. Combined with `exec-policy enforce ON, NO cmdset`, a procedure that lists no commands cannot run a shell at all. This is what makes a procedure safe to expose to callers you do not control: they choose the question, never the method, and the method cannot reach outside its fence. ## Writing one You do not hand-author these files. In the workspace, start a **new session on a `mission` engine** rather than `chat`. Then **describe what you want in conversation** — what question arrives, what should be searched, what must never happen. It takes shape in the panel beside the conversation as you talk, you correct it in the same conversation, and each revision is saved and re-indexed as you go. The YAML above is what it produces. You need to be able to *read* it — to check a step goes where you meant — but you do not need to write it. That matters because the person who knows the procedure is rarely the person who wants to write YAML. ### Never put an answer in a card Cards accept an `examples:` block, and it is tempting to paste in a worked example with its answer. > **Measured.** A card carried one example: a question, its answer, and the source id. Asked that > exact question, the agent found the card, read the answer straight out of it, and returned in > **three steps without searching anything**. It looked like excellent retrieval. It was recitation. > > With the example removed, the same question took **thirty-nine steps**, searched honestly, and got > it **wrong** — which had been the true state all along. Examples teach *shape*. One that carries a real answer stops you measuring the system and starts you measuring the card. ## Moving it to another machine ```bash hexaeight-activate agskill-export --mission My_Workflow --out mission-My_Workflow.zip hexaeight-activate agskill-import --in mission-My_Workflow.zip --root ~/.hexaeight-harness ``` The bundle carries the cards, the map, the fence and any files the mission keeps beside them (a framework's `runner.py`, say). It does **not** carry the document collections they search — those must already exist on the target — and **permissions never travel**, because they are specific to an identity: a mission that runs a command needs its command set sealed again on the receiving agent (`cmdset seal`). Cards a re-ingest retired are never shipped. > Import **refuses to overwrite**: `mission memory exists (use --force to overwrite)`. Without > `--force` nothing happened and the previous version is still the one running. Check what a bundle holds before trusting it: ```bash unzip -l mission-My_Workflow.zip ``` The card count is the number of `.md` files under `sources/` **minus** `_flowchart.md` and `_manifest.md`, which are not cards. ## Locking an agent to one procedure An agent can be sealed so it runs exactly one procedure, and a caller cannot choose another: ```bash hexaeight-activate engine --add runmission --name my-engine \ --mission My_Workflow \ --model "" --router "" \ --dir --file ``` `--file` names a small **wrapper script** that sits in front of the engine. You do not write it: `add-external-agent` creates it when it provisions a runner, in a folder beside the runner's own. Its job is to impose this door's procedure on every turn and strip anything a caller sends that tries to choose a different one. It must live **outside the agent's folder**, because each turn runs with that folder masked — a script kept inside it does not exist as far as the engine is concerned. Proof at startup: ``` [hexaeight-agent] engine 'my-engine' runs ONE mission (sealed): My_Workflow ``` **If that line is absent the procedure is not sealed**, and the agent will run whatever a caller asks for. See [Other software calling it](/docs/extend/external-callers/). ## When a procedure misbehaves | symptom | cause | |---|---| | it answers without searching | an `examples:` block contains the answer | | it invents a call and fails | a step names a resource but no `query` | | it cannot reach a collection | missing from the fence, or from `resources.memories` | | an edit has no effect | the index was refreshed rather than rebuilt — see [Troubleshooting](/docs/operate/troubleshooting/) | | a card you deleted is still being found | a workspace older than r35: ingest only ever added. From r35 a re-ingest is the complete set and drops removed cards from the mission and its index | | a caller ran a different procedure | the engine was re-sealed without `--file`, unbinding the wrapper | ------------------------------------------------------------------------------ PAGE: An API you already run URL: /docs/extend/api/ ABOUT: Put a service you already have behind a cryptographic identity. Callers reach it by name over an encrypted channel and never see the host, the port, or the key. ------------------------------------------------------------------------------ You have a service. It might be internal, it might wrap a vendor API you pay for, it might hold a key you would rather not distribute. Putting it behind your agent gives it an identity. Callers reach it **by name**, over an encrypted channel, and never learn the host, the port, or the key. The service itself does not change. ## What the service must do Three HTTP endpoints, bound to **loopback only** — the agent is the only thing that should reach it directly. ``` GET /health is it alive? GET //describe what is this, and what does it answer? POST / {"query": "..."} ``` The reply: ```json { "contract": "heia-service/1", "status": "ok", "results": [ { "score": 1.0, "document": "id", "source": "where it came from", "text": "the answer" } ] } ``` Bind it to loopback: ```python ThreadingHTTPServer(("127.0.0.1", 38490), Handler) ``` ### The description is read by a model, not a person `//describe` is not documentation. It is the text a calling model reads to decide whether to use your service at all. - it is read **live on every request**, so you can improve it without restarting anything - it is **capped at 400 characters** Spend them on what the service knows and when to reach for it. Not on how it was built. ## Seal it as a named route ```bash cd ~/heia-agent hexaeight-activate add-api --name weather --port 38490 heia restart agent ``` `add-api` probes `/health` and `/describe` **before** sealing anything. A service that cannot answer is refused, and the required contract is printed — so you find out now rather than when a caller does. To attach a credential the caller never sees: ```bash hexaeight-activate add-api --name weather --port 38490 --header 'X-Api-Key: ...' ``` The header is sealed with the route. Callers get answers; the key stays on your machine. After the restart, confirm the route: ``` [api] 1 route(s): weather->127.0.0.1:38490[GET/POST] | tiers=dde-auth | API-ONLY ``` ## The three settings that decide whether callers get in An API agent is called by **other agents**, not by people signing in. Three settings say so. Get one wrong and the agent runs normally, the route is sealed, and every call is refused. All three live in **`hexaeight-agent.json`**, in the agent's folder — see the [settings reference](/docs/reference/settings/). | setting | value | what it means | |---|---|---| | `external.api.enabled` | `true` | the API layer is on. A sealed route with it off is invisible. `add-api` sets this | | `api.tiers` | `["dde-auth"]` | the tier name for agent-to-agent calls. This exact string | | `authTiers` | **not present** | this key is for people signing in. Setting it closes the door agents use | If a caller is refused with: ``` tier 'dde-auth' may not call the API ``` then `api.tiers` does not contain `dde-auth`. That is the whole meaning of the message. ## One agent is one trust boundary Everything sealed on one agent shares that agent's permissions. A caller admitted to reach one route can reach them all. Per-route gating exists but is currently **advisory** — it records the decision and allows the call. > **Where two services must not share callers, give them separate agents with separate identities.** > Sharing one identity also means a caller cannot tell which service answered. ## Letting another agent call it **Two rules, one on each side.** They are not the same rule, and putting both on one agent is the usual mistake: ```bash # on the SERVING agent - "this caller may reach me" ./hexaeight-agent-linux-x64 hexaeight-agent.json \ --add-rule ',,inbound,allow' # on the CALLING agent - "I may call out to that peer" ./hexaeight-agent-linux-x64 hexaeight-agent.json \ --add-rule '*,,outbound,allow' ``` The calling side uses `*` as the principal because the sender is `engine:`, not the agent's own name — see [Trust and permission](/docs/concepts/trust/). > **Why the agent binary here, when everything else is `hexaeight-activate`?** Policy is sealed > under the agent's own key, so only the agent can write it. `hexaeight-activate add-policy` writes > the baseline set; `--add-rule` adds one specific row. Same store, two front ends — see the > [settings reference](/docs/reference/settings/). On the calling agent, add a pointer so its model knows the service exists — see [Documents it can search](/docs/extend/documents/), which uses the same pointer mechanism. ### What the call looks like from the other side The caller never sees your host or port. It asks **by name**, and its agent does the rest: ``` memory_search("weather", "what is it doing in London") ``` That reaches your agent over an encrypted channel, arrives at your sealed route, and is handed to your service as the plain HTTP request it already understands: ```json POST /weather { "query": "what is it doing in London" } ``` Your service answers in the contract shape, and the caller gets the `results` array. ## What you have now A service that was a port and a key is now a **name**, reachable only by principals you admitted, over a channel nothing in the middle can read. Rotating the upstream key is a local edit. Revoking a caller is one policy line. Nothing was rewritten to get there. ------------------------------------------------------------------------------ PAGE: Bring your own engine URL: /docs/extend/own-engine/ ABOUT: The agent supplies identity, encryption, sessions and policy. You supply a process it can run — any language, because the contract is argv in and JSON out. ------------------------------------------------------------------------------ Everything so far used the engine that ships with the agent. This page is the other path: **your own code behind the same identity and policy boundary**. There is no SDK and no library to link against. An engine is a **process the agent runs**, which is why it can be written in anything. > **Your code stays yours, in your environment.** Nothing is packaged into the agent, and nothing of > ours is imported into your project — you keep your own dependencies, your own versions and your > own release cycle. The agent starts a process and reads its output; that is the entire coupling. ## The contract The agent starts your process with an argument list it builds, and reads the reply out of the JSON your process writes to stdout. You declare both halves when you seal it: | field | what it is | |---|---| | `file` | your executable | | `argsNew` | the argv for a **new** conversation | | `argsResume` | the argv for **continuing** one | | `replyField` | which field of your JSON output holds the reply | | `sessionIdField` | which field carries the session id | | `nativeSession` | `true` if your engine tracks its own sessions; the agent then passes the id back to you | | `workdir` | where the process runs | Two placeholders are substituted into the argv before your process is started: ``` {message} what the caller said {sessionId} the conversation this belongs to ``` A real entry, from a working agent: ```json { "type": "process", "file": "/home/you/my-engine.sh", "argsNew": ["-p", "{message}", "--output-format", "stream-json"], "argsResume": ["-p", "--resume", "{sessionId}", "{message}", "--output-format", "stream-json"], "replyField": "result", "sessionIdField": "session_id", "nativeSession": true, "workdir": "/home/you/work" } ``` So the whole of your obligation is: **be startable with those arguments, and print JSON containing the fields you named.** Everything else — proving who is calling, deciding whether they are allowed, encrypting both directions, keeping the session — is the agent's, and already done by the time your code runs. | the agent supplies | you supply | |---|---| | identity, and proof of the caller's | the work | | encryption, both directions | | | sessions, and the id that threads them | | | policy: who may call, and what they may reach | | ## When to write one | | | |---|---| | **You already have the logic** | a service, a framework, an internal tool — put it behind an identity without rewriting it | | **You need a language we do not ship** | it is a process, so the language is yours | | **You want your own loop** | your own tools, your own model calls, your own control flow | If you only want to expose an existing **HTTP** service to other agents, you do not need this page — [An API you already run](/docs/extend/api/) is shorter and seals a named route instead. > **This is not theoretical, and you may not need to start from nothing.** Ten agent frameworks run > end to end this way with no code changes — CrewAI, AutoGen, LangGraph, LlamaIndex and the rest, > each keeping its own native session mechanism. Each comes with a working runner you can put behind > an agent and then replace with your own. See > [Your framework already works](/docs/extend/frameworks/). > **Or keep the harness as the engine and seal your code into a mission.** A mission card can run one > approved command — your runner, pinned to its sha256 — and a caller can change the question but never > the method. That is the stronger shape when outsiders will call it; see > [As a sealed mission](/docs/extend/frameworks/#as-a-sealed-mission). ## Sealing it The entry is stored under the agent's own key, so it goes in through the CLI: ```bash cd ~/heia-agent hexaeight-activate engine --add \ --name my-engine \ --model "|" \ --router "|http://127.0.0.1:5100" \ --file /home/you/my-engine.sh ``` An engine that does its own work and never calls a model still takes `--model` and `--router`, because the sealed entry has one shape. Point it at any route; it will not be used. ### Writing the full entry For anything beyond the defaults — your own `argsNew`, a different `replyField` — write the object and seal it directly: ```bash ./hexaeight-agent-linux-x64 add-engine --name my-engine \ --router "|http://127.0.0.1:5100" \ --json @./entry.json ``` `add-engine` seals the object **verbatim**, so anything you did not change survives byte for byte. ## Wrappers `file` is often a small **wrapper script** rather than the engine itself. A wrapper sits in front of your process and shapes the turn before it runs — runner provisioning uses one to impose a single procedure and strip anything a caller sends that tries to choose another. Two rules if you write one: - It receives the argv the agent built, and must **exec the real engine with everything it did not deliberately change**. - It must live **outside the agent's folder**. Every turn runs with that folder masked, so a script kept inside it does not exist as far as the spawned process is concerned. ## What your process runs inside - the identity folder is **masked** — your code cannot read `env-file`, even though it runs as the agent - shell access follows the exec policy; a sealed procedure with no cmdset cannot run commands at all - **stdout is the reply channel.** Keep diagnostics on stderr, or they become part of the answer ## Checking it is sealed ``` [hexaeight-agent] engines: SEALED store (N engine(s)) [hexaeight-agent] engine 'my-engine' -> process ``` `-> process` is your engine. Sealed to one procedure, you get the stronger line instead: ``` [hexaeight-agent] engine 'my-engine' runs ONE mission (sealed): My_Workflow ``` ## Changing one field later Export the sealed entry as plaintext, edit one field, re-seal: ```bash ./hexaeight-agent-linux-x64 export --plaintext --out ./dump.json # edit, then: ./hexaeight-agent-linux-x64 add-engine --name my-engine --router "" --json @./entry.json ``` > **Pass `--file` again on a re-seal** if the entry had a wrapper. Omitting it unbinds the wrapper > silently: no error, and the turn returns in a second or two with no work done. > **The export is plaintext** and contains everything sealed in the entry, including any headers. > Write it somewhere you control and remove it afterwards. ------------------------------------------------------------------------------ PAGE: Frameworks URL: /docs/extend/frameworks/ ABOUT: Ten agent frameworks, verified end to end through the Identity Agent with zero code changes to any of them. ------------------------------------------------------------------------------ Your framework already works — and not because we wrote an integration for it. **An engine is a process, not a library binding.** Nothing in your framework imports anything of ours, so if it can take a message and return a reply, it already works: any language, any framework, or an agent loop you wrote yourself. The table below is what has been run end to end with zero code changes. It is evidence, not a supported-list. > **None of this ships inside the agent, deliberately.** There is no bundled CrewAI, no vendored > LangGraph, no plugin to keep in step with someone else's releases. **You install your framework > the way you already do**, in your own environment, at whatever version you want — and the runner > below is a file you own and can change. The agent only ever starts a process. > > That is also why this list can never be out of date in the way an integration list would be: a > framework released tomorrow works the same day, without us shipping anything. ## Who does what | HexaEight does | Your framework does | |---|---| | who is calling, and whether they may (identity, policy, vouch) | the crew, graph or team | | encryption in both directions | its tools and its reasoning loop | | the model route for each turn — no provider key in your code | its own conversation memory, keyed on the session id it is handed | | which command may run — approved once, pinned to the file's sha256 | everything else | | every call it makes to a memory or another agent's API — through the turn's ticket, policy-checked | | ## Two ways to run one | | **As a sealed mission** (recommended) | **As a process engine** | |---|---|---| | what is sealed | a mission whose card runs ONE approved command | the framework's process as the engine itself | | what a caller can change | the question — never the method | the question | | tamper-evidence | the runner file is sha-pinned: edit one byte and it will not run until re-approved | the engine entry is sealed | | reaches memories and APIs | yes — the turn's ticket is handed to the process | through its own tools | | verified with | **CrewAI, LangGraph, Pydantic AI, Agno** — one command each, below | all ten below | ### As a sealed mission Every framework runs as the **same mission** — a [direct mission](/docs/concepts/missions/#the-two-kinds) with one card — and only the `runner.py` inside it differs: ``` runmission engine ── ONE mission: _v1_Runner card ask-runner mode: direct — every message, greetings included; no model step in the harness 1. write the message to question.txt (the message never reaches a shell) 2. run python3 runner.py --question-file question.txt ← approved, pinned to runner.py's sha256 └─ your framework, as its own OS process 3. reply with what it printed, unchanged ``` The harness makes no model call of its own here: it hands the message over and returns what comes back. The runner's `Answered by ` line is **the runner's own statement** — HexaEight renders the text as it is and vouches for nothing inside it; its guarantee is that the approved, sha-pinned `runner.py` is what ran. The runner travels **inside the mission**, and each turn gets a fresh copy. **One command sets it up**, from your agent's folder: ```bash hexaeight-activate enable crewai # or langgraph, pydanticai, agno hexaeight-activate enable langgraph --venv ~/my-env # use an environment you already have ``` It creates a pinned environment under `~/.heia/frameworks//` (or, with `--venv`, checks that yours imports the framework and uses it, installing nothing into it); downloads the mission bundle from its release and verifies its sha256; installs the mission and builds its index on your machine; and has your agent seal the one command. Then choose `runmission` and the mission in the workspace. Requires agent r30, harness engine r41 and Activate 1.0.68 or later, and Python 3.10–3.13 (or [uv](https://docs.astral.sh/uv/), which supplies one). | framework | mission | the framework half of `runner.py` | |---|---|---| | [CrewAI](/docs/extend/frameworks/crewai/) | `CrewAI_v1_Runner` | one `Agent`, one `Task` carrying the conversation, a sequential `Crew`; model via CrewAI's `LLM` (LiteLLM) | | [LangGraph](/docs/extend/frameworks/langgraph/) | `LangGraph_v1_Runner` | a prebuilt ReAct graph over the tools; model via `ChatAnthropic` | | [Pydantic AI](/docs/extend/frameworks/pydanticai/) | `PydanticAI_v1_Runner` | an `Agent` with native message history; model via `AnthropicModel` | | [Agno](/docs/extend/frameworks/agno/) | `Agno_v1_Runner` | an `Agent`; the reply is its final assistant message only | | [AutoGen](/docs/extend/frameworks/autogen/), [Google ADK](/docs/extend/frameworks/googleadk/), [LlamaIndex](/docs/extend/frameworks/llamaindex/), [OpenAI Agents SDK](/docs/extend/frameworks/openai-agents/), [Semantic Kernel](/docs/extend/frameworks/semantickernel/), [smolagents](/docs/extend/frameworks/smolagents/), Hermes Agent | **coming soon** | each runs today as a process engine, below | Each `runner.py` is **one self-contained file** — only the file the command names is pinned — with two halves: the **HexaEight half**, identical in every runner (the turn's ticket, `service_call`, memory search, `who_am_i`, the session transcript, and printing only the answer), and the **framework half**, `run(question, session_id)`, which is yours to change. To run your own version, duplicate the mission, put your `runner.py` in it, and seal it; `enable` always installs the published one and never overwrites a mission that differs from it unless you pass `--force`. The complete examples are in [`integration_examples`](https://github.com/HexaEightTeam/hbia-agent/tree/main/integration_examples). ### Serving it to other people and systems The steps above put the framework behind **your** workspace. To let a backend or another agent call it, give it a [runner](/docs/extend/external-callers/) — a second agent sealed to this one mission: ```bash hexaeight-activate add-runner --from ~/hbia-agent --dir ~/runner-crewai \ --mission CrewAI_v1_Runner --owner you@example.com --license personal --model "" cd ~/runner-crewai hexaeight-activate enable crewai # into THIS runner's own store hexaeight-activate runner-memory --share weather --share bbc-news hexaeight-activate restart agent # stops and starts only this folder's agent ``` **A runner sees only what you export into it** — its mission, and nothing else, until `runner-memory --share ` exports a served memory's pointer or links (or, with `--copy`, copies) a local memory. **Choose its model deliberately:** the framework needs one that really calls tools — measured on one route, a model answered weather and "who am I" by inventing a tool result instead of calling the tool. Check the runner's `-run.log` for one `[tool]` line per call. **The whole path, step by step** — including giving it your documents and APIs as memories, letting a caller in, and checking each answer really used its tools — is the [Quick start: a framework for outside callers](/docs/extend/framework-quickstart/). ### As a process engine The shape here is **a runner agent, with the framework's runner sealed as its engine.** You then replace the sample with your own crew, graph or team. ``` a runner agent ──► the framework's runner as its engine ──► answers turns │ you replace the sample with your own work ``` You do this **by hand**: provision a runner, put the file below where its engine points, seal it. Every step is on [Bring your own engine](/docs/extend/own-engine/). (For the sealed-mission shape, CrewAI, LangGraph, Pydantic AI and Agno each have the one-step `enable` above.) The code on each page below is **that starting point** — a working agent on the first turn, and a file you own. Gut it: swap the crew, change the tools, point it at your own data. The agent does not care what the process does, only that it starts and answers. | Framework | Time | Session persistence | |---|---|---| | [CrewAI](/docs/extend/frameworks/crewai/) | 24s | wrapper-owned transcript | | [AutoGen](/docs/extend/frameworks/autogen/) | 5s | `save_state()` / `load_state()` blob | | [Agno](/docs/extend/frameworks/agno/) | 9s | native `SqliteDb` | | [Google ADK](/docs/extend/frameworks/googleadk/) | 4s | native `DatabaseSessionService` | | [LangGraph](/docs/extend/frameworks/langgraph/) | 6s | native `SqliteSaver` checkpointer | | [LlamaIndex](/docs/extend/frameworks/llamaindex/) | 7s | `Context` serialize / restore | | [OpenAI Agents SDK](/docs/extend/frameworks/openai-agents/) | 6s | native `SQLiteSession` | | [Pydantic AI](/docs/extend/frameworks/pydanticai/) | 4s | `message_history` round-trip | | [Semantic Kernel](/docs/extend/frameworks/semantickernel/) | 6s | `ChatHistory` serialize / restore | | [smolagents](/docs/extend/frameworks/smolagents/) | 5s | wrapper-owned transcript | Times are one cold call each, all the way through: encrypted message → `/external/incoming` → engine proxy → adapter → runner. **None of these frameworks has a HexaEight dependency.** An [engine](/docs/extend/own-engine/) is a process rather than a library binding, so the framework never imports anything of ours. ## Pick your resume strategy first > **From here down is the process-engine shape** — writing your own runner as the engine itself. The > sealed-mission runners above already do all of it for you: they receive the route as > `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_MODEL` and keep their transcript keyed on the > session id. The process-engine adapter below injects `OPENAI_*` instead. Every integration is the same three pieces. What actually differs between frameworks is **how a conversation survives between turns** — because every turn is a separate process, in-memory state is gone by design and the framework has to rehydrate from disk. ### 1 · Native session store *Agno, Google ADK, LangGraph, OpenAI Agents SDK* The framework owns persistence. You hand it the session id and it does the rest. ```python agent = Agent(..., db=SqliteDb(db_file=DB), session_id=sid, add_history_to_context=True) return str(agent.run(message).content) ``` Least code, least to get wrong. **Prefer this when the framework offers it.** ### 2 · Serialize and restore a state blob *AutoGen, LlamaIndex, Semantic Kernel, Pydantic AI* The framework hands you an opaque blob; you write it out and read it back, keyed on the session id. ```python if f.exists(): await agent.load_state(json.loads(f.read_text())) result = await agent.run(task=message) f.write_text(json.dumps(await agent.save_state())) ``` Full fidelity — tool calls and intermediate steps survive, not just the final text. ### 3 · Wrapper-owned transcript *CrewAI, smolagents* No native session concept, so you keep the transcript yourself and replay it into the prompt. ```python history = "\n".join(f'{t["role"]}: {t["content"]}' for t in transcript) desc = f"Conversation so far:\n{history}\n\nNew message: {message}" ``` Simplest to reason about, and the one that loses fidelity: the model sees text rather than structured turns, and long conversations eventually need trimming. ## One helper, every framework No framework has a HexaEight dependency. Each one reads the route that was injected for this spawn: ```python def load(): if os.environ.get("OPENAI_BASE_URL"): # injected for this spawn return {"base_url": os.environ["OPENAI_BASE_URL"], "api_key": os.environ.get("OPENAI_API_KEY", ""), "model": os.environ.get("OPENAI_MODEL", "")} return { ... } # your own fallback when running standalone ``` **Env-first, and per-process.** Injection happens per spawn, so nothing is shared and there is no rewrite race. The key is a per-turn nonce that dies with the turn — **your provider key never appears in your code, your config, or your repository.** The fallback branch is what lets the same runner execute standalone during development, which is also the first thing to try when a turn misbehaves. ## Tools All ten bind tools through their own native API — `@tool`, `tools=[...]`, `@function_tool`, `@kernel_function`, `FunctionTool.from_defaults`. The agent does not mediate them, so a tool call is ordinary framework behaviour, and every model hop in a reason → tool → answer loop routes through the proxy. Tool *implementations* stay outside the framework files, so the same three functions serve all ten: ```python import hetool def get_working_folder() -> str: return hetool.get_working_folder() def list_files(path: str = ".") -> str: return hetool.list_files(path) def run_shell(command: str) -> str: return hetool.run_shell(command) ``` ## What a framework can reach - **The model** — through the route injected for the turn. No provider key in your code. - **Memories and other agents' APIs** — as a sealed mission, the turn's ticket is handed to your process (`HEIA_MCP_CONFIG`); a call to `service_call` over it reaches a served memory or a sealed API route, and the agent checks its policy on every call. A local memory is searched with the harness binary's `--memory-search`. - **Other agents, conversationally.** Every runner has the `connect-to-agent` memory built in: `memory_search("connect-to-agent", " ")` asks that agent and returns its answer. A runner is always answering someone else, so by default it **does not relay** — it says so instead. See [Two agents talking to each other](/docs/extend/agents-talking/#no-relay-by-default). > **The approval covers the launch, not what your process starts afterwards.** A command your Python > code runs itself is not approved separately. Keep runners free of shell tools, and review the file > before you approve it — the approval pins exactly what you reviewed. ## Debugging Turn the adapter's own trace on — it captures the OpenAI SDK request and response logging too: ```bash HEIA_DIAG=1 # -> /tmp/adapter_diag.log ``` Then, in order: 1. **Run the runner standalone**, pointed straight at a provider. If it fails there, it is your code. 2. **Check the router log**, not the client's error. On this path clients invent their reasons — `Connection error`, `Error in generating model output` — and debugging those inventions as if they were true is expensive. 3. **Only then suspect the framework.** In the first run of these ten, two apparent framework failures turned out to be one poisoned session in the transport underneath. Both frameworks were fine. ## Adopt, do not depend Copy the runner and adapter patterns into your own project. They are editable Python; shipping them as product code would imply a guarantee that cannot be made. **The contract is what is stable** — satisfy it with code you own. ## Next - [Write an engine](/docs/extend/own-engine/) — the contract these all satisfy - [Installing](/docs/start/install/) — get one running first - [LLM Router](/docs/router/own/) — where the injected route points ------------------------------------------------------------------------------ PAGE: Quick start — a framework for outside callers URL: /docs/extend/framework-quickstart/ ABOUT: Stand up CrewAI, LangGraph, Pydantic AI or Agno behind a HexaEight runner that other software can call — reaching your documents and APIs only through the memories you share, and nothing else. ------------------------------------------------------------------------------ From nothing to another system calling your framework, in eight steps. The framework does the work; HexaEight decides who may ask, what model it uses, which command may run, and **exactly what it can reach**. > **The one idea to hold on to:** a runner reaches **only the memories you share into it**. Your > documents are shared as local memories; your APIs are shared as served memories. There is no other > door — no workspace memories, no files, no shell. ## Before you start - A working agent (the [install](/docs/start/install/)), with **agent r30, harness engine r41 and Activate 1.0.68** or later: `hexaeight-activate verify-env`. - A router route whose model **makes real tool calls**. Measured: one route's model answered "what is the weather" by inventing a tool result; another called the tool every time. You will check this in step 7. - Python 3.10–3.13, or [uv](https://docs.astral.sh/uv/) (it fetches one). The examples use CrewAI; `langgraph`, `pydanticai` and `agno` work the same way. Folder names follow the [install](/docs/start/install/): `~/hbia-agent` is the **licence folder** (your identity files), `~/heia-agent` is **your agent's folder** — use yours if they differ. ## 1 · Try it in your own workspace ```bash cd ~/heia-agent # your agent's folder hexaeight-activate enable crewai ``` In the workspace choose `runmission` → `CrewAI_v1_Runner` and say hello. The answer is headed `Answered by CrewAI`. This is the same mission the runner will serve — see [What a mission is](/docs/concepts/missions/). ## 2 · Create the runner A **runner** is a second agent, sealed to one mission, that serves outside callers: ```bash hexaeight-activate add-runner --from ~/hbia-agent --dir ~/runner-crewai \ --mission CrewAI_v1_Runner --owner you@example.com --license personal \ --model "" ``` `--from` supplies the identity only (hardlinked, never copied). The runner gets its own ports, policy, store and working folders. ## 3 · Put the framework into the runner ```bash cd ~/runner-crewai hexaeight-activate enable crewai ``` Run inside the runner's folder, `enable` installs the mission into **the runner's own store** and seals its one command there (`this folder is a runner: its own harness root`). ## 4 · Give it information — documents, as memories The runner sees **only its mission** until you share something: ```bash hexaeight-activate runner-memory --list hexaeight-activate runner-memory --share Product-Handbook # linked: no copy hexaeight-activate runner-memory --share Product-Handbook --copy # or a self-contained copy ``` A local memory is one you built in the workspace from your documents ([Documents it can search](/docs/extend/documents/)). Linked, the runner searches the same index and sees updates; copied, it keeps its own. ## 5 · Give it APIs — also as memories An API reaches a runner the same way: as a **served memory** — a name that stands for a sealed route on another agent. 1. **Seal the API** on the agent that runs it — [An API you already run](/docs/extend/api/): ```bash cd ~/api-agent && hexaeight-activate add-api --name weather --port 38490 ``` 2. **Point a memory at it.** `add-api` prints the pointer's exact fields. Add it as a served memory in the workspace — that writes `~/.hexaeight-harness/memories/weather/remote.json` — or save those fields yourself to that path ([what a pointer holds](/docs/extend/documents/#documents-another-agent-serves)). 3. **Share it with the runner** — this copies that pointer into the runner's store: ```bash cd ~/runner-crewai && hexaeight-activate runner-memory --share weather ``` 4. **Let the runner call that agent, and that agent accept the runner** — one rule on each side ([the two rules](/docs/extend/api/#letting-another-agent-call-it)); `add-runner --peer ` or `modify-agent --dir ~/runner-crewai --peer ` writes the runner's side. Every call then goes through `service_call`, over the turn's ticket, under the runner's policy. The framework never sees a host, a port or a key. **Other agents need no memory of their own.** The runner has `connect-to-agent` built in — `memory_search("connect-to-agent", " ")`. Because a runner always answers someone else, it will not ask a third agent for them unless you switch relay on ([No relay by default](/docs/extend/agents-talking/#no-relay-by-default)). ## 6 · Start it ```bash cd ~/runner-crewai && hexaeight-activate restart agent ``` This stops and starts **only** the agent in this folder, and gives the runner its own store. Its `agent.log` must show: ``` [hexaeight-agent] engine 'missionrun-external' runs ONE mission (sealed): CrewAI_v1_Runner [licence] … policy rule(s) in force … [mcp-external] OPENED BY CONFIG (external.allowTools): service_call,who_am_i ``` ## 7 · Let a caller in, and call it A caller is a backend acting for a person. Three stores must name that person as `sha512(email)` — the runner's vouch and inbound rule, and the router's policy. The exact commands are in [Other software calling it](/docs/extend/external-callers/#what-provisioning-does-not-do-for-you). The call, from **the caller's own folder** (any folder holding an identity): ```bash cd ~/caller # the caller's identity folder set -a; . ./env-file; set +a # the caller's identity export HEIA_DIR=~/caller-heia # its OWN store — never the runner's, or the door answers your question back to you export HEIA_ASK_TIMEOUT_SECONDS=0 # wait for the work; the runner bounds its own turn SUB=$(printf 'person@example.com' | sha512sum | cut -d' ' -f1) printf '{"ask":"What is the weather in Chennai?","on_behalf_of":"%s","peer":"","peer_url":"http://127.0.0.1:","capability":"crewai"}\n' "$SUB" \ | ./hexaeight-agent-linux-x64 ask-daemon ``` `peer` is the runner's agent name (its identity), `peer_url` its port from step 2, and `capability` a label for this kind of request. Only the output line starting with `{` is the result; the answer is the `result` field of its last frame. **Check it really used the tool** — each caller session has its own folder under `~/runner-crewai-frontdoor/work/`, and the framework's log there has one line per tool call: ``` [tool] search:weather('Chennai') -> '[weatherapi.com] Current weather in Chennai … 29.9°C …' ``` An answer with no matching `[tool]` line was not fetched — change the runner's model (step 2). ## 8 · Make it yours The runner is `runner.py` inside the mission: a HexaEight half (identical in every framework) and a framework half, `run(question, session_id)`. Duplicate the mission, change the framework half, and seal your version — see [Your framework already works](/docs/extend/frameworks/#as-a-sealed-mission). ## When something is off | you see | it means | |---|---| | an answer that names a source, but no `[tool]` line in the log | the model invented it — use a model that makes real tool calls | | `nothing found in ''` | that memory is not shared into the runner — `runner-memory --share ` | | `'' is not available on the external server` | the runner's external tools do not include it — `modify-agent --allow-tools service_call,who_am_i` | | `Connection refused` | the runner is still starting — give it ~25 s after `restart agent` | | a caller can list every memory on the machine | a runner made before Activate 1.0.67 — re-create it with `add-runner` | ------------------------------------------------------------------------------ PAGE: CrewAI URL: /docs/extend/frameworks/crewai/ ABOUT: CrewAI as a sealed mission — identity, policy and approvals by HexaEight, the crew by CrewAI. Also verified as a process engine. ------------------------------------------------------------------------------ **Verified as a sealed mission 2026-09-27**, in the workspace and as a runner called from outside (BYOA) — general questions, live weather and BBC News through HexaEight-verified services, search of this machine's documents, "who am I", conversation memory across turns, and an injection probe that never reached a shell. **Verified as a process engine 2026-08-19** — PASS, 24 s. ## As a sealed mission HexaEight decides who may ask and which command may run; CrewAI does the work. It is a [direct mission](/docs/concepts/missions/#the-two-kinds) — the same one-card mission every framework uses — and the answer is CrewAI's, headed `Answered by CrewAI`. **The complete example** — runner, pinned requirements, install steps and tests — is in [`integration_examples/crewai`](https://github.com/HexaEightTeam/hbia-agent/tree/main/integration_examples/crewai); the mission bundle is the `integration-crewai-v2` release. **The mission** (`CrewAI_v1_Runner`) has one card, `ask-runner`: every message, greetings included, is written to `question.txt` and handed to the one approved command; the reply is what the crew printed, unchanged. **The one command**, identical on every run and every machine: ```bash python3 runner.py --question-file question.txt ``` - The question travels in a **file**, never on the command line — a question containing `$(…)` or quotes is only ever text. - The command is approved once and **pinned to `runner.py`'s sha256**. Edit the file and it will not run until it is sealed again. - `runner.py` lives **inside the mission**; every turn gets a fresh copy of the approved file. - **Installed with 1.0.66?** That was the two-card v1 mission with `crewai_heia_runner.py`. Replace it with `hexaeight-activate enable crewai --force` — the old one is kept under `~/.hexaeight-harness/backups/`. **What the runner file must do** — one self-contained file, because only the file the command names is pinned: | | | |---|---| | model | build CrewAI's `LLM` from the route the turn provides (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) — no provider key in the file | | tools | call `service_call` over the turn's ticket (`HEIA_MCP_CONFIG`) for served memories and APIs; search local memories with `hexaeight-engine --memory-search` | | conversation | keep CrewAI's transcript keyed on `HEIA_WORK_SESSION`, and replay it into the task | | output | print **only the answer**. Send CrewAI's own output to a log file at the file-descriptor level — the turn captures stdout and stderr together | | privacy | set `CREWAI_DISABLE_TELEMETRY=true`, `OTEL_SDK_DISABLED=true` and `CREWAI_TRACING_ENABLED=false` before CrewAI loads. CrewAI sends telemetry by default, and its first-run tracing prompt otherwise lands in the answer | | environment | if the `python3` that launched it has no CrewAI, re-launch itself under the CrewAI virtual environment — so the command never names a machine path | | role | a helpful general assistant that uses tools only for live data and documents. A role phrased as "answer using the tools" makes CrewAI refuse ordinary questions | **Set it up in one command**, from your agent's folder — agent r30, harness engine r41 and Activate 1.0.68 or later, and Python 3.10–3.13 (or [uv](https://docs.astral.sh/uv/), which supplies one): ```bash hexaeight-activate enable crewai hexaeight-activate enable crewai --venv ~/my-env # or use an environment you already have ``` To serve it to other people's software, run the same command inside a runner's folder — see [Serving it to other people and systems](/docs/extend/frameworks/#serving-it-to-other-people-and-systems). CrewAI reaches the model through **LiteLLM**, the library its `LLM` class uses underneath; both are pinned (`crewai==1.15.2`, `litellm==1.93.0`) because LiteLLM builds the actual request to the agent's model route. > The conversation transcript is stored unencrypted and is not trimmed; both are being addressed. **Other agents:** the runner asks another HexaEight agent a question through its built-in `connect-to-agent` memory, and reaches other agents' **API routes** through the memories that point at them — [Two agents talking to each other](/docs/extend/agents-talking/). As a runner it does not relay by default. --- ## As a process engine CrewAI has no built-in cross-process session, so the wrapper keeps the transcript and replays it into the task description each turn. ## The runner ```python import sys, os, json, pathlib sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from crewai import Agent, Task, Crew, Process, LLM from crewai.tools import tool SESS_DIR = pathlib.Path(os.path.expanduser("~/agenttests/crewai/sessions")) SESS_DIR.mkdir(parents=True, exist_ok=True) @tool("get_working_folder") def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() @tool("run_shell") def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) def load(sid): f = SESS_DIR / f"{sid}.json" return json.loads(f.read_text()) if f.exists() else [] def save(sid, transcript): (SESS_DIR / f"{sid}.json").write_text(json.dumps(transcript, indent=2)) def invoke(sid, message): transcript = load(sid) c = azcfg.load() llm = LLM(model="openai/" + c["model"], base_url=c["base_url"], api_key=c["api_key"]) agent = Agent( role="Conversational assistant", goal="Answer the user, using the prior conversation for context and tools for operational questions.", backstory="You keep track of everything said earlier in this session.", llm=llm, tools=[get_working_folder, run_shell], verbose=False, ) history = "\n".join(f'{t["role"]}: {t["content"]}' for t in transcript) desc = ( "Here is the conversation so far in this session (may be empty):\n" f"{history or '(no prior messages)'}\n\n" f"New user message: {message}\n\n" "Reply concisely to the new user message." ) task = Task(description=desc, expected_output="A concise reply.", agent=agent) crew = Crew(agents=[agent], tasks=[task], process=Process.sequential, verbose=False) reply = str(crew.kickoff()).strip() transcript.append({"role": "user", "content": message}) transcript.append({"role": "assistant", "content": reply}) save(sid, transcript) return reply ``` --- ## Engine definition ```json { "type": "process", "file": "/home/you/crewai/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/crewai_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/crewai_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your existing crew, agents and tasks as they are. 2. Wrap the kickoff in `invoke(sid, message)`. 3. Add transcript load/save keyed on `sid`, and replay it into the task description. 4. Read the route from `azcfg.load()` and build `LLM(...)` from it. 5. Seal the engine definition, point `external.engine` at it, restart. --- ## Gotchas **`model` needs the `openai/` prefix.** CrewAI's `LLM` routes on the provider prefix, so it is `model="openai/" + c["model"]`, not the bare model id. **CrewAI prints its own tracing banner to stdout.** The adapter redirects runner stdout to stderr — if you write your own adapter, do the same or the JSON envelope is unparseable. **Transcript replay is text, not structured turns.** Tool calls from earlier turns are not replayed, only the final text. For long conversations, trim or summarise the history you replay. **`verbose=False`** on both `Agent` and `Crew` keeps the output quiet; useful even with the stdout redirect in place. ------------------------------------------------------------------------------ PAGE: AutoGen URL: /docs/extend/frameworks/autogen/ ABOUT: Verified through the Identity Agent with no code changes. Session persistence by save_state / load_state blob. ------------------------------------------------------------------------------ ## As a sealed mission — coming soon AutoGen as a [direct mission](/docs/concepts/missions/#the-two-kinds) — one card, one approved command, installed with `hexaeight-activate enable` like [CrewAI, LangGraph, Pydantic AI and Agno](/docs/extend/frameworks/#as-a-sealed-mission) — is **coming soon**. Until then, AutoGen runs today as a process engine, below. --- ## As a process engine **Verified 2026-08-19 — PASS, 5s.** Session persistence: `save_state()` / `load_state()` blob. AutoGen serialises the agent's whole conversation state, so resume keeps structured turns rather than replayed text. --- ## The runner ```python import sys, os, json, asyncio, pathlib sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from autogen_agentchat.agents import AssistantAgent from autogen_ext.models.openai import OpenAIChatCompletionClient STATE_DIR = pathlib.Path(os.path.expanduser("~/agenttests/autogen/state")) STATE_DIR.mkdir(parents=True, exist_ok=True) def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) async def invoke(sid, message): c = azcfg.load() model_client = OpenAIChatCompletionClient( model=c["model"], base_url=c["base_url"], api_key=c["api_key"], model_info={"vision": False, "function_calling": True, "json_output": True, "family": "unknown", "structured_output": True}, ) agent = AssistantAgent("assistant", model_client=model_client, system_message="Be concise. Use tools for operational questions.", tools=[get_working_folder, run_shell], reflect_on_tool_use=True) f = STATE_DIR / f"{sid}.json" if f.exists(): await agent.load_state(json.loads(f.read_text())) result = await agent.run(task=message) reply = result.messages[-1].content.strip() f.write_text(json.dumps(await agent.save_state())) await model_client.close() return reply ``` Async — the adapter drives the coroutine, so `invoke` may be `async def`. --- ## Engine definition Same shape as every other framework; only `file` and the runner path change. ```json { "type": "process", "file": "/home/you/autogen/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/autogen_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/autogen_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your `AssistantAgent` and tools as they are. 2. Wrap `agent.run(...)` in `async def invoke(sid, message)`. 3. Add `load_state` / `save_state` keyed on `sid`. 4. Build `OpenAIChatCompletionClient` from `azcfg.load()`. 5. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **`model_info` is required for any non-OpenAI model.** The client cannot infer capabilities for an unknown model id and will refuse to start without it. `function_calling: True` is the field that matters if you bind tools. **`reflect_on_tool_use=True` or you get the raw tool output.** Without it the agent's last message is the tool result, not a composed answer — so `result.messages[-1].content` is JSON rather than prose. **Close the client.** `await model_client.close()` before returning, or the process can hang with the connection pool open — which surfaces as a turn that never completes. **Plain callables are fine as tools.** No decorator needed; AutoGen introspects the signature and docstring, so write a real docstring — it becomes the tool description the model sees. ------------------------------------------------------------------------------ PAGE: Agno URL: /docs/extend/frameworks/agno/ ABOUT: Agno as a sealed mission — identity, policy and approvals by HexaEight, the agent by Agno. Also verified as a process engine. ------------------------------------------------------------------------------ **Verified as a sealed mission 2026-09-27** — general questions, live weather and BBC News through HexaEight-verified services, search of this machine's documents, "who am I", and conversation memory across turns. ## As a sealed mission HexaEight decides who may ask and which command may run; Agno does the work. It is a [direct mission](/docs/concepts/missions/#the-two-kinds) — the same one-card mission every framework uses — and the answer is Agno's, headed `Answered by Agno`. ```bash hexaeight-activate enable agno # from your agent's folder hexaeight-activate enable agno --venv ~/my-env # or use an environment you already have ``` Then choose `runmission` → `Agno_v1_Runner` in the workspace. Requires agent r30, harness engine r41 and Activate 1.0.68 or later, and Python 3.10–3.13 (or [uv](https://docs.astral.sh/uv/)). The mission bundle is the `integration-agno-v1` release; the runner, pinned requirements and install-by-hand steps are in [`integration_examples/agno`](https://github.com/HexaEightTeam/hbia-agent/tree/main/integration_examples/agno). | | | |---|---| | the one command | `python3 runner.py --question-file question.txt` — pinned to `runner.py`'s sha256 | | the Agno half | an `Agent` with the tools as plain functions | | model | Agno's `Claude` on the turn's route, authenticated with the turn's token — no provider key in the file | | pinned | `agno==3.0.11`, `anthropic==1.8.0` | | its own output | to `agno-run.log` in the turn's folder, with one `[tool]` line per tool call | The reply is Agno's **final** assistant message only. Its `content` also carries text the model wrote before a tool call ("Let me check…"), which is working, not the answer. To serve it to other people's software, run the same `enable` inside a runner's folder — see [Serving it to other people and systems](/docs/extend/frameworks/#serving-it-to-other-people-and-systems). --- ## As a process engine **Verified 2026-08-19 — PASS, 9s.** Session persistence: native `SqliteDb`. The shortest integration of the ten. Agno owns persistence entirely — hand it a `session_id` and it rehydrates history itself. --- ## The runner ```python import sys, os sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.db.sqlite import SqliteDb DB = os.path.expanduser("~/agenttests/agno/agno.db") def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) def invoke(sid, message): c = azcfg.load() agent = Agent( model=OpenAIChat(id=c["model"], base_url=c["base_url"], api_key=c["api_key"]), db=SqliteDb(db_file=DB), session_id=sid, add_history_to_context=True, tools=[get_working_folder, run_shell], instructions="Be concise. Use tools for operational questions.", ) return str(agent.run(message).content).strip() ``` That is the entire runner — no load, no save, no transcript handling. --- ## Engine definition ```json { "type": "process", "file": "/home/you/agno/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/agno_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/agno_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your agent definition as it is. 2. Pass HBIA's `sid` straight through as Agno's `session_id`. 3. Add `db=SqliteDb(...)` and `add_history_to_context=True`. 4. Build `OpenAIChat` from `azcfg.load()`. 5. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **`add_history_to_context=True` is not the default.** Without it Agno stores the session but does not feed prior turns to the model — persistence that looks like it works and produces an agent with no memory. This is the single most likely thing to get wrong here. **`OpenAIChat(id=...)`, not `model=...`.** The keyword is `id`. **One SQLite file, many sessions.** Keyed by `session_id`, so a swarm sharing a filesystem shares history correctly — but SQLite over NFS is a known hazard. Keep the db on local disk. **Plain callables as tools**, with real docstrings — Agno reads the signature and docstring. ------------------------------------------------------------------------------ PAGE: Google ADK URL: /docs/extend/frameworks/googleadk/ ABOUT: Verified through the Identity Agent with no code changes. Native DatabaseSessionService persistence. ------------------------------------------------------------------------------ ## As a sealed mission — coming soon Google ADK as a [direct mission](/docs/concepts/missions/#the-two-kinds) — one card, one approved command, installed with `hexaeight-activate enable` like [CrewAI, LangGraph, Pydantic AI and Agno](/docs/extend/frameworks/#as-a-sealed-mission) — is **coming soon**. Until then, Google ADK runs today as a process engine, below. --- ## As a process engine **Verified 2026-08-19 — PASS, 4s.** Session persistence: native `DatabaseSessionService`. ADK reaches the route through LiteLLM, which is the one thing that makes this integration different from the rest. --- ## The runner ```python import sys, os, asyncio sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from google.adk.agents import LlmAgent from google.adk.runners import Runner from google.adk.sessions import DatabaseSessionService from google.adk.models.lite_llm import LiteLlm from google.genai import types DB = "sqlite+aiosqlite:///" + os.path.expanduser("~/agenttests/googleadk/sessions.db") APP, USER = "hexa", "u1" def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) async def invoke(sid, message): c = azcfg.load() # LiteLlm's openai/ route reads OPENAI_API_BASE / OPENAI_API_KEY from the # ENVIRONMENT, not from constructor arguments. Feed it the injected proxy endpoint # so the call routes through HBIA. os.environ["OPENAI_API_KEY"] = c["api_key"] os.environ["OPENAI_API_BASE"] = c["base_url"] agent = LlmAgent(name="assistant", model=LiteLlm(model="openai/" + c["model"]), instruction="Be concise. Use tools for operational questions.", tools=[get_working_folder, run_shell]) svc = DatabaseSessionService(db_url=DB) sess = await svc.get_session(app_name=APP, user_id=USER, session_id=sid) if sess is None: sess = await svc.create_session(app_name=APP, user_id=USER, session_id=sid) runner = Runner(agent=agent, app_name=APP, session_service=svc) content = types.Content(role="user", parts=[types.Part(text=message)]) reply = "" async for ev in runner.run_async(user_id=USER, session_id=sid, new_message=content): if ev.is_final_response() and ev.content and ev.content.parts: reply = ev.content.parts[0].text return (reply or "").strip() ``` --- ## Engine definition ```json { "type": "process", "file": "/home/you/googleadk/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/googleadk_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/googleadk_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your `LlmAgent` and tools as they are. 2. Set `OPENAI_API_BASE` / `OPENAI_API_KEY` from `azcfg.load()` **before** constructing `LiteLlm`. 3. Use `DatabaseSessionService` with HBIA's `sid` as the ADK `session_id`. 4. Get-or-create the session — `get_session` returns `None` on the first turn. 5. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **LiteLLM reads the endpoint from the environment, not from arguments.** This is the trap. Passing a base URL to the constructor silently does nothing; LiteLLM picks up `OPENAI_API_BASE` and `OPENAI_API_KEY` from `os.environ`. Get this wrong and the agent works perfectly while **bypassing the proxy entirely** — calling the provider directly with whatever key it found, so the turn succeeds and nothing is metered or gated. An earlier version of this runner did exactly that. Note the variable is `OPENAI_API_BASE` (LiteLLM's name), while HBIA injects `OPENAI_BASE_URL` — hence the explicit copy. **`get_session` returns `None` for an unknown id**, it does not create one. Create explicitly, or the runner throws on the first turn of every conversation. **Async DB URL.** `sqlite+aiosqlite:///` — the sync `sqlite:///` driver will not work with `DatabaseSessionService`. **Iterate to the final event.** `run_async` yields a stream; only `ev.is_final_response()` carries the answer. Taking the first event gives you a partial or a tool call. ------------------------------------------------------------------------------ PAGE: LangGraph URL: /docs/extend/frameworks/langgraph/ ABOUT: LangGraph as a sealed mission — identity, policy and approvals by HexaEight, the agent by LangGraph. Also verified as a process engine. ------------------------------------------------------------------------------ **Verified as a sealed mission 2026-09-27** — general questions, live weather and BBC News through HexaEight-verified services, search of this machine's documents, "who am I", and conversation memory across turns. ## As a sealed mission HexaEight decides who may ask and which command may run; LangGraph does the work. It is a [direct mission](/docs/concepts/missions/#the-two-kinds) — the same one-card mission every framework uses — and the answer is LangGraph's, headed `Answered by LangGraph`. ```bash hexaeight-activate enable langgraph # from your agent's folder hexaeight-activate enable langgraph --venv ~/my-env # or use an environment you already have ``` Then choose `runmission` → `LangGraph_v1_Runner` in the workspace. Requires agent r30, harness engine r41 and Activate 1.0.68 or later, and Python 3.10–3.13 (or [uv](https://docs.astral.sh/uv/)). The mission bundle is the `integration-langgraph-v1` release; the runner, pinned requirements and install-by-hand steps are in [`integration_examples/langgraph`](https://github.com/HexaEightTeam/hbia-agent/tree/main/integration_examples/langgraph). | | | |---|---| | the one command | `python3 runner.py --question-file question.txt` — pinned to `runner.py`'s sha256 | | the LangGraph half | a prebuilt ReAct graph (`create_react_agent`) over the tools, with the conversation so far passed as messages | | model | `ChatAnthropic` on the turn's route, with the turn's token as a bearer header — no provider key in the file | | pinned | `langgraph==1.2.12`, `langchain-anthropic==1.7.4`, `anthropic==1.8.0` | | its own output | to `langgraph-run.log` in the turn's folder, with one `[tool]` line per tool call | Live weather and news are asked for fresh on every turn. Measured: in a long session LangGraph's model repeated headlines from earlier in the conversation instead of calling the tool; the runner's instructions now forbid that, and its log shows one `[tool]` line per real call. To serve it to other people's software, run the same `enable` inside a runner's folder — see [Serving it to other people and systems](/docs/extend/frameworks/#serving-it-to-other-people-and-systems). --- ## As a process engine **Verified 2026-08-19 — PASS, 6s.** Session persistence: native `SqliteSaver` checkpointer. LangGraph's checkpointer rehydrates graph state from disk, so there is no transcript to manage. The session id is the `thread_id`. > **Licence:** use the **`langgraph` library** only. **`langgraph-api` / LangGraph Platform is Elastic > Licence 2.0**, which prohibits offering it as a hosted service — do not pull it into a product you > deploy for others. The library itself is MIT. --- ## The runner ```python import sys, os sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.prebuilt import create_react_agent from langgraph.checkpoint.sqlite import SqliteSaver DB = os.path.expanduser("~/agenttests/langgraph/checkpoints.sqlite") c = azcfg.load() llm = ChatOpenAI(model=c["model"], base_url=c["base_url"], api_key=c["api_key"], temperature=0) @tool def get_working_folder() -> str: """Return the agent's current working folder (absolute path). Takes no arguments.""" return hetool.get_working_folder() @tool def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) TOOLS = [get_working_folder, run_shell] def invoke(thread_id, message): """No local transcript — LangGraph rehydrates state from the checkpoint.""" with SqliteSaver.from_conn_string(DB) as saver: agent = create_react_agent(llm, TOOLS, checkpointer=saver) cfg = {"configurable": {"thread_id": thread_id}} result = agent.invoke({"messages": [{"role": "user", "content": message}]}, cfg) return result["messages"][-1].content.strip() ``` --- ## Engine definition ```json { "type": "process", "file": "/home/you/langgraph/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/langgraph_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/langgraph_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your graph as it is — any compiled graph works, `create_react_agent` is just the short example. 2. Pass HBIA's `sid` as the `thread_id` in `configurable`. 3. Attach a `SqliteSaver` (or any checkpointer) so state survives between processes. 4. Build `ChatOpenAI` from `azcfg.load()`. 5. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **`SqliteSaver.from_conn_string` is a context manager.** Use `with`; the connection must be open for the whole `invoke`, and closing it early gives an agent that silently forgets. **Every hop routes through the proxy.** A reason → tool → answer loop makes multiple LLM calls, all routed. Good for gating, and worth knowing when reading metering: one turn is not one call. **A tool with no arguments needs saying so.** `"Takes no arguments."` in the docstring stops models inventing a parameter and failing the call. **`temperature=0`** for deterministic testing; drop it in production if you want variety. **Build the LLM at module scope only if the route is stable.** In this runner `azcfg.load()` runs at import, which is fine because the env is injected per spawn. If you ever reuse the process across turns, move it inside `invoke`. ------------------------------------------------------------------------------ PAGE: LlamaIndex URL: /docs/extend/frameworks/llamaindex/ ABOUT: Verified through the Identity Agent with no code changes. Context serialize and restore. ------------------------------------------------------------------------------ ## As a sealed mission — coming soon LlamaIndex as a [direct mission](/docs/concepts/missions/#the-two-kinds) — one card, one approved command, installed with `hexaeight-activate enable` like [CrewAI, LangGraph, Pydantic AI and Agno](/docs/extend/frameworks/#as-a-sealed-mission) — is **coming soon**. Until then, LlamaIndex runs today as a process engine, below. --- ## As a process engine **Verified 2026-08-19 — PASS, 7s.** Session persistence: `Context` serialize / restore. The workflow `Context` is the session — serialise it to JSON on the way out, rebuild it on the way in. --- ## The runner ```python import sys, os, json, pathlib, asyncio sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from llama_index.core.agent.workflow import FunctionAgent from llama_index.core.workflow import Context, JsonSerializer from llama_index.core.tools import FunctionTool from llama_index.llms.openai_like import OpenAILike STATE = pathlib.Path(os.path.expanduser("~/agenttests/llamaindex/state")) STATE.mkdir(parents=True, exist_ok=True) def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) TOOLS = [FunctionTool.from_defaults(fn=f) for f in (get_working_folder, run_shell)] async def invoke(sid, message): c = azcfg.load() llm = OpenAILike(model=c["model"], api_base=c["base_url"], api_key=c["api_key"], context_window=131072, is_chat_model=True, is_function_calling_model=True) agent = FunctionAgent(tools=TOOLS, llm=llm, system_prompt="Be concise. Use tools for operational questions.") f = STATE / f"{sid}.json" ctx = (Context.from_dict(agent, json.loads(f.read_text()), serializer=JsonSerializer()) if f.exists() else Context(agent)) resp = await agent.run(message, ctx=ctx) f.write_text(json.dumps(ctx.to_dict(serializer=JsonSerializer()))) return str(resp).strip() ``` --- ## Engine definition ```json { "type": "process", "file": "/home/you/llamaindex/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/llamaindex_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/llamaindex_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your agent and tools as they are. 2. Serialise the `Context` keyed on `sid`; rebuild with `Context.from_dict` when the file exists. 3. Use `OpenAILike` — not `OpenAI` — built from `azcfg.load()`. 4. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **Use `OpenAILike`, not `OpenAI`.** The `OpenAI` class validates the model id against OpenAI's known models and rejects anything else. `OpenAILike` is the class for OpenAI-compatible endpoints, which is what the HBIA route is. **`is_function_calling_model=True` or tools are silently ignored.** LlamaIndex cannot infer this for an unknown model, and the default assumes no tool support — the agent then answers without ever calling a tool, which reads like a model problem rather than a config one. **`is_chat_model=True`** likewise, or the request goes to the completions shape. **Set `context_window` explicitly.** There is no way to infer it for an unknown model, and the default is small enough to truncate long sessions. **`api_base`, not `base_url`.** LlamaIndex's keyword differs from most other SDKs. ------------------------------------------------------------------------------ PAGE: OpenAI Agents SDK URL: /docs/extend/frameworks/openai-agents/ ABOUT: Verified through the Identity Agent with no code changes. Native SQLiteSession persistence. ------------------------------------------------------------------------------ ## As a sealed mission — coming soon OpenAI Agents SDK as a [direct mission](/docs/concepts/missions/#the-two-kinds) — one card, one approved command, installed with `hexaeight-activate enable` like [CrewAI, LangGraph, Pydantic AI and Agno](/docs/extend/frameworks/#as-a-sealed-mission) — is **coming soon**. Until then, OpenAI Agents SDK runs today as a process engine, below. --- ## As a process engine **Verified 2026-08-19 — PASS, 6s.** Session persistence: native `SQLiteSession`. `SQLiteSession` is keyed on the session id and works across processes, so resume needs no code of your own. --- ## The runner ```python import sys, os, asyncio sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from agents import Agent, Runner, SQLiteSession, OpenAIChatCompletionsModel, function_tool from openai import AsyncOpenAI DB = os.path.expanduser("~/agenttests/openai_agents/sessions.db") @function_tool def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() @function_tool def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) async def invoke(sid, message): c = azcfg.load() client = AsyncOpenAI(base_url=c["base_url"], api_key=c["api_key"]) agent = Agent(name="assistant", instructions="Be concise. Use tools for operational questions.", model=OpenAIChatCompletionsModel(model=c["model"], openai_client=client), tools=[get_working_folder, run_shell]) session = SQLiteSession(sid, DB) # native cross-process history keyed by sid result = await Runner.run(agent, message, session=session) return str(result.final_output).strip() ``` --- ## Engine definition ```json { "type": "process", "file": "/home/you/openai_agents/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/openai_agents_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/openai_agents_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your agent and `@function_tool` definitions as they are. 2. Pass HBIA's `sid` as the first argument to `SQLiteSession`. 3. Build an `AsyncOpenAI` client from `azcfg.load()` and wrap it in `OpenAIChatCompletionsModel`. 4. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **Use `OpenAIChatCompletionsModel`, not the default.** The SDK defaults to the **Responses API**, which an OpenAI-compatible endpoint generally does not implement. Passing the model id as a bare string gets you the Responses shape and a confusing failure; wrapping it in `OpenAIChatCompletionsModel` selects chat completions. **Pass the client, not a base URL.** The model object takes `openai_client=`, so construct `AsyncOpenAI` yourself with the injected route rather than relying on ambient env vars. **`SQLiteSession(sid, DB)`** — session id first, database path second. Reversing them creates a database named after your session. **Tracing is on by default** and tries to reach OpenAI's telemetry endpoint. In a confined spawn with no outbound access it fails harmlessly to stderr, but you can disable it (`OPENAI_AGENTS_DISABLE_TRACING=1`) to keep logs clean. ------------------------------------------------------------------------------ PAGE: Pydantic AI URL: /docs/extend/frameworks/pydanticai/ ABOUT: Pydantic AI as a sealed mission — identity, policy and approvals by HexaEight, the agent by Pydantic AI. Also verified as a process engine. ------------------------------------------------------------------------------ **Verified as a sealed mission 2026-09-27** — general questions, live weather and BBC News through HexaEight-verified services, search of this machine's documents, "who am I", and conversation memory across turns. ## As a sealed mission HexaEight decides who may ask and which command may run; Pydantic AI does the work. It is a [direct mission](/docs/concepts/missions/#the-two-kinds) — the same one-card mission every framework uses — and the answer is Pydantic AI's, headed `Answered by Pydantic AI`. ```bash hexaeight-activate enable pydanticai # from your agent's folder hexaeight-activate enable pydanticai --venv ~/my-env # or use an environment you already have ``` Then choose `runmission` → `PydanticAI_v1_Runner` in the workspace. Requires agent r30, harness engine r41 and Activate 1.0.68 or later, and Python 3.10–3.13 (or [uv](https://docs.astral.sh/uv/)). The mission bundle is the `integration-pydanticai-v1` release; the runner, pinned requirements and install-by-hand steps are in [`integration_examples/pydanticai`](https://github.com/HexaEightTeam/hbia-agent/tree/main/integration_examples/pydanticai). | | | |---|---| | the one command | `python3 runner.py --question-file question.txt` — pinned to `runner.py`'s sha256 | | the Pydantic AI half | an `Agent` with the tools as plain functions, and the conversation so far as native message history | | model | `AnthropicModel` over an `AsyncAnthropic` client on the turn's route, with the turn's token as a bearer header — no provider key in the file | | pinned | `pydantic-ai-slim[anthropic]==2.51.0`, `anthropic==1.8.0` | | its own output | to `pydanticai-run.log` in the turn's folder, with one `[tool]` line per tool call | To serve it to other people's software, run the same `enable` inside a runner's folder — see [Serving it to other people and systems](/docs/extend/frameworks/#serving-it-to-other-people-and-systems). --- ## As a process engine **Verified 2026-08-19 — PASS, 4s.** Session persistence: `message_history` round-trip. Pydantic AI exposes the full typed message list, so persistence is one adapter call each way. > This is one of the two frameworks that appeared to fail in an earlier test run. It was never a > framework fault — the transport underneath had a poisoned session. See > [sessions-and-swarm.md](/docs/concepts/architecture/). --- ## The runner ```python import sys, os, json, pathlib sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider from pydantic_ai.messages import ModelMessagesTypeAdapter SESS = pathlib.Path(os.path.expanduser("~/agenttests/pydanticai/sessions")) SESS.mkdir(parents=True, exist_ok=True) def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output.""" return hetool.run_shell(command) def invoke(sid, message): c = azcfg.load() model = OpenAIChatModel(c["model"], provider=OpenAIProvider(base_url=c["base_url"], api_key=c["api_key"])) agent = Agent(model, system_prompt="Be concise. Use tools for operational questions.", tools=[get_working_folder, run_shell]) f = SESS / f"{sid}.json" history = ModelMessagesTypeAdapter.validate_json(f.read_text()) if f.exists() else None result = agent.run_sync(message, message_history=history) f.write_bytes(ModelMessagesTypeAdapter.dump_json(result.all_messages())) return str(result.output).strip() ``` Note `run_sync` — no async needed, though `agent.run` is available if you prefer. --- ## Engine definition ```json { "type": "process", "file": "/home/you/pydanticai/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/pydanticai_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/pydanticai_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your agent, tools and result types as they are. 2. Persist `result.all_messages()` keyed on `sid`; pass it back as `message_history`. 3. Build `OpenAIChatModel` with an `OpenAIProvider` from `azcfg.load()`. 4. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **`ModelMessagesTypeAdapter` both ways — do not hand-roll JSON.** The message list is typed (tool calls, tool returns, parts), and `dump_json` / `validate_json` preserve it exactly. Serialising it yourself loses structure and breaks resume in ways that surface much later. **`dump_json` returns bytes**, hence `write_bytes` paired with `read_text` for the parse. **Provider goes through `OpenAIProvider`**, not constructor kwargs on the model. **`result.output`, not `result.data`.** The attribute was renamed; older examples on the web still use `data` and will raise. **Typed outputs still work.** If your agent declares a Pydantic result type, `result.output` is that type — stringify it however your product needs before returning, since the adapter contract expects a string. ------------------------------------------------------------------------------ PAGE: Semantic Kernel URL: /docs/extend/frameworks/semantickernel/ ABOUT: Verified through the Identity Agent with no code changes. ChatHistory serialize and restore. ------------------------------------------------------------------------------ ## As a sealed mission — coming soon Semantic Kernel as a [direct mission](/docs/concepts/missions/#the-two-kinds) — one card, one approved command, installed with `hexaeight-activate enable` like [CrewAI, LangGraph, Pydantic AI and Agno](/docs/extend/frameworks/#as-a-sealed-mission) — is **coming soon**. Until then, Semantic Kernel runs today as a process engine, below. --- ## As a process engine **Verified 2026-08-19 — PASS, 6s.** Session persistence: `ChatHistory` serialize / restore. Tools are kernel plugins, and `FunctionChoiceBehavior.Auto()` runs the call loop for you. > **.NET alternative:** Semantic Kernel is .NET-native, so a C# agent can be driven directly as a > process engine without the Python adapter. The Python path is documented here because it is what was > verified. --- ## The runner ```python import sys, os, pathlib, asyncio sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from semantic_kernel import Kernel from semantic_kernel.functions import kernel_function from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior from semantic_kernel.contents import ChatHistory from openai import AsyncOpenAI SESS = pathlib.Path(os.path.expanduser("~/agenttests/semantickernel/sessions")) SESS.mkdir(parents=True, exist_ok=True) class OsTools: @kernel_function(description="Return the agent's current working folder (absolute path).") def get_working_folder(self) -> str: return hetool.get_working_folder() @kernel_function(description="Run a shell command in the working folder and return its output.") def run_shell(self, command: str) -> str: return hetool.run_shell(command) async def invoke(sid, message): c = azcfg.load() client = AsyncOpenAI(base_url=c["base_url"], api_key=c["api_key"]) svc = OpenAIChatCompletion(ai_model_id=c["model"], async_client=client) kernel = Kernel() kernel.add_service(svc) kernel.add_plugin(OsTools(), plugin_name="os") settings = svc.instantiate_prompt_execution_settings() settings.function_choice_behavior = FunctionChoiceBehavior.Auto() f = SESS / f"{sid}.json" history = (ChatHistory.restore_chat_history(f.read_text()) if f.exists() else ChatHistory(system_message="Be concise. Use tools for operational questions.")) history.add_user_message(message) resp = await svc.get_chat_message_content(history, settings, kernel=kernel) history.add_message(resp) f.write_text(history.serialize()) return str(resp).strip() ``` --- ## Engine definition ```json { "type": "process", "file": "/home/you/semantickernel/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/semantickernel_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/semantickernel_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your kernel, plugins and prompts as they are. 2. Serialise `ChatHistory` keyed on `sid`; restore it when the file exists. 3. Build `OpenAIChatCompletion` with an `AsyncOpenAI` client from `azcfg.load()`. 4. Set `FunctionChoiceBehavior.Auto()` if you want tools invoked automatically. 5. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **`FunctionChoiceBehavior.Auto()` is required for tool calling.** Without it the plugin is registered and never used — the model has no way to invoke it, so you get an agent that describes what it would do instead of doing it. **Pass `kernel=kernel` to `get_chat_message_content`.** The service needs the kernel reference to resolve plugins; omit it and tools are invisible even with `Auto()` set. **`async_client=`, not a base URL.** Construct `AsyncOpenAI` yourself with the injected route. **The system message belongs in the `ChatHistory` constructor**, and only on first creation — a restored history already carries it. Adding it again each turn duplicates it. **Add the response back to the history before serialising**, or the assistant's turn is lost and the conversation reads as a series of unanswered user messages. ------------------------------------------------------------------------------ PAGE: smolagents URL: /docs/extend/frameworks/smolagents/ ABOUT: Verified through the Identity Agent with no code changes. Session persistence by wrapper-owned transcript. ------------------------------------------------------------------------------ ## As a sealed mission — coming soon smolagents as a [direct mission](/docs/concepts/missions/#the-two-kinds) — one card, one approved command, installed with `hexaeight-activate enable` like [CrewAI, LangGraph, Pydantic AI and Agno](/docs/extend/frameworks/#as-a-sealed-mission) — is **coming soon**. Until then, smolagents runs today as a process engine, below. --- ## As a process engine **Verified 2026-08-19 — PASS, 5s.** Session persistence: wrapper-owned transcript. smolagents' idiom is `CodeAgent`, which calls tools by **generating Python that calls them** rather than emitting structured tool calls. That choice is deliberate here and explained below. > This is one of the two frameworks that appeared to fail in an earlier test run. It was never a > framework fault — the transport underneath had a poisoned session. See > [sessions-and-swarm.md](/docs/concepts/architecture/). --- ## The runner ```python import sys, os, json, pathlib sys.path.insert(0, os.path.expanduser("~/agenttests")) import azcfg, hetool from smolagents import CodeAgent, OpenAIServerModel, tool SESS = pathlib.Path(os.path.expanduser("~/agenttests/smolagents/sessions")) SESS.mkdir(parents=True, exist_ok=True) @tool def get_working_folder() -> str: """Return the agent's current working folder (absolute path).""" return hetool.get_working_folder() @tool def run_shell(command: str) -> str: """Run a shell command in the working folder and return its output. Args: command: The shell command to run. """ return hetool.run_shell(command) def invoke(sid, message): c = azcfg.load() model = OpenAIServerModel(model_id=c["model"], api_base=c["base_url"], api_key=c["api_key"]) agent = CodeAgent(tools=[get_working_folder, run_shell], model=model, max_steps=4, code_block_tags="markdown") f = SESS / f"{sid}.json" transcript = json.loads(f.read_text()) if f.exists() else [] history = "\n".join(f'{t["role"]}: {t["content"]}' for t in transcript) prompt = (f"Conversation so far:\n{history or '(none)'}\n\nNew message: {message}\n" "Reply concisely. Use your tools for operational questions.") reply = str(agent.run(prompt)).strip() transcript += [{"role": "user", "content": message}, {"role": "assistant", "content": reply}] f.write_text(json.dumps(transcript, indent=2)) return reply ``` --- ## Engine definition ```json { "type": "process", "file": "/home/you/smolagents/.venv/bin/python3", "nativeSession": true, "argsNew": ["/home/you/he_adapter.py", "/home/you/smolagents_session.py", "", "{message}"], "argsResume": ["/home/you/he_adapter.py", "/home/you/smolagents_session.py", "{sessionId}", "{message}"], "replyField": "result", "sessionIdField": "session_id", "approve": false, "workdir": "/home/you/work", "proxy": { "shape": "openai", "baseUrlEnv": "OPENAI_BASE_URL", "keyEnv": "OPENAI_API_KEY", "modelEnv": "OPENAI_MODEL", "model": "|" } } ``` --- ## Adoption 1. Keep your tools as they are, decorated with `@tool`. 2. Keep a transcript keyed on `sid` and replay it into the prompt. 3. Build `OpenAIServerModel` from `azcfg.load()`. 4. Seal the engine, point `external.engine` at it, restart. --- ## Gotchas **Prefer `CodeAgent` over `ToolCallingAgent` on non-OpenAI models.** `ToolCallingAgent` sets `tool_choice` in a way some providers reject — GLM among them. `CodeAgent` sidesteps it by having the model write Python that calls the tools, which is smolagents' native idiom anyway. **Set `code_block_tags="markdown"`.** The default `` tags arrive truncated from some providers (`` | `*` | inbound | the router's replies come back as this identity | | `you@example.com` | `op:*` | outbound | workspace operations — without it sign-in works and nothing else does | | `you@example.com` | `editor:*` | outbound | memory pane, browser and editor surfaces | | `` | `op:*` | outbound | unattended work — skills and missions run as the agent | | `*` | `` | outbound | engines call the router; the sender is `engine:`, so this must be `*` | | `*` | `` | outbound | **only if you have peers** — one row per external agent you call | ## Add one principal ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json \ --add-rule 'person@example.com,*,inbound,allow' ``` For an external caller acting for a person, the principal is the **hash**: ```bash SUB=$(printf 'person@example.com' | sha512sum | cut -d' ' -f1) ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule "${SUB},,inbound,allow" ``` ## Remove one Write the rule exactly as it was added: ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json \ --remove-rule 'person@example.com,*,inbound,allow' ./hexaeight-agent-linux-x64 hexaeight-agent.json --list-rules ``` The [access review](/docs/operate/compliance-reports/#the-access-review) lists every rule in force, with everything else that gives access. ## Prove it ```bash hexaeight-activate list-policy --subject person@example.com ``` This prints **what the enforcer decides**, not what is written down. A rule that is present but does not match reads as protection and is not. A healthy baseline ends with a deliberate refusal: ``` inbound nobody@example.invalid -> DENY ok ``` ## Two traps **`op:*` is needed twice** — once for the owner, once for the agent itself. The agent's row is the one always missed, and it only breaks *skill runs*, with `bind said 404`. **Never `*,*,inbound,deny`.** It outranks everything else you wrote. ## Vouching ```bash ./hexaeight-agent-linux-x64 vouch allow --caller --subject "$SUB" ./hexaeight-agent-linux-x64 vouch list ``` Loaded **once at startup** — restart after a change: ``` [byoa] vouch policy loaded: 2 rule(s) ``` ## Approved builds Binaries gate on published hashes, fetched at runtime. A build whose hash is not listed is refused by peers, so withdrawing one is central and needs no redeployment. Adding a hash later still reaches every machine, which is why the list — and not the tool — is where they belong. ============================================================================== SECTION: The workspace ============================================================================== ------------------------------------------------------------------------------ PAGE: The workspace URL: /docs/start/workspace/ ABOUT: How you use your agent, screen by screen. Sign in with your phone, ask in plain words, give it memories, turn a process into a mission, work on your machines with every command approved, and hand it long jobs. ------------------------------------------------------------------------------ The **workspace** is how you use your agent: a web page served from your own machine, which talks to the agent over the same end-to-end encrypted channel as everything else. It holds no identity and no model keys of its own, and closing it stops nothing that is running. The examples on this page use a small sample handbook for a fictional company, Example Co, so you can follow along with documents of your own. ## Sign in Open the address the [installer](/docs/start/install/) printed. Enter your email, choose **Scan with HexaEight Authenticator**, scan the QR code with the app, and type the access code it shows. The sign-in screen: a QR code to scan with the HexaEight Authenticator, and the access code typed in.

Scan the code with the Authenticator, then type the code the app shows.

The first time, you accept the workspace's terms. On a business licence the privacy notice is part of them. Each acceptance is kept with the exact words, so you are asked again only when they change. Before you use this workspace: the terms, with I understand and accept. After a while without activity the workspace signs you out: 15 minutes by default on a business licence, 8 hours on a personal one. See [Admin settings](/docs/operate/admin-settings/). ## Home Home: What do you want to do? Tiles for Missions, Mission Runner, Chat, Memory, Coding and Machines, with the bar of places on the left. The bar on the left holds one place for each job. Home shows them as tiles, with how many conversations each has. | | | |---|---| | **Chat** | ask, research and draft with the agent | | **Coding** | work on one codebase: the agent searches the code, changes it and checks its own work | | **Missions** | turn a process into a mission: describe it, review the flowchart, ingest it | | **Mission Runner** | run a mission and check its answers | | **Memory** | the documents and services the agent can search | | **Machines** | servers the agent works on, with every command approved by you | | **HexaPilot** | long jobs the agent runs on its own | | **Messages** | messages to and from other people, delivered end to end to their agent | | **Keys** | API keys the agent's work may use | ## Give it documents: Memory A **memory** is a named collection of documents the agent can search. Create one in **Memory** with a name and a one-line description. The description is how the agent decides when to search it, so say what is inside. Then add documents: **Upload** them from your computer, or **Add Files From Agent** to pick files or a whole folder on the agent's machine. Add files from agent: the sample-handbook folder with leave-policy.md and travel-expenses.md, and Stage this whole folder.

Pick a folder on the agent's machine and stage it.

Press **Save & embed**. The documents are indexed on the agent's machine, on its CPU, and the memory shows what it holds: The sample-handbook memory: 2 documents, 10 chunks, up to date. See [Memories](/docs/extend/documents/) for documents another agent serves, APIs, and very large collections. ## Ask: Chat Open **Chat**, choose **New chat** and ask in plain words. You don't have to tell it where to look: the agent reads the descriptions of your memories and picks the one that fits. It may check with you before it searches. A chat: the question about annual leave, the agent offering to search the sample-handbook memory, and the reply Yes, search it. Switch the view to **Advanced** to see how it got there. The thought process lists every step. Here it is one `memory_search`, with the passages it found and the document and section each came from, then the answer: Advanced view: memory_search with its query, the matching passages from leave-policy.md and travel-expenses.md, and the answer: 24 days of annual leave, up to 5 days carried over until 31 March.

Default shows the answers; Advanced also shows the thinking and every step.

Under the message box: The message box with Attach, the sample-handbook memory chip and Tools, and the AI notice underneath. - **Attach** gives the conversation files, uploaded or picked from the agent's machine. - **The memory chip** attaches one memory that the conversation consults on every turn. You rarely need it, because the agent can search any memory by name. - The line underneath reminds everyone that they are working with an AI system. Export a conversation with **.md** or **PDF** at the top. The export is labelled as AI-generated. ## Make it repeatable: Missions When a piece of work must be done the same way every time, build a **mission**. Open **Missions** and choose **Build a new mission**. Missions lists the conversations that build missions; the missions you have recorded are listed in **Mission Runner**. Missions: describe the process, review the flowchart, ingest the mission, run it in Mission Runner. Recorded missions are listed in Mission Runner. **Describe the process in plain words.** For the sample handbook: > Build a mission that answers employees' questions about Example Co's policies, using the > sample-handbook memory. For each question: decide whether it is about leave or about travel and > expenses; search the sample-handbook memory; answer with the exact number or limit and name the > document it came from. If the handbook does not cover the question, say so and point the person to > the People team or Finance. Never guess a number. The mission engine reads the memory first, then draws the process as a flowchart of **capability cards** and asks you to confirm it: ```mermaid flowchart TD start([Employee question]) --> classify{Leave or Travel/Expenses?} classify -->|leave, annual, sick, parental, time off| leave_search classify -->|travel, expense, hotel, meal, claim, reimbursement| travel_search classify -->|unclear| unsure subgraph leave_card[Card: Answer Leave Question] leave_search[("Search sample-handbook
for leave terms")] leave_search --> leave_extract leave_extract[[Extract exact number/limit
and document name]] leave_extract --> leave_check{Found in handbook?} leave_check -->|yes| leave_answer leave_check -->|no| leave_route leave_answer[Compose answer with
exact number and citation] leave_route[Route to People Team
people@example.com] end subgraph travel_card[Card: Answer Travel/Expenses Question] travel_search[("Search sample-handbook
for travel/expense terms")] travel_search --> travel_extract travel_extract[[Extract exact number/limit
and document name]] travel_extract --> travel_check{Found in handbook?} travel_check -->|yes| travel_answer travel_check -->|no| travel_route travel_answer[Compose answer with
exact number and citation] travel_route[Route to Finance
expenses@example.com] end unsure --> clarify[Ask clarifying question] leave_answer --> done([Return answer]) leave_route --> done travel_answer --> done travel_route --> done clarify --> classify ```

The flowchart the mission engine drew from that description.

In the workspace the flowchart sits beside the conversation. Change it by saying so, or type a change into **Ask for a change to this picture**: The flowchart pane: Ingest Mission and Ingest above the chart, and Ask for a change to this picture below it. Confirm the design and it writes the cards. Then give it a sample question to **prove** them: it walks the cards step by step and checks the answer against the memory. Proving the cards on a sample question: classify, extract the fact, check coverage, compose the answer, PROVE IT — Passed. When you are happy, press **Ingest Mission** and give the mission a name: the name is the memory the mission is written to. Before anything is written, it checks that every card's dependencies are present and every reference is valid: The Ingest Mission dialog: the mission name, Ready to write 3 cards and the flowchart, dependencies all present (answer-leave and answer-travel-expense use the sample-handbook memory), references all valid, and Cancel or Ingest Mission. Press **Ingest Mission** in the dialog, and the flowchart and the cards are written: Wrote the flowchart and 3 cards into memory Handbook_Answers.

The mission is now a memory of its own, here Handbook_Answers. See Missions.

## Run it: Mission Runner Open **Mission Runner**. Your recorded missions are listed on the left, the ones run most recently first, each with its runs beneath it. Pick one to see its cards and flowchart: Mission Runner: the recorded missions on the left, each with its runs beneath it, and the Handbook_Answers mission open with its three cards and Run mission, Edit / duplicate, Export, Import and Delete.

A mission's page: its cards, and what you can do with it.

Choose **Run mission**, or choose **New Mission Runner session** and pick the mission with **Choose mission** above the message box. Ask the kind of question your people will ask. The Advanced view lists every step the mission took, starting with its searches: A runner session with Handbook_Answers chosen: the question about annual leave, and the thought process starting with two memory searches. The answer says which card it used and what it found in the document, and ends with an answer card that names its source: The answer: matched to the answer-leave card, found in leave-policy.md: 24 days of paid annual leave, up to 5 unused days carried over and used by 31 March, with an answer card citing leave-policy.md. If an answer is wrong, choose **Edit / duplicate** on the mission's page, change it in **Missions** and ingest it again. To remove a mission you no longer need, choose **Delete** on its page, or **select** at the top of the list to delete several at once. The documents it searches are not touched, and its runs stay, listed last as orphaned. ## Work on your servers: Machines **Machines** lists the servers the agent can work on. The installer adds the computer the agent runs on (here it is called **local**). Add others with their address, the user to sign in as, and a password or key. The agent signs in first and seals the details only if that works. Nothing can read them back. Machines: the local machine and other servers, with Test, Chat, Run, Log and Remove, and the Add a machine form. Choose **Chat** on a machine to open a conversation bound to it. It starts by surveying the machine, read only, and answers questions about it: An answer card: Disk space on local, 795 GB free, with suggestions under Ask next. **Every command waits for you.** When the agent needs to run something, it appears on the right with **Approve** and **Deny**: Waiting for your approval: df -h, with Approve and Deny, while the conversation shows run_on_machine df -h. Approve it, and the command runs. Its output appears in the terminal on the right, and the agent explains it: After approval: the df -h output in the terminal and the agent's summary of each filesystem. ## Long jobs: HexaPilot For a job that runs for a long time on its own, open **HexaPilot** and choose **New pilot**. Jobs that need you are listed first. HexaPilot: a job marked NEEDS YOU, and New pilot. Describe the job. The agent drafts it as a flowchart with numbered steps, and **nothing runs until you press Start**: A drafted job, Create Handbook Summary: three steps on the right, and Ready with Start and Decline above the message box. After **Start** it plans, works and checks its own work inside its own folder. Ask how it is going at any time, **Pause** or **Stop** it, and answer it when it needs you. A job can also run on a schedule: then the button is **Approve schedule**. ## Keys **Keys** holds API keys that the agent's work may use, such as a key for a search or weather service. Values are sent encrypted, sealed on the agent and never shown again. Agent keys: a key name and a value field — sent encrypted, never shown again — and Save to the agent. ## Privacy On a business licence, **Privacy** at the bottom of the workspace shows your consent record and the privacy notice, and lets you withdraw your consent. After you withdraw, the workspace shows only the terms until you accept them again. See [Admin settings](/docs/operate/admin-settings/#terms-privacy-notice-and-consent). ============================================================================== SECTION: The router ============================================================================== ------------------------------------------------------------------------------ PAGE: The router URL: /docs/router/overview/ ABOUT: The router holds the model keys so no agent has to, and decides who may use which model. A company runs one for its own people; a model provider runs one to serve its models to its customers' agents. ------------------------------------------------------------------------------ An agent never holds a model key. Its engines send every model request to a **router**, and the router passes it on to the model. - **Every request proves who sent it.** It is encrypted end to end between the agent and the router, and it proves which agent sent it and, when the agent names them, the person it is for. - **The router decides.** Its rules say who may use it, and which models they may use. - **The router records every call**: who it was for, the route and model, the tokens used and the time it took. ```mermaid flowchart LR subgraph co["A company"] A1["Its agents"] -->|"encrypted, proves who"| R1["Its router
holds the provider keys"] end R1 --> P1["AWS Bedrock, Azure,
OpenAI and others"] A2["A customer's agent"] -->|"encrypted, proves who
no API key"| R2["A provider's router
large.example.com"] R2 --> M2["The provider's
own models"] ``` ## Who runs one | | **A company** | **A model provider** | |---|---|---| | **who calls it** | its own agents, for its own people | its customers' agents | | **what it reaches** | the company's provider accounts, with their keys | the provider's own models | | **who it sees** | each person by name, and it can refuse callers who are not named | the person, or only the customer's agent when that agent keeps its callers private | | **who may use it** | whoever the company's rules allow | the customers the provider admits | | **read** | [Run your own router](/docs/router/own/) | [Serve models to agents](/docs/router/providers/) | The [installer](/docs/start/install/) can set up a router on the same machine as the agent, with your provider key, or connect the agent to a router that runs elsewhere. ## Using someone else's router An agent can use a router that someone else runs: a model provider's, or a central one at your company. Point an engine at it by its name and address. There is no API key to store, and neither side sets up OAuth for the other: the router admits your identity, and every request proves it. See [Use someone else's router](/docs/router/forward/). ## Between organisations The router serves models. When the agents of two companies work with each other directly, see [Two agents talking to each other](/docs/extend/agents-talking/). A company can also vouch for its agent through its own OAuth app, so that other companies' agents check on every message that the company still stands behind it: see [HexaEight and OAuth](/docs/concepts/oauth/). ------------------------------------------------------------------------------ PAGE: Run your own router URL: /docs/router/own/ ABOUT: You hold the provider keys. One place to rotate them, one place that decides which agent may use which model, and per-caller accounting. ------------------------------------------------------------------------------ The router holds model credentials so **no agent has to**. Agents ask for a route name; the router resolves it to a provider and decides whether that caller may use it. Run your own when you already have provider accounts and want everything in one place. This page is for a company serving its own people. A model provider serving its models to customers' agents: see [Serve models to agents](/docs/router/providers/). ## Where it is The [installer](/docs/start/install/) sets up a router in `~/heia-router` with the provider you chose. The commands on this page run from that folder. ## Add providers ```bash cd ~/heia-router hexaeight-activate upstreams ``` Supported: `anthropic`, `openai`, `azure`, `bedrock`, `openrouter`, `ollama`. Each carries its own key and model list, written to **`upstreams.yaml`** beside the binary. That one file holds the upstreams *and* the router's own settings — there is no second config file. > **These files hold your provider keys in plain text.** Treat them the way you would any secret: > restrict file permissions, exclude them from version control, and keep them out of backups that > travel. Confirm what each will actually serve: ```bash hexaeight-activate models ``` ## How a route name works An engine sends both names in one field, separated by `|`: ``` "model": "claude-ant-aws|" ``` The router matches the **left** half against `upstreams.yaml` to choose a provider and key, and puts the **right** half on the wire. Two consequences worth understanding: - a route name **never has to be a real model id** — it is yours to name - a provider **never sees your routing names** **A route name is a glob you choose.** It is matched against the left half of what an engine sends, so it never has to look like a real model id, and a provider never sees it. A useful convention is `*--` — the dialect being the API the caller speaks (`ant`, `oai`, `res`) and the tag one provider and one key. Two regions of the same provider are two tags, because they are two keys. But a plain prefix works just as well: `*-ant-aws` and `glm5br*` are both valid, and a real router usually has some of each. List what yours are called: ```bash hexaeight-activate upstreams --list ``` ## Its policy — the base set The router enforces rules of the **same shape as an agent's**: a sender, a destination, a direction and an effect. It has its own store, sealed under the **router's** key, which the agent CLI cannot write. A working base policy looks like this: ``` sender dest dir meaning ------------------------ ------------ --------- -------------------------------------------- you@example.com * inbound the owner may relay through any agent you@example.com * outbound the owner may use any route my-agent * inbound this agent may relay my-agent * outbound ...using any route second-agent * inbound a second agent may relay second-agent *-ant-aws|* outbound ...but only these two routes second-agent *-oai-aws|* outbound my-agent inbound a person, relaying through that agent * outbound ...may use any route ``` Two things to take from it: - **`inbound` is "may relay"; `outbound` is "may use this route".** Both are needed. An agent with only an inbound row connects and can reach no model. - **Restrict by route where it matters.** `second-agent` above is deliberately limited to two routes. `*` is convenient for your own agent and wrong for anything you did not write. A person appears as the **hash** of their address, not the address itself — the same subject used for vouching on the agent side. ### Confirming it is on The router prints the whole policy at startup: ``` Authorization: Casbin (encrypted policy at …/router-policy.he, bootstrap=False) [policy] 9 rule(s): [policy] sender='you@example.com' dest='*' realm='default' dir='inbound' eft='allow' … Callers: opaque permitted - an agent may decline to name its callers ``` Read three things: **`bootstrap=False`** (it is enforcing), the **rule count**, and the **Callers** line, which tells you whether `requireIdentifiedCaller` is in effect. **`bootstrap=True`, or any rule whose sender is `*`, means the router is open to anyone who can reach it.** A new router starts that way. The installer replaces it with rules for your agent, and for you through your agent. It authorises twice per call: may this caller relay through this agent, and may this caller use this route and model. Policy matches the whole `route|model` string, with globs: ``` claude-ant-aws|* that route, any model on it *|moonshotai.kimi-k2.5 that model, by whichever route reaches it ``` > Globs do not cross `/`. A model id containing a slash needs a star per level — > `kimi-oai-or|*/*`, not `kimi-oai-or|*`. **The router reads its policy once at startup.** It does not reload on change — after editing, restart the router or the change is not in force. ## Writing the rules `--init-policy` is how rules are written. There is no `--add-rule`: the store is sealed under the router's own key, so the router itself is the only thing that can change it. ```bash cd ~/heia-router cp -p router-policy.he "router-policy.he.bak_$(date +%Y%m%d_%H%M%S)" set -a; . ./env-file; set +a ./hexaeight-router-linux-x64 --init-policy ``` It shows the rules you already have, then asks five things: | it asks | answer with | notes | |---|---|---| | **Do you have an external authorization service?** | `N` | the rules you enter next decide who may use the router | | **Who may use this router?** | `alice@example.com,,my-agent` | comma-separated. Enter a person twice: by address, and by the SHA-512 hash of the lower-cased address | | **Which models may they use?** | `*`, or `*-ant-aws\|*` | a rule matches the whole `route\|model`, so give a route as `route\|*`. `*` allows every model this router serves | | **Which agents may vouch for them?** | blank, or an agent name | blank means any agent | | **Write this policy?** | `y` | **nothing is written before this answer** | The hash of an address: ```bash printf '%s' 'alice@example.com' | tr '[:upper:]' '[:lower:]' | sha512sum | cut -d' ' -f1 ``` Typing `*` as the sender makes it demand the literal word `YES` — because that is bootstrap, and leaving bootstrap is the whole reason the command exists. ### What it does to bootstrap A fresh router starts wide open, with two rules: ``` p, *, *, default, inbound, allow # anyone may reach this router p, *, *, default, outbound, allow # ...and use any model on it ``` When you write your first real policy, **those two are removed.** The command says so before it does it. After that the router is default-deny, and every caller needs a rule. ### It is additive, and it does not reload Running it again **adds** to what is there rather than replacing it, so you can admit one more caller later without retyping the rest. The router reads its policy **once, at startup**. After writing, restart it: ```bash heia restart router ``` Then check the boot line says what you expect: ``` Authorization: Casbin (encrypted policy at …/router-policy.he, bootstrap=False) [policy] 9 rule(s): ``` ### Reading the policy back `router-policy.he` is encrypted and there is no decrypt tool. You read it two ways, and both print it in clear: the **router prints every rule at startup**, and `--init-policy` shows the current rules before it asks you anything — so you can run it, read them, and answer `N` to change nothing. ## Accounting Because every call carries a proven identity, usage is attributable **per caller** rather than per key. That is the practical reason to run a router even with a single provider: an API key tells you what was spent; a router tells you **who** spent it. There is no billing screen, and none is needed. The router appends a line per call to **`usage.jsonl`** beside the binary, and every session on the agent side leaves its own JSONL trail of what was asked and what it cost. ```bash wc -l usage.jsonl # calls served tail -1 usage.jsonl # the most recent, with its token counts ``` It is a plain text record, one JSON object per line, so totalling it by caller, by model or by day is whatever tool you already use — `jq`, a spreadsheet, or your own script. Nothing is aggregated behind an interface you cannot query. ## Who may decline to be named An agent may keep a caller private: it sends `:opaque:` instead of who the caller is, and the router attributes the call to the **relaying agent**. An agent does this for outside callers when `external.opaqueCallers` is on. On your own router you usually do not want that — you run both sides, and per-caller accounting is the point: ``` requireIdentifiedCaller: true ``` That setting refuses opaque callers outright. A model provider's router usually accepts them: see [Serve models to agents](/docs/router/providers/#who-you-see). ------------------------------------------------------------------------------ PAGE: Serve models to agents URL: /docs/router/providers/ ABOUT: For model providers. Serve your models at a name on your own domain, and let your customers' agents call them directly, with no API keys and no OAuth. Every request proves who sent it, and you admit and bill by that identity. ------------------------------------------------------------------------------ A model provider can run the router to serve its own models to HexaEight agents. ## What changes Today a customer creates an API key with you and keeps it wherever their software runs. Whoever holds the key can spend on that account, and the key names an account, not the agent or the person behind a request. With a router: - **Your models have a name on your domain**, such as `large.example.com`. Serve all your models under one name, or give each model its own, such as `large.example.com` and `fast.example.com`. Each name is a router of its own. - **Your customers' agents call that name directly.** When an agent starts, it checks that the address answers as that name, and it does not use an address that does not. - **There is no API key and no OAuth.** Every request is encrypted end to end between the customer's agent and your router, and proves which agent sent it. That proof is the credential: there is nothing to issue, store, rotate or leak. - **You decide who may use it**, by identity: a person, or a customer's agent. - **You bill by identity.** Every call is recorded with who it was for, the model and the tokens used. ```mermaid sequenceDiagram participant A as Customer's agent participant R as Your router
large.example.com participant M as Your model A->>R: request, encrypted end to end
proves the agent, and the person when named R->>R: may this caller use this model? R->>M: the request M-->>R: the answer R-->>A: the answer, encrypted end to end R->>R: record who, model and tokens ``` ## Who you see The customer's agent decides whether the person is named: | the customer's agent is working for | your router sees, and bills | |---|---| | a person signed in to it | that person, proven with their own key | | a caller it keeps private | only the agent | An agent can keep every caller from outside its company private. The agent itself is then your customer: for a personal agent, one person; for a company's agent, the company. Your router accepts private callers unless `upstreams.yaml` says otherwise: ```yaml requireIdentifiedCaller: true # refuse callers who are not named ``` A provider normally leaves this out. Who a customer's own users are is the customer's business. ## Set it up ### 1. A name on your domain In the HexaEight Authenticator, use an identity whose email is at your domain, add a **Domain Resource** such as `large.example.com`, and publish the DNS TXT record the app gives you. The record is checked when the licence is granted. See [Domain resource](/docs/concepts/authenticator/#domain-resource). ### 2. Install it with that name Run the [one-line installer](/docs/start/install/). In the licence step, scan with the domain resource. When the installer asks **Where are your models?**, choose **3** or **8**, another endpoint that speaks the Anthropic or the OpenAI API, and give the address of your model. ### 3. Admit your customers From the router's folder: ```bash cd ~/heia-router cp -p router-policy.he "router-policy.he.bak_$(date +%Y%m%d_%H%M%S)" set -a; . ./env-file; set +a ./hexaeight-router-linux-x64 --init-policy ``` | it asks | answer | |---|---| | **Do you have an external authorization service?** | `N` | | **Who may use this router?** | the customers you admit, comma-separated | | **Which models may they use?** | `*` for every model, or the routes their plan includes, each as `route\|*` | | **Which agents may vouch for them?** | blank | | **Write this policy?** | `y` | Admit each customer as: - **a customer's agent**, by its name, such as `agent01.example.org`. Use this when the agent keeps its callers private. - **a person**, twice: by their email address, and by the SHA-512 hash of the lower-cased address: ```bash printf '%s' 'alice@example.org' | tr '[:upper:]' '[:lower:]' | sha512sum | cut -d' ' -f1 ``` The router reads its rules when it starts, so restart it: ```bash heia restart router ``` Run `--init-policy` again for each new customer: it adds to the rules already there. More in [Run your own router](/docs/router/own/#writing-the-rules). ### 4. Make it reachable at that name The router listens on port 5100. Publish it at an address on the same name, such as `https://large.example.com`, for example through your load balancer. ## Billing The router adds one line per call to `usage.jsonl`, in its folder: | field | | |---|---| | `ts` | when the call ended | | `session` | the session it belongs to | | `email` | who the call was for: the person, or the agent's name for a private caller | | `route`, `model` | what was called | | `input_tokens`, `output_tokens` | tokens in and out | | `cache_read_input_tokens`, `cache_creation_input_tokens` | cached tokens, when the model reports them | | `metered` | `false` when the model reported no token counts | | `latency_ms` | how long the call took | Total it by customer with any tool you already use. The router also keeps a sealed [audit trail](/docs/operate/audit/#the-router-keeps-one-too): every session it allowed or refused, and every call. ## What your customers do They add an engine pointed at your router, by its name and address, with a route name you publish: ```bash hexaeight-activate engine --add chat \ --name chat \ --model "large|" \ --router "large.example.com|https://large.example.com" ``` Their agent holds no key of yours. See [Use someone else's router](/docs/router/forward/). ## Next - [Use someone else's router](/docs/router/forward/): the customer's side - [Run your own router](/docs/router/own/): routes, rules and the policy command - [HexaEight and OAuth](/docs/concepts/oauth/): how a company vouches for its agents to other companies ============================================================================== SECTION: Serving other people ============================================================================== ------------------------------------------------------------------------------ PAGE: Your own users URL: /docs/extend/your-users/ ABOUT: Let unlimited people use your agent, for free, without giving any of them a workspace sign-in — through your existing login, or through the HexaEight Authenticator. ------------------------------------------------------------------------------ The workspace is the operator's console. A personal licence admits one address there, and a business licence admits several — but neither is how your **users** reach you. For that you branch off a **runner**: a second agent, with its own engine, that serves outside callers. Through it, **unlimited users authenticate for free.** No per-user charge, no cap. your users your app your login, your UI names the user runner agent its own identity the work unlimited users · free · the agent’s licence is the only one ## Two doors onto the same house A person can arrive through either, and **both derive the same identity**. Someone who signs in with your password today and a HexaEight Authenticator tomorrow is the same user to your application — same token, same isolation, same quota. | | **BYOA** — bring your own auth | **alt-auth** | |---|---|---| | who authenticates the person | **you do**, exactly as you do today | the HexaEight Authenticator | | what you build | your own frontend and backend, any auth you like | a front door against the alt-auth library | | what your users do | **nothing new** | install the Authenticator (free) and type a code | | what you keep | Clerk, Auth0, Cognito, your own password table | nothing to keep | **Neither needs a licence of its own.** The only licence in play is the one your agent already has. There is no per-user cost on either door, and the Authenticator is free for everyone. The real difference is **who carries the friction**: with BYOA your users notice nothing and you own the auth; with alt-auth you write almost no auth code and every user installs an app. --- ## BYOA — keep the login you already have This is the first step for most people, and **it changes nothing your users can see.** Your login, your user records, your sessions, your UI: untouched. One thing changes. Instead of your backend calling a model provider with a provider key, it calls your agent and **names the user**: BEFORE your backend a provider API key the model the key lives in your code AFTER your backend names the user your agent a route router → model Two consequences worth being concrete about: - **The provider key leaves your codebase.** It lives in the router instead. - **Your work gets a per-user identity** it can meter and isolate on, without you building one. The agent verifies **your backend**. Your backend vouches for **the user**. That split is the whole mechanism: you are already the authority on who your users are, so nothing asks you to prove it again. ### What you actually build Anything you like. A web app, a mobile app, an internal tool — with whatever login you already have. **The part that holds an identity stays on the licensed machine.** That is the whole shape of BYOA, and it is worth drawing before the code: | where it runs | what it is | |---|---| | **your licensed machine** | your identity agent, the **runner** branched off it, and the small **caller** that speaks to the runner. All three share one identity by hardlink, so this is **one licence** | | **anywhere you like** | your front end — web app, mobile app, internal tool — with whatever login you already have. It holds no identity and needs no licence. It takes a question and hands it to the caller | So your front end never authenticates to an agent. It collects a question, and the caller on the licensed machine runs the runner **once per question**, naming the user as it goes. That naming is a **vouch**, and it is what keeps one person's conversation out of another's. > **That first hop is yours.** How your front end reaches the caller — an HTTP call, a queue, a > socket — is ordinary plumbing you write and secure yourself. HexaEight begins at the caller, where > an identity exists. If your front end and the caller are on different networks, protect that hop > the way you would any other internal API: it carries your users' questions. | | | |---|---| | **an identity** | only on the licensed machine: the agent, the runner and the caller, sharing one set of files | | **a separate paid licence** | **no**, as long as the identity-holding parts sit on the machine you already licensed | | **an SDK** | no. The call is made with the agent binary's client mode — see [Other software calling it](/docs/extend/external-callers/) | > **Identity files do not travel.** `env-file` and `hexaeight.mac` are bound to the machine that > activated them, and a hardlink cannot cross machines. If you were to put an identity-holding > component on a **second server**, that server would need its own activation and therefore its own > licence. Keeping the runner and its caller on the licensed machine is what avoids that, and it is > the arrangement these docs describe throughout. The caller holds nothing about your users. Your front end passes it the question and who asked, and it calls the runner: ```json { "ask": "the user's question", "on_behalf_of": "" } ``` That is the whole integration. The runner answers; your front end renders it however you want. > **No extra licence.** Your backend is not separately licensed — the agent's identity licence, > which you already have, is the only one. Nothing about BYOA is charged per user. Two things to get right: - **Name the user per request.** `on_behalf_of` is what gives each person their own isolated session, so one user's conversation never leaks into another's. - **The serving agent must be told your backend may speak for that subject.** That is a **vouch** — see [Trust and permission](/docs/concepts/trust/). --- ## alt-auth — no password reaches you at all The second door. A user signs in with the HexaEight Authenticator and **you never handle a credential**. You still build the front end. The page has to derive a key and seal a body. A **reference browser client** that does that part is coming; until it is available, implement the protocol below, which is all it does. ``` your page POST /external/auth {email} → {session_id, challenge, expires_in: 120} the agent seals a one-time code to that address their Authenticator decrypts it and shows it they type it into your page your page POST /external/incoming → sealed under a key both sides derived independently ``` Both calls are made **by the page in the browser**, to your runner agent. What the client handles is the cryptography; you handle the two fields and the screen. The protocol, if you are implementing it: ``` key = SHAKE256("hexaeight.external.v1|" + session_id + "|" + CODE) 32 bytes body = AES-256-GCM(key, fresh 96-bit nonce) tag appended ``` Both directions are sealed under the same key, so opening the reply proves the agent derived the identical key — not merely that it accepted yours. **Never reuse a nonce**, and keep the key non-extractable (`crypto.subtle` with `extractable: false`) so a script on the page cannot lift it. **The agent successfully opening the request *is* the authentication.** There is no password to check, because there is no password. > **Every alt-auth user needs the HexaEight Authenticator** — it is how the code reaches them. It > is **free for everyone**, and there is no per-user cost, but it is a real step to ask of your > users. That is the trade against BYOA, where they install nothing. What that buys, precisely: | property | consequence | |---|---| | **no cookies, ever** | authentication is the sealed body, so there is no ambient credential a cross-site request could ride. **CSRF is structurally absent**, not mitigated | | **sealed both directions** | opening the reply proves the agent derived the *same* key, not merely that it accepted yours | | **120-second code, three attempts** | an unspent code dies fast; three wrong keys end the session permanently | | **one error for "wrong key" and "no such session"** | a stranger cannot probe whether a session is live | > **It does not stop XSS, and nothing in a browser does.** What it changes is the blast radius: a > script on your page can act as the signed-in user while the tab is open — it could do that anyway > by driving the page — but it cannot extract a reusable credential, because there is not one. ### Letting your users in Admit one address, or a whole domain: ```bash # one person hexaeight-activate front-door-policy allow --self --subject you@example.com # everyone at a domain — this is the one you usually want hexaeight-activate front-door-policy allow --self --subject '*@yourcompany.com' ``` `--self` says the rule is for **this agent acting on behalf of the user who signed in** — the agent does the work, vouched for that person, rather than the person reaching anything directly. `--subject` is who may sign in: one address, or a glob for a whole domain. Until you add a rule, alt-auth is closed and the agent says so at startup: ``` [frontdoor] NO sign-in rules — alt-auth is CLOSED. ``` ### Your own branding The Authenticator your users install is the HexaEight one. A **white-labelled app under your own brand is possible** and is an enterprise arrangement — it carries a cost, so [contact support](https://store.hexaeight.com) if you need it. > **The agent token is a different thing.** It lets a browser app authenticate **to your agent**, > and it is created in the Authenticator under a resource — see > [The Authenticator](/docs/concepts/authenticator/). alt-auth authenticates **a person**. If you > are letting people in, you want alt-auth. --- ## Branching off a runner Both doors need an agent to arrive at, and it should **not** be your workspace agent. A runner is a second agent with its own ports, its own policy store, and **one sealed engine** — so a caller can ask it to work and cannot ask it for anything else. ```bash hexaeight-activate add-external-agent \ --from ~/hbia-agent \ --dir ~/heia-runner \ --mission My_Workflow \ --license personal \ --owner you@example.com \ --base-port 8930 ``` | flag | what it does | |---|---| | `--from` | supplies the **identity only** — `hexaeight.mac` and `env-file` are hardlinked, never copied | | `--dir` | the new runner's folder | | `--mission` | the one procedure this runner will serve | | `--base-port` | its own ports, so it can run beside your workspace agent | It gets **its own engine**, sealed to that one capability: ``` [hexaeight-agent] engine 'missionrun-external' runs ONE mission (sealed): My_Workflow [external] enabled — authenticated:missionrun-external cleartext:OFF ``` That is the line that matters. **If it is absent, the runner is not sealed** and a caller can ask it to run whatever they like. ### Why a separate agent, and not another engine on the one you have | | | |---|---| | **blast radius** | the runner's policy store is its own; admitting a customer there admits them to nothing else | | **one capability** | a sealed engine serves one procedure. A caller chooses the question, never the method | | **its own ports and store** | it starts, stops and is upgraded without touching your workspace | | **revocation is local** | removing a customer is a rule in the runner's store | **Read this page first, then that one.** This page is about letting *people* in — your users, through your app. [Other software calling it](/docs/extend/external-callers/) is about letting *another system* call your agent machine-to-machine, and it carries the full provisioning detail, including the parts the tool does not do for you. Both use the same runner; only the caller differs. --- ## One thing to know before you promise it **Conversation threads do not follow a user across doors automatically.** The same person arriving through BYOA and through alt-auth gets two conversations, because the thread id is minted by whoever runs the front end and the transcript is keyed on it. If you want one thread across both doors, **mint the id the same way on both** — which you can, because the id is yours. ------------------------------------------------------------------------------ PAGE: Other software calling it URL: /docs/extend/external-callers/ ABOUT: Let someone else's software call your agent — over DDE, bound to a person, running one sealed mission it cannot choose. ------------------------------------------------------------------------------ Everything so far assumed the caller is you, or another agent you run. The **front door** is for the case where it is not: another company's backend, a customer's application, a partner system. The shape that makes this safe: the caller their software open a session ask a question runner agent /external/auth /external/incoming bound to a person ONE sealed procedure a caller chooses the question · never the method A caller can **ask a question**. A caller cannot choose the mission, inject priming, or reach anything outside the fence. ### The words this page uses | | | |---|---| | **`ask-daemon`** | the agent binary's client mode — it makes one encrypted call to another agent and prints the reply | | **`peer`** / **`peer_url`** | who you are calling, by identity name, and where it listens | | **`capability`** | which sealed capability on that agent you are asking for | | **`on_behalf_of`** | the person this turn is for, as `sha512(their email)` — never the address | | **`HEIA_DIR`** | an agent's own store. **The caller and the door must not share one** (see gate 3) | ## Provision the runner Use a **separate agent** for the front door. It gets its own ports, its own policy store, and one sealed engine — and it can run alongside your workspace agent. ```bash hexaeight-activate add-external-agent \ --from ~/hbia-agent \ --dir ~/heia-runner \ --mission My_Workflow \ --license personal \ --owner you@example.com \ --base-port 8930 ``` `--from` supplies the **identity only** — `hexaeight.mac` and `env-file` are hardlinked, never copied. Ports are chosen (or checked, with `--base-port`) **before** anything is created, so a port clash leaves nothing behind. Pass `--model ""` to choose the runner's model; without it, the source agent's mission route is used. **Start and restart it from its own folder:** ```bash cd ~/heia-runner && hexaeight-activate restart agent ``` `restart agent` stops and starts only the agent in that folder — the output names every other agent it left alone — and gives a runner its own store (`HEIA_DIR=-frontdoor/heia`) automatically. ### What the runner can see A runner has its **own** harness root, `-frontdoor/harness-root`, and the mission it runs sees **only that** — its own mission, and nothing else on the machine, until you export something into it: ```bash cd ~/heia-runner hexaeight-activate runner-memory --list hexaeight-activate runner-memory --share weather # served: the pointer is exported hexaeight-activate runner-memory --share My_Documents # local: linked, no copy hexaeight-activate runner-memory --share My_Documents --copy # or a self-contained copy hexaeight-activate runner-memory --unshare weather ``` A served memory is still reached through `service_call` under the runner's own policy. Each caller session also gets its own working folder, `-frontdoor/work//`. > **Measured before this existed:** an outside caller asked a runner to list memories and got every > memory on the machine. A runner created before Activate 1.0.67 still behaves that way — re-create > it with `add-runner`, then share only what it needs. ## What provisioning does not do for you Six things stand between a freshly provisioned runner and its first successful call. Each fails differently, and **none of them says "policy"**. These are **setup steps, not bugs** — but provisioning could do several of them for you, and the intent is that it will. Until then, work through them in order; each one's symptom is given so you can tell which you have hit. ### 1. The vouch subject is the hash, not the email An external turn binds to `sha512(email)`, not the address. ```bash cd ~/heia-runner set -a; . ./env-file; set +a SUB=$(printf 'you@example.com' | sha512sum | cut -d' ' -f1) ./hexaeight-agent-linux-x64 vouch allow --caller --subject "$SUB" ``` Symptom without it: `not permitted to act on behalf of that subject`. ### 2. The same subject needs an inbound rule ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json \ --add-rule "${SUB},,inbound,allow" ``` Symptom without it, and this is the one nothing prepares you for — the router *approves* and the agent then refuses: ``` [engineproxy] REFUSED to register router session … no matching allow rule (default-deny) [engineproxy] router authorized … but the agent policy refused to register it ``` ### 3. The caller and the door need separate stores Both resolve through `HEIA_DIR`. Sharing one means the caller's "expecting a reply" record and the door's inbox are the same file, and **the door answers your own question back to you**: ```json {"ok":true,"accepted":"response"} ``` `restart agent` gives the door its own store (above). Give the caller a different one: ```bash export HEIA_DIR=/home/you/caller-heia # making the call ``` ### 4. The runner's harness root starts with nothing in it The wrapper runs the engine with `--root -frontdoor/harness-root`, created empty. Put the mission into it and export the memories it uses, or the mission has nothing to navigate — the turn returns a permissions frame in about a second and writes nothing. - **A published framework mission:** `hexaeight-activate enable ` run **in the runner's folder** installs it into the runner's root and seals its command there. - **Your own mission:** `agskill-import --in --root -frontdoor/harness-root`. - **Its memories:** `hexaeight-activate runner-memory --share ` for each one. ### 5. Re-sealing drops the wrapper unless you say otherwise `engine --add` without `--file` unbinds the wrapper silently. Same symptom as above. ### 6. The agent binary must be new enough A binary older than the sealed-mission feature **ignores the mission** and reports `-> process` rather than `runs ONE mission (sealed): `. No error, no log line explaining it. > **Is the caller another agent?** See [Two agents talking to each other](/docs/extend/agents-talking/) > for the rules on both agents and their routers. ## Make the call ```bash cd /path/to/caller-identity set -a; . ./env-file; set +a export HEIA_DIR=/home/you/caller-heia export HEIA_ASK_TIMEOUT_SECONDS=0 # 0 = wait for the work; the peer bounds its own turn SUB=$(printf 'you@example.com' | sha512sum | cut -d' ' -f1) printf '{"ask":"","on_behalf_of":"%s","peer":"", "peer_url":"http://127.0.0.1:8930","capability":""}\n' "$SUB" \ | ./hexaeight-agent-linux-x64 ask-daemon ``` Only a line starting with `{` is a result — the tool narrates to the same stdout. ### What success looks like ```json {"sent":true,"reason":"sent","peer":"","session":"s-2ec7a313…","reply":"…"} ``` `sent:true` means it was delivered and answered. The `reply` holds the turn's frames; the last one is the result: ```json {"type":"result","subtype":"success","is_error":false, "result":"","num_turns":11,"duration_ms":152906, "usage":{"input_tokens":117855,"output_tokens":1475}} ``` Read `subtype` first: `success` means the procedure ran to an answer. And check the door's own log recorded the turn — if the wrapper never ran, nothing is written there: ``` 2026-09-25T22:21:08+00:00 mission=My_Workflow in=431 chars out=701 chars ``` A **failure** is just as legible: ```json {"sent":true,"reply":"{\"ok\":false,\"error\":\"not permitted to act on behalf of that subject\"}"} ``` which is gate 1 above — the vouch names the address instead of `sha512(address)`. ## Three policy stores authorise one turn This is where a day goes if it is not written down. Each has its own rule list, and a rule in one is invisible to the other two. | # | who decides | rules live in | |---|---|---| | 1 | the serving agent | the runner folder, via `--add-rule` | | 2 | the router, relay gate | the router's own sealed policy | | 3 | the router, model gate | the same file | The router's policy is sealed under the router's key — the agent's CLI cannot write it, and the router **does not hot-reload**. Restart it after a change. ## A cached session outlives a policy change Sessions are cached by `(peer, on_behalf_of)`. A session opened before you fixed a rule — or before you re-sealed the mission — keeps being reused and keeps failing: ``` '' may not post to session 'ext-s-…' ``` Retire the cached entry under `/peer-sessions/` and the next call mints a fresh one. It does not self-heal. ## Verifying the door is really closed ``` [hexaeight-agent] engine 'missionrun-external' runs ONE mission (sealed): My_Workflow [exec-policy] mission 'My_Workflow': enforce ON, NO cmdset — shell denied [external] enabled — authenticated:missionrun-external cleartext:OFF [byoa] vouch policy loaded: 2 rule(s) ``` Four lines. If the first is missing the caller can choose the mission. If the second says anything other than `shell denied` the mission can run commands. Read them after every restart. ------------------------------------------------------------------------------ PAGE: Two agents talking to each other URL: /docs/extend/agents-talking/ ABOUT: One agent asks another a question and gets its answer — from a chat or a mission, through the connect-to-agent memory; found by name through the registry, over DDE. Every rule both agents and their routers need, the no-relay default, and what each error means. ------------------------------------------------------------------------------ Agent **A** asks agent **B** a question. B runs its own sealed mission — its framework, its tools, its model — and A gets B's answer. Nothing is shared between them but a name and the rules below. In a chat you just say so — *"ask `` what the weather in Chennai is"* — and A uses its **`connect-to-agent`** memory ([below](#from-a-chat-or-a-mission--connect-to-agent)). Every install has it (agent r30, harness engine r41). ``` A ──(1) who is B? ────────────► registry.fastagents.net by NAME, over DDE (a sealed query, not a GET) A ──(2) open a session ───────► B /external/auth B's policy: may A talk to me? A ──(3) the question ─────────► B /external/incoming B runs its ONE sealed mission B ──(4) a model, please ──► B's router may B relay for A? B ──(5) its tools ────────► other agents' APIs may B call them? A ◄─(6) the answer ─────────── B ``` **Verified 2026-09-27:** from a workspace chat, an agent asked a PydanticAI agent by name through `connect-to-agent`; the PydanticAI agent answered with live weather and BBC headlines it fetched from two API agents. Asked to pass a question on to a LangGraph agent, it declined — [no relay](#no-relay-by-default). `` and `` below are the agents' **identity names** — `HEXAEIGHT_RESOURCENAME` in each one's `env-file`, the name in its boot log's `identity:` line — not folder names. ## Prerequisites — each agent works on its own Before two agents can coordinate, **each one must be a working agent by itself.** None of this is about the other agent; an agent missing any of it cannot answer anyone, its own owner included. | each agent needs | | |---|---| | **its own identity** | the registry holds **one address per name**. Two agents under one identity cannot both be found by name — an agent others must reach by name needs an identity of its own | | **its own model (an LLM)** | its engine asks **its router** for a model, so its router must admit it: ` -> *` inbound (it may relay turns) and ` -> ` outbound. This is part of standing an agent up — the same as for any agent. The [installer](/docs/start/install/) writes these rules for the agent it installs | | **a mission it serves** | the agent being asked is a [runner](/docs/extend/external-callers/) (`add-runner`) sealed to a mission. An API-only agent (`"apiOnly": true`) answers only named API routes and refuses a question: `this agent serves API requests only` | | **a way to be found** | registered (`"register": true`) with a public address — a tunnel, `"reach": {"mode": "cloudflared", "bin": ""}` — or the caller is given its address explicitly | Giving an agent its model, on its router's folder: ```bash cp -p router-policy.he "router-policy.he.bak_$(date +%Y%m%d_%H%M%S)" set -a; . ./env-file; set +a printf 'N\n%s\n*\n\ny\n' "" | ./hexaeight-router-linux-x64 --init-policy # -> * both ways heia restart router # the router reads its policy only at start ``` Replace `*` (the models) with a route pattern to limit which models the agent may use. A registered agent's boot log shows it can be found: ``` [reach] mode=cloudflared tunnel up https://…trycloudflare.com [register] OK -> https://registry.fastagents.net as = https://…trycloudflare.com (http 200) ``` > **Measured:** a newly stood-up agent was found by name and accepted the session, then could not answer: > its router did not admit it (`NOT authorized with router …: HTTP 400`). That was a missing > *prerequisite* — the agent had no model — not a coordination rule. ## Coordination — the rules between the two With both agents working, what lets A talk to B is **each agent's own policy**, both sides, both directions. Policy is default-deny. **On agent B** (the one being asked) — run in B's folder: ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule ",*,inbound,allow" # A may open a session and ask ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule "*,,outbound,allow" # B may answer / reach A ``` > **The destination is `*`, not B's own name.** A session request is checked as > *sender = A, destination = self*. A rule `,,inbound` looks right and does not match. **On agent A** (the one asking) — in **every** folder that holds A's identity: ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule "*,,outbound,allow" # A's engines may reach B ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule ",*,inbound,allow" # B's answers and calls may reach A ``` `add-runner --peer ` writes B's outbound row for you when B is created. **On every API agent B's tools call** (a weather or news service, say) — the same pair, for B: ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule ",*,inbound,allow" ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule "*,,outbound,allow" ``` Agent policy changes are picked up without a restart. ## Routers — one case to know about Coordination needs **no router change** when each agent already has its model (the prerequisite above) and the answering agent's router already knows the caller. Two things are worth knowing: - **The answer's model is always B's** — the route B's engine is sealed to, on B's router. A's router is not involved in A asking B, and A cannot choose B's model. - **B's router checks who each turn is for.** A turn from A runs *for A*, so B's router must allow A as the turn's sender. When A and B share a router that already has ` -> *` rows (as it does for A's own work), that is already true. **When B's router has never seen A** — different routers, different operators — add A there: ```bash printf 'N\n%s\n*\n%s\ny\n' "" "" | ./hexaeight-router-linux-x64 --init-policy # -> in, -> * out heia restart router ``` Measured on a shared router only; on separate routers this follows from the same check and has not been run end to end yet. | | router change for A to talk to B | |---|---| | both agents have their model, one shared router | none | | B's router has never seen A | on **B's router**: allow A as a turn's sender (above) | | they also talk the other way | the mirror, on A's router, for B | | A acts **for a person** | the person, as `sha512(email)`, in B's vouch, B's inbound rule and B's router — the [BYOA stores](/docs/extend/external-callers/#what-provisioning-does-not-do-for-you) | ## From a chat or a mission — `connect-to-agent` Every install has a memory named **`connect-to-agent`**. It holds no documents: searching it **asks another agent**. ``` memory_search("connect-to-agent", " What is the weather in Chennai?") memory_search("connect-to-agent", "") # the name alone: B describes what it can do ``` The first word is the agent's name, the rest is the question. The model does this itself when you ask it to talk to another agent; the answer comes back headed `# Answer from agent ''`, and the model reports it as B's answer. Framework runners have the same memory built in. - **One conversation per chat.** Follow-ups in the same chat continue the conversation with B; a new chat starts a new one. The chat's own id never leaves A's machine. - **It waits for the answer** — up to 5 minutes — and returns it in the same turn. - **APIs are not asked this way.** Another agent's API (weather, news, a search corpus) is reached through a memory that points at it, exactly as before — [An API you already run](/docs/extend/api/). - **The memory is kept exactly as shipped.** An edited copy is put back at the next turn; the relay switch below is the only way to change it. ## No relay by default A turn that is **serving someone else** — another agent, or an external caller — does not ask a third agent for them. If B is answering A and B's model tries `connect-to-agent`, it gets ``` NOT ASKED: this request came from someone else (an external caller), and connect-to-agent is set not to contact other agents on anyone else's behalf. … ``` and tells A that it does not relay; A can ask that agent directly. Turns for the agent's **own user** (your workspace chat) are never affected. The check is in code, not in the prompt: a turn is "for someone else" when the agent opened it through its external door, which only external callers can reach. To let one agent relay: ```bash # in that agent's folder — its harness root: ~/.hexaeight-harness for a workspace agent, # -frontdoor/harness-root for a runner ~/.heia/runtime/harness/hexaeight-engine --connector-relay on --root ~/.heia/runtime/harness/hexaeight-engine --connector-relay status --root ``` Relaying is also subject to the policy of every agent in the chain: B needs the rules to reach the third agent, and the third agent the rules to accept B. ## An API door beside the agent's own An agent that serves an API (`external.api.enabled`) registers that address **separately**, under the `api` capability. A name lookup returns the agent's normal door; the API door is returned only when it is asked for — so an identity can hold a conversational agent and an API service at two addresses. An API-only agent (`"apiOnly": true`) registers only its API door. ## From the command line From A's folder: ```bash set -a; . ./env-file; set +a export HEIA_ASK_TIMEOUT_SECONDS=0 # wait for the work; B bounds its own turn ./hexaeight-agent-linux-x64 ask-agent --peer --capability created session s-… [external] dde-auth request from session 's-…' [/v1/messages] session ext-s-… via DDE-map -> (in B's router log) ``` > **Name lookup needs agent r30.** Earlier agents look a named peer up by *capability*, and answer > `cannot resolve a url` for an agent that publishes no tag. Upgrade, or pass `--peer-url`. ## When it fails | you see | where | it means | |---|---|---| | `cannot resolve a url for ''` | A | B is not registered — or A's agent predates r30; pass `--peer-url` | | `NOT ASKED: this request came from someone else …` | B's answer | B is answering someone else and does not relay — [by design](#no-relay-by-default). Ask the third agent directly | | `agent '' did not answer (denied)` | A's chat | B's policy refused A — B lacks `,*,inbound,allow` | | `this agent serves API requests only` | B's answer | B is an API agent (`apiOnly`); ask a runner instead | | `DENY session action from : no matching allow rule` | B's log | B lacks `,*,inbound,allow` — note the `*` | | `NOT authorized with router …: HTTP 400`, and on the router `agent_jwt decrypt failed: 'r' is an invalid start of a value` | B's log / B's router | a **prerequisite**, not a coordination rule: B has no model — its router does not admit B. Give it one ([prerequisites](#prerequisites--each-agent-works-on-its-own)) | | an answer that says a tool returned `denied` | B's answer | an API agent B called lacks `,*,inbound` / `*,,outbound` | | `{"ok":true,"accepted":"response"}` and no answer | A | A and B share one identity **and** one store — give each its own `HEIA_DIR` | ## Tested | | result | |---|---| | workspace chat → a PydanticAI runner, by name | answered, with live weather and news from two API agents | | workspace chat → a LangGraph runner, by name | answered — when the runner's policy allowed the caller; refused (`denied`) before | | a new chat → the same agent | a new conversation; the earlier chat's history not carried over | | PydanticAI runner, answering an agent, asked to ask a LangGraph runner | declined — no relay | | `connect-to-agent` edited by hand | restored at the next turn | ============================================================================== SECTION: How it works ============================================================================== ------------------------------------------------------------------------------ PAGE: Why this exists URL: /docs/concepts/problem/ ABOUT: What the API-key world assumed, what agents broke, and why the existing identity stack cannot be bent to fit. ------------------------------------------------------------------------------ ## Where we are today Every SaaS product has an API, and every API works the same way. You sign up, you are issued a **key**, and you put that key in your code. The key is your identity. Whoever holds it is you. For a world of servers calling servers, this was tolerable. The number of integrations was small, the keys were held by systems your team operated, and a human decided when each one was created. OAuth extended it: a person could click *allow*, and an application could then act for them within a scope, with a token that expires. The whole arrangement rests on one assumption — **that a human is present at the moment trust is granted**, and that what runs afterwards is code you deployed. ## What agents changed An agent breaks both halves of that assumption. It runs **without a person present**. It acts **for** someone who is not there. It decides what to do next on its own, calls other agents, and reaches whatever tools it has been given. And increasingly it is not code you wrote — it is a framework, a model, and a prompt. Now look at what we have handed it. **Every credential it might need, up front.** An agent that can read your files, query your database, and send email holds keys to all three, permanently, because nobody is around to approve each use. The blast radius of one compromised agent is the union of everything it was ever given. **No way to say who it is acting for.** An agent holding a user's token *is* that user, as far as every downstream system can tell. Ten users' work flows through one agent and arrives wearing one identity. When agents call other agents, the original requester disappears entirely by the second hop. **No idea what is actually running.** An API key proves someone was trusted once. It says nothing about whether the binary presenting it today is the one you approved, or a modified copy on a machine you have never seen. **A model in the middle of it.** The agent is driven by something that can be talked into changing its mind. Everything above stops being theoretical the moment an instruction arrives inside data the agent was asked to process. **And every vendor building their own.** Each platform ships its own agent framework, its own tool protocol, its own credential model. None of them interoperate, so an agent in one cannot prove anything to an agent in another. ## Why the existing stack cannot fix this Not for lack of quality — these are mature systems solving a different problem. | | Why it does not fit | |---|---| | **OAuth** | Assumes a browser redirect and a human to click *allow*. An agent working at 3am has neither. | | **API keys** | A bearer secret. Cannot express *"this agent, acting for this person, right now"* — only *"someone has the string"*. | | **mTLS / certificates** | Identifies a **connection**, not a message or a party. Says nothing about what is acting behind it, and carries a CA, renewals and revocation. | | **Service meshes** | Trust stops at the edge. Inside the boundary everything is assumed friendly — which is precisely where an agent operates. | | **All of them** | Identify **who**. None identify **what** — which build, which binary, which origin. | The common thread: they secure a **connection** and hand out a **secret** that stands in for you. That model was built for a world where trust was granted once, by a person, to software that did not make its own decisions. --- That is the problem. Next: [the components](/docs/concepts/components/) that answer it, and then [how they fit together](/docs/concepts/architecture/). ------------------------------------------------------------------------------ PAGE: Components URL: /docs/concepts/components/ ABOUT: Every piece of HexaEight, what it does, where it runs, and what you need to touch. ------------------------------------------------------------------------------ Six things. Most people deal with three. ```mermaid flowchart TB subgraph YOURS["Yours — you run these"] AG["AGENT
holds an identity"] EN["ENGINE
your code"] RT["ROUTER
optional"] AG <--> EN AG --> RT end subgraph THEIRS["Ours — you do not run these"] PL["PLATFORM
issues keys only"] RG["REGISTRY
a phone book"] end subgraph PHONE["Yours — on your phone"] AU["AUTHENTICATOR
your identity"] end AU -.->|"issues identities"| AG AG -.->|"asks for keys"| PL AG -.->|"publishes where it is"| RG ``` Solid lines are your data. **Dotted lines carry no message content at all.** ## The Authenticator — your phone Where a person's identity lives. It holds a **vault**, and the vault issues the **resources** that agents take. You use it twice: once to create an identity, and again whenever you approve something — a licence, or a browser app asking to talk to your agent. **You need this before anything else works.** → [The Authenticator](/docs/concepts/authenticator/) · [How identity is issued](/docs/concepts/identity/) ## The agent — your machine A single self-contained binary. It holds an identity, proves who is calling, applies your policy, and hands work to your engine. It is the only component that has to be running for anything to happen, and everything else is optional around it. The [installer](/docs/start/install/) sets it up. → [Architecture](/docs/concepts/architecture/) · [Installing](/docs/start/install/) ## The engine — the harness, or your code The engine does the work. Every agent ships with one, the [harness](/docs/concepts/harness/), so there is nothing to write. You can also put your own behind an agent: a process that takes a message and returns a reply: ``` the agent runs: your-engine -p "" [--resume ] … and reads back: {"result": "…", "session_id": "…"} ``` Any language, because it is a **process** rather than a library binding — you declare the argv and which JSON fields carry the reply. It is where the actual work happens: reading files, running commands, calling systems. The agent supplies identity, encryption, sessions and policy. You supply the capability. → [Bring your own engine](/docs/extend/own-engine/) ## The router — optional in the architecture, needed in practice Holds your model provider keys so your agents do not have to. Agents reach it with a proven identity and it forwards to whichever provider you configured. It is optional in the sense that nothing in the design requires it: an engine that does its own work and never calls a model needs no router at all. **But if your engine calls a model, you need one today** — no provider yet serves an LLM endpoint that accepts a HexaEight identity directly, so something has to hold the provider's API key, and the router exists so that it is never your agent. That may change as adoption spreads; until it does, treat the router as a step rather than a choice. The [installer](/docs/start/install/) sets one up with your provider key. Worth running when you have more than one agent, or when you would rather your provider key existed in exactly one place. → [Run your own router](/docs/router/own/) ## The platform — ours **It issues keys. That is the entire list.** It never sees ciphertext, never relays a message, never holds plaintext. Your traffic does not pass through it. The algorithm is published with sample values so this is checkable rather than a promise. You never install or configure it. An agent talks to it when it needs a key for a recipient. → [Dead Drop Encryption](/docs/concepts/dde/) ## The registry — ours, and optional A phone book. An agent publishes the URL where it can be found; another agent looks it up by name. It never sees a message. Remove it and agents that already know each other's addresses keep working — you lose discovery, not communication. → [Agents on different machines](/docs/concepts/architecture/#agents-on-different-machines) ## What you actually touch | Component | Do you run it? | Do you configure it? | |---|---|---| | Authenticator | On your phone | Create a vault once | | **Agent** | **Yes** | **Yes — policy, engines** | | **Engine** | **Built in (the harness), or your own** | **Only if it is your own** | | Router | Yes — the installer sets one up | Your provider and its key | | Platform | No | Never | | Registry | No | Only whether to publish | ## Putting it together The smallest useful system is an **agent** plus an **engine**, with an identity from the **Authenticator**. Everything else is added when you need it: a router when keys should live in one place, the registry when other agents need to find you. Now see [how they fit together](/docs/concepts/architecture/) — one request, end to end. Or skip ahead and install it: [Installing](/docs/start/install/). ------------------------------------------------------------------------------ PAGE: The harness URL: /docs/concepts/harness/ ABOUT: The AI runtime inside your agent. It runs on your machine, reaches your model only through the router, finds information through memories and follows your missions — inside a sandbox, with no model key of its own. ------------------------------------------------------------------------------ When you ask your agent something, the work is done by the **harness**: the AI runtime that ships with every agent and runs **on your machine**, next to the agent. A conversation in the workspace, building a mission and running one all run on it. There is nothing to write first — **no prompts, no MCP servers, no skill files, no instruction files.** In a conversation you just say what you need. What the harness can reach is what you give it as **[memories](/docs/extend/documents/)** — your documents, an API, another agent — and when a piece of work must be done the same way every time, you give it a **[mission](/docs/concepts/missions/)**. ## How a question travels ```mermaid flowchart LR W["Workspace
your browser"] <-->|"encrypted end to end"| A["Agent"] A <-->|"starts a turn"| H["Harness
on your machine, sandboxed"] H <-->|"searches"| MEM["Memories
documents · APIs · other agents"] A <-->|"model calls, encrypted
under the agent's identity"| R["Router
holds the provider key"] R <--> P["Model provider"] ``` 1. **You ask** in the workspace. Your browser encrypts the message for your agent, so nothing between them can read it. 2. **The agent checks** who you are and that your policy allows the request, then starts a **turn** of the harness. 3. **The harness works in a loop.** It asks the model what to do next, searches a memory or carries out a step, reads the result and asks again — until it has the answer. In the workspace you can follow it as it happens: which memory it searched, and what it found there. 4. **Every model call goes through the agent to the router.** The harness never holds a provider key. The router does, and it is the only part that talks to the provider. 5. **The answer comes back** to your browser, encrypted end to end. Content leaves your machines only for the parties you chose: the model provider, with what goes into a model call, and another agent, when you ask one. ## Where it runs | | | |---|---| | **Where** | On the same machine as the agent. The agent starts it for each turn — it is not a separate service to run or look after. | | **The program** | `~/.heia/runtime/harness/hexaeight-engine`, installed and updated together with the agent. | | **The sandbox** | Every turn runs inside one — `bubblewrap` on Linux, `sandbox-exec` on macOS — with the agent's licence and identity files hidden, so nothing a turn does, or starts, can read them. | | **The model** | Reached only through the agent and the router. There is no model key on the agent's side. | | **Search** | A small search service keeps memory search fast. It runs on the CPU — no GPU needed — and stops by itself when the agent stops. | ## What it keeps, and where Everything the harness keeps lives in **`~/.hexaeight-harness`**: | | | |---|---| | **Memories** | Each is a searchable body of documents, or a way to reach an API or another agent. | | **Missions** | Each mission's map, cards and files. | | **Conversations** | Each conversation's record, so it carries on where it left off, and its own working folder, so the files of one conversation never appear in another. | ## What a turn can do - **Search your memories** — this is how it reaches any information at all. - **Ask another agent** — through the `connect-to-agent` memory, by the agent's name, encrypted end to end. See [Two agents talking to each other](/docs/extend/agents-talking/). - **Run commands, only as allowed.** - A mission runs only the commands sealed with it — anything else is refused. - On **Machines**, every command waits for your approval. - In a conversation, a command that is not already allowed waits for your approval, and so does the first use of the web. ## Your own engine, or a framework The harness is what every agent starts with, not the only choice. A framework you already use — CrewAI, LangGraph, Pydantic AI or Agno — can run as a sealed mission on the same harness, with the same identity, memories and policy. Or you can plug in a program of your own. See [Frameworks](/docs/extend/frameworks/) and [Bring your own engine](/docs/extend/own-engine/). ------------------------------------------------------------------------------ PAGE: Architecture URL: /docs/concepts/architecture/ ABOUT: How identity, agents, engines and the router fit together, on one machine and across many. ------------------------------------------------------------------------------ You have met the pieces in [Components](/docs/concepts/components/). This is how they fit together, and what happens when a single request arrives. ## The approach Every system built this way does the same two things: it secures a **connection**, and it hands out a **secret** that stands in for you. TLS protects the pipe; an API key, a certificate or a bearer token proves that whoever holds the string was trusted at some point in the past. HexaEight does neither. **It gives every party an identity and secures the message.** That sounds like a small distinction. It is not, and five things fall out of it that the conventional stack cannot offer at all. **Identity is proven per message, not per connection.** There is no session to hijack and no token to steal, because there is no bearer credential. Successfully decrypting a message is what proves who sent it — that is not a check performed after the fact, it is a property of the message existing. **Nothing has to be issued, rotated, or revoked.** No certificate authority, no signing requests, no renewal calendar, no revocation list, no public-key directory to keep in sync. Two identities that have never met derive a shared key when they need one. **You can encrypt to someone who does not exist yet.** Address a message to a person who has never heard of HexaEight, or an agent nobody has built. When that address is later registered, it can be read. Nothing in the certificate or OAuth world can do this — there is nobody to look up and nobody to authorise. **We are not in the path of your data.** The platform issues keys and does nothing else. It never sees ciphertext, never relays a message, never holds plaintext. The working algorithm is published with sample values so you can verify that claim rather than believe it. **You can know what software is calling, not just who.** Every message identifies the executable that produced it, derived by the library rather than claimed by the sender. An approved identity running a modified binary is a case you can refuse — a distinction no API key or certificate can draw. ### And then there are agents All of that would matter for ordinary services. It matters more now, because the thing calling you increasingly is not a service. It is an agent: autonomous, acting for a person who is not present, possibly calling other agents, possibly running code you did not write. And an agent is not a chat window in front of a model. **It runs on a machine and does real work** — reading files, running commands, touching systems that exist. Which means it has to *be* somewhere, it has to hold credentials to reach a model, and something has to decide what it is allowed to do. That is the shape the architecture below is built for. ## The architecture Here is the whole thing. One request, from the moment it arrives to the moment it is answered. User App AGENT identity · policy ENGINE does the work Router Provider turn 1 · turn 2 · turn 3 … every turn goes back through the agent holds the key the answer returns only when the engine is done Every arrow is encrypted and proves who is at the other end. Read the rest of this section and that picture should stop needing explanation. ```mermaid flowchart TB U1["User"] --> AA["Another agent"] AA --> A U2["User"] --> APP["Your app"] APP --> A U3["User"] -->|"directly"| A A["THE AGENT
identity · policy · sessions"] A <--> E["THE ENGINE
runs on this machine
files · commands · systems"] A -->|"needs a model"| R["LLM Router"] E -->|"needs a model,
back through the agent"| A R --> M["Model provider"] ``` **The agent is a hub, and the engine is where work actually happens.** Everything converges on the agent — a person directly, an application with a person behind it, another agent with its own person behind it. Whoever arrives, the agent proves who they are and decides what they may do. Below it sits the engine, and this is the part usually left out of diagrams like this. An agent is not a chat window in front of a model. **The engine runs on a real machine and does real work** — reading files, running commands, touching systems that exist. That is why an agent has to be somewhere rather than being a hosted endpoint. ### The round trip nobody draws When the engine needs a model — and it usually does — it does **not** call the provider itself. It goes back through the agent, out to the router, and the answer returns the same way. ```mermaid sequenceDiagram participant U as User participant App as App participant A as Agent participant E as Engine participant R as Router participant M as Provider U->>App: asks for something App->>A: encrypted, identity proven A->>E: runs the process, argv carries the message loop until the engine has finished Note over E: work on this machine —
read a file, run a command E->>A: needs a model (turn N) A->>R: encrypted, identity proven R->>M: with the key the router holds M-->>R: completion R-->>A: encrypted A-->>E: model answer end E-->>A: the finished result A-->>App: encrypted reply App-->>U: answer ``` **The loop is the important part.** An agent does not ask a model once and hand the answer back. It works, asks, reads the answer, works again — as many turns as the job takes. The user hears nothing until the engine has finished; the model never speaks to the user directly. That looks like a long path until you ask what each hop buys. The engine **holds no provider key** — it asks the agent, so a compromised engine leaks nothing. The agent **applies policy on the way out as well as in**, so an engine cannot quietly call a model it was not meant to. The router **holds one copy of the key** for every agent you run. And the identity chain survives the whole trip: the router knows which agent asked, and the agent knows which person it was for. Route the engine straight to the provider and all four properties are gone at once. ## Agents on different machines Everything so far happened on one machine. The interesting case is two. An agent on your laptop needs to reach an agent in someone else's data centre. Conventionally that means a broker in the middle — a message bus, a SaaS relay, a queue — and now a third party carries your traffic and has to be trusted with it. **There is no broker here. The agents talk directly.** ```mermaid flowchart LR subgraph M1["Your machine"] A1["Agent A"] end subgraph M2["Their machine"] A2["Agent B"] end REG["Registry
a phone book"] A2 -.->|"1 · publishes its URL"| REG A1 -.->|"2 · looks up agent B"| REG A1 ==>|"3 · encrypted request, straight there"| A2 A2 ==>|"4 · encrypted reply"| A1 ``` The dotted lines happen once and carry no payload. **The solid lines are your data, and they go nowhere except between the two agents.** ### Being reachable without opening a firewall An agent on a laptop has no public address, so the agent solves that for you. `reach` decides how it is reachable and publishes the result: | Mode | What it does | |---|---| | `cloudflared` | Spawns a tunnel and reads back the URL it was assigned | | `tailscale` | Reachable on your private network | | `ngrok` | Spawns a tunnel | | `local` | Publishes this machine's LAN address | | `none` | Publishes nothing — the agent makes calls but accepts none | Reach is a **setting**, not a command. In `hexaeight-agent.json`: ```json "reach": { "mode": "cloudflared", "bin": "/path/to/cloudflared" } ``` Every key is in the [settings reference](/docs/reference/settings/). No port forwarding, no inbound firewall rule, no static IP. The agent registers the URL it ended up with, and re-registers periodically so a dead agent's address expires rather than being served forever. ### Why a tunnel does not weaken anything This is the part worth pausing on. A tunnel provider now carries your bytes — and it does not matter, because **the bytes are already end-to-end encrypted between the two agents**. The tunnel sees ciphertext. So does anything else on the path. Neither the tunnel provider, nor the registry, nor HexaEight can read a message or alter one without the recipient noticing. That is the practical payoff of encrypting the message rather than the connection: you can use whatever gets the packets across, including infrastructure you do not control, and it changes nothing about who can read your data. ### What the registry does and does not do It maps a **name** to a **URL**, like DNS. An agent publishes where it can be found; another agent looks it up. It never sees a message. Remove it and agents that already know each other's addresses keep working — you lose discovery, not communication. ## Next - [Identity](/docs/concepts/identity/) — where identities come from - [Dead Drop Encryption](/docs/concepts/dde/) — the primitive underneath - [Installing](/docs/start/install/) — install one ------------------------------------------------------------------------------ PAGE: Identity URL: /docs/concepts/identity/ ABOUT: Where identities come from — vault, generic resource, domain resource — and how one becomes a running agent that can encrypt to anybody. ------------------------------------------------------------------------------ This is the page that connects the phone in your hand to the agent on your machine. It is worth reading in order, because each step depends on the one before. ```mermaid flowchart LR E["1 · Your email"] --> V["2 · VAULT
on your phone"] V --> R["3 · RESOURCE
generic or domain"] R --> L["4 · LICENCE
approved by you"] L --> A["5 · AGENT
running, with an identity"] A --> D["6 · Encrypt to anyone"] ``` ## 1 · An email address Everything begins here. Your email is not a login — it is what your identity is **derived from**, which is why nobody else can end up with a name in your space. ## 2 · A vault Registered against that email, unlocked by a password you set, held on your phone in the [Authenticator](/docs/concepts/authenticator/). The vault is **you**. Agents do not have vaults; people do. ## 3 · A resource — assigned to your vault A vault holds resources. This is the step people find surprising: **a resource is assigned to your vault.** The vault is what identifies the owner, so every agent has a provable person behind it rather than being an anonymous piece of software. Two kinds. ### Generic resource The platform derives the name from your email: ``` web0-still-copper-lake18 └──────┬───────┘ └──┬──┘ always yours varies ``` The **first three words are fixed for your email address** — the same every time. The fourth comes from a list and changes per issuance. So names cannot be squatted. They are not first-come-first-served: the prefix belongs to your address, and **nobody else can ever be issued a name in your space**. Once you use one it is yours. Nothing to set up. This is the normal choice. ### Domain resource A name on a domain you control — `agent01.yourcompany.com`. **Your vault's email must be on that domain.** A vault at `you@yourcompany.com` can create `agent01.yourcompany.com`. A vault on any other domain cannot; the platform refuses. You cannot claim a domain you have no address at. Adding it returns a **DNS TXT record** to publish. That record is the proof. :::note[The TXT record is checked at licence time, not creation time] You can add the resource without the record — it simply will not become a working identity. When you approve a licence, the platform checks DNS. **No record, no licence.** An unproven claim sits there doing nothing. ::: Use a domain resource when the name matters to whoever is calling. ## 4 · A licence An agent needs one. During the [install](/docs/start/install/#4--activate-the-licence), `hexaeight-activate newtoken` asks for the **resource name** — the one from step 3 — and the licence code from your email, then shows a QR code. You scan it in the Authenticator and approve. For a domain resource, DNS is verified at this moment. **You license agents, not people.** Once the agent is running, an unlimited number of your users can authenticate against it at no cost. ## 5 · A running agent Two files land in the folder: `env-file` and `hexaeight.mac`. The agent now holds that resource's identity, and from here on it can prove who it is to anybody. :::danger[`hexaeight.mac` is machine-bound] Never copy it to another machine — that breaks the identity. To share one licence between programs on the *same* machine, hardlink it. ::: ## 6 · And now it can talk to anyone This is where [Dead Drop Encryption](/docs/concepts/dde/) starts, and where the work above pays off. Because the agent has an identity, it can derive a shared key with **any other identity** — with no introduction, no exchanged keys, and no certificate. ```mermaid flowchart LR A["Your agent"] -->|"knows the name"| K["Ask for a key"] K --> B1["An agent that exists"] K --> B2["A person you have never met"] K --> B3["An address nobody has
registered yet"] ``` All three work. The third is the one worth pausing on: you can encrypt to `someone@somewhere.com` today, when that person has never heard of HexaEight, and they can read it after they register. The recipient's identity does not need to exist when you encrypt. It needs to exist when they decrypt. ## How the pieces relate | | Belongs to | What it is for | |---|---|---| | **Email** | You | What your identity is derived from | | **Vault** | You, on your phone | Holds resources, approves things | | **Generic resource** | Assigned to your vault | An identity for an agent, name derived from your email | | **Domain resource** | Assigned to your vault | The same, but on a domain you have proved you own | | **Agent token** | Assigned to your vault | Lets a browser app authenticate to your agent | | **Licence** | A machine | Permits one agent to run there | | **Agent** | A machine | Holds a resource's identity, and proves it per message | ## Next - [The Authenticator](/docs/concepts/authenticator/) — the app, screen by screen - [Dead Drop Encryption](/docs/concepts/dde/) — what identity lets you do - [Installing](/docs/start/install/) — do all of this for real ------------------------------------------------------------------------------ PAGE: The Authenticator URL: /docs/concepts/authenticator/ ABOUT: Your identity lives on your phone. Resources are assigned to it, and that is what proves who owns an agent. ------------------------------------------------------------------------------ The HexaEight Authenticator is where a person's identity lives. It runs on Android and iOS. Everything an agent does traces back to it. An agent takes the identity of a **resource**; that resource is assigned to **your identity**; and that identity is **yours alone**. That chain is what makes the owner of any agent provable. :::note[A note on wording] The app calls what you create an **identity**, and lists them under **Identities**. Older material — and the vault icon you may see — calls the same thing a **vault**. They are the same: an email address, protected by a password, that holds your resources. ::: ```mermaid flowchart TB E["Your email address"] --> V["YOUR IDENTITY
protected by a password"] V --> G["Generic resource
web0-still-copper-lake18"] V --> D["Domain resource
agent01.yourcompany.com"] V --> C["Agent token
lets a browser or app
authenticate to an agent"] G --> A1["An agent takes
this identity"] D --> A2["An agent takes
this identity"] ``` > **Getting started?** [Installing](/docs/start/install/) has the short version: install the > app, create an identity, add a resource. This page is the full reference — every screen, agent > tokens, and approving a licence. ## Creating your identity, screen by screen Two steps, a couple of minutes. ### 1 · Create your identity The Create your identity screen: an email address field, an optional display name field, and a Continue button. Enter your email address. **This is what your identity is derived from**, and everything else follows from it — so use an address you intend to keep. A **display name** is optional. It is a label for your own use — *Work*, *Personal* — and it hides your email address on screen. :::caution[Choose the address carefully] The app is explicit about this: *"Use a real, permanent email — temporary addresses aren't allowed. An identity can't be deleted without reinstalling the app, so double-check the address."* :::
### 2 · Verify it and set a password The Verify your email and set a password screen, explaining that a verification code will be emailed containing a QR code. One email check proves the address is really yours, then you set a password to protect the identity. A verification code arrives from `DONOTREPLY@hexaeight.com` — **check spam** if you do not see it. The email contains a QR code: - **Scan it** from another device, or - if you are reading the email on the same phone, **tap the link below the QR code** and the app finishes automatically. :::note At most **three** verification emails can be sent, so do not request them repeatedly. :::
That is your identity created. It lives on this phone, and it is what everything else hangs off. ## Resources — giving agents and devices an identity The Resource Tokens help screen: Give agents and devices an identity. The app puts it well: > Your identity isn't just for logging in — it's the starting point for giving **everything else** an > identity too. > > Create a **Generic Resource** for an app, AI agent, IoT gadget or door lock you authorize to act > for you; create a **Domain Resource** for your websites and servers. Each becomes a trusted, > verifiable entity — and you can grant or revoke that trust whenever you like. When `hexaeight-activate newtoken` asks for a **resource name**, this is what it means. The agent takes the identity of that resource, and the resource is assigned to you.
### Generic resource *"Let apps act on your behalf."* The platform derives the name from your email address: ``` web0-still-copper-lake18 └──────┬───────┘ └──┬──┘ always yours varies ``` The **first three words are derived from your email**, so they are the same every time you create one. The fourth comes from a fixed list and changes per issuance. This is why names cannot be squatted. They are not first-come-first-served — the prefix belongs to your address, so **nobody else can ever claim a name in your space**. Once you use one, it is yours. Generic resources need nothing set up. This is the normal choice. ### Domain resource *"Admins only — needs DNS access."* A resource on a domain you control, like `agent01.yourcompany.com`. Two things gate it, and both matter: **Your identity's email must be on that domain.** An identity registered at `you@yourcompany.com` may add `agent01.yourcompany.com`. An identity on a different domain cannot — the platform refuses. You cannot claim a domain you have no address at. **A TXT record proves it.** When you add the resource the app gives you a DNS TXT record to publish. :::note[When the TXT record is actually checked] Not when you add the resource — when a **licence is granted**. Every agent needs a licence, and you authorise one by scanning a QR code in the app. At that moment the platform checks the record. **No record, no licence.** So an unproven claim sits there doing nothing; it does not become a working identity until DNS backs it. ::: Use a domain resource when the name matters to whoever is calling — an agent your customers or partners reach should look like yours. ### Agent token Listed in the app as *Captcha Token*. It is what lets a **browser, SPA or user SDK authenticate itself to an agent**. The mechanism is simpler than it sounds, because **your phone and the agent already have an encrypted channel between them** — they both have HexaEight identities, so they can talk directly. Everything else follows from that. It works the way a login code does, and you have done this before. ```mermaid sequenceDiagram participant You as You participant App as The app
(browser / SPA) participant A as Your agent participant P as Platform participant M as Your phone You->>App: open it and sign in App->>A: presents the agent token A->>P: who is this, and let them
approve on their own device P->>M: sends a code — to the phone only Note over M: you read the code
on your phone You->>App: type the code in App->>A: here is the code Note over A: matches — this app is
acting for a real, present person A-->>App: you are in ``` **You read the code on your phone and type it into the app.** Same shape as any login code, and the reason it works is the same: the code arrives on a device only you hold. The app never receives the code from anywhere except **you**. It cannot request it, cannot guess it, and cannot obtain it by compromising the agent — the platform sends it to your phone and nowhere else. So the app gets in because **you were there and vouched for it**, not because it was holding a secret that could have been stolen. ## Approving a licence This is the step of the [install](/docs/start/install/#4--activate-the-licence) that needs a person. ```mermaid sequenceDiagram participant T as hexaeight-activate newtoken participant P as Platform participant M as Authenticator T->>T: asks for the resource name T->>T: asks for the licence code from your email T->>M: shows a QR code M->>M: you scan it and approve the resource P->>P: domain resource? verify the DNS TXT record P-->>T: licence granted T->>T: writes env-file and hexaeight.mac ``` The licence is bound to that machine. `hexaeight.mac` is machine-bound and **must never be copied** to another machine — to share one licence between programs on the *same* machine, hardlink it. ## Which do I need? | You want | Use | |---|---| | An agent for yourself, on your own machine | Generic resource | | An agent your customers or partners reach by name | Domain resource — you will need DNS access | | A browser app or SPA that talks to your agent | Agent token | You can hold as many as you like under one identity. Set one as the default so authentication uses it automatically. ------------------------------------------------------------------------------ PAGE: Dead Drop Encryption URL: /docs/concepts/dde/ ABOUT: The primitive underneath everything — how two identities that have never met derive a shared key, and why we never see your data. ------------------------------------------------------------------------------ Everything else rests on this. You do not need it to build, but it is what the claims stand on. ## The primitive: Dead Drop Encryption Two parties who both have HexaEight identities can derive a shared key **without exchanging public keys, without a certificate, and without ever having met**. The platform issues each side their half when they need it. Two consequences are worth stating loudly, because they are unusual. ### The platform is not in the data path **The platform issues keys. That is all it does.** It never sees your ciphertext, never relays a message, and never holds plaintext. Your messages do not travel through it. This is a claim you should not have to take on trust — so the working algorithm is published with sample key values, and you can run the encryption yourself and confirm what it does. ### You can encrypt to someone who does not exist yet You can encrypt a message to `alice@newcompany.com` **today**, when Alice has never heard of HexaEight, has no account, and no software installed. When she later registers that address, she can decrypt it. The same works for agents: address a request to `agent01@somedomain.com` before that agent exists. ```mermaid flowchart LR S["You"] -->|"encrypt to
alice@newcompany.com"| C["Ciphertext"] C -.->|"sits anywhere
email · S3 · a queue"| L["Later"] L --> A["Alice registers
that address"] A --> D["She decrypts it"] ``` Nothing in the conventional identity stack does this. With certificates you cannot encrypt to somebody who has no certificate; with OAuth there is nobody to authorise. Here the *address itself* is enough. :::note[Two paths, and the hour applies to only one] **Collecting a key directly.** The platform serves a given key for a window of about an hour, so a recipient taking that path collects their half inside it. Once collected, it is **permanent**. **Reaching somebody who may act next week.** The message itself carries what the destination needs to identify the sender — the *first-communication JWT*, a token minted with the message rather than fetched from anywhere. There is no window to miss, which is what makes "encrypt to someone who has not registered yet" hold in the general case. So both statements on this page are true: the address is enough, and the hour is a collection window on one of the two paths — not a deadline for the recipient to exist. ::: ### Transport stops mattering Because encryption is end to end, **what carries the bytes is irrelevant**. Plain HTTP, a queue, a relay, a file on disk. Nothing in the middle can read or alter a message, so nothing in the middle has to be trusted. The agent is not giving you a secure channel; it is making the channel irrelevant. ## The primitives, for those who want them :::note[Skip this section if you are building rather than evaluating] Nothing below is needed to deploy an agent or write an engine. It is here for people who want to know what the claims above rest on. Every item names the method that implements it. ::: Five operations carry everything else. ### Getting a key for a recipient ``` FetchAskAsync(recipient, kgt) the implementation ``` Takes the recipient as a **string** and a key generation time. There is no lookup of a directory, no certificate exchange, and **no requirement that the recipient exists** — which is exactly why you can encrypt to an address nobody has registered yet. The call returns your half of the shared key. Answers are cached locally, so a repeated send to the same recipient in the same window does not call out again. ### The time window ``` CurrentKgt() minutes since epoch, rounded down to 15 ``` Keys are derived per **fifteen-minute bucket**. Both sides derive the same bucket independently, so no negotiation is needed. The platform serves keys for a given bucket for a limited period — this is the practical window mentioned above, and the reason a recipient must collect their half reasonably promptly. Once collected, the key does not expire. ### Sealing to one recipient ``` EncryptEnvelopeAsync(recipient, body, kgt, ...) the implementation DecryptEnvelopeAsync(envelope, pinAsk) the implementation ``` The envelope carries who sent it, who it is for, and the window it was made in. Decryption is what proves the sender: producing a message that opens under the recipient's half required the sender's half, which only that identity could obtain. `DecryptEnvelopeAsync` returns the sender and the authorization decision alongside the body, so the receiving code does not have to trust anything the message claims about itself. ### Sealing to several recipients ``` MultiEncryptMessageUsingSharedKeyAsync(recipients, message, sharedKey) the implementation ``` One ciphertext, several recipients, each able to open it with their own key. This is what relays and approval chains are built from. ### Keys an identity holds for itself ``` FetchInternalKeyAsync(seed) the implementation ``` A key derived from **this identity plus a seed**, used to encrypt things at rest that only this identity should read — its policy, its session store, its engine configuration. Nobody else can derive it, so a stolen file is inert. ### What is not here There is no key exchange step, no certificate validation, no revocation list, and no public-key directory. The absence is the point: those are the parts of the conventional stack that cost the most to operate. ## Next - [Identity](/docs/concepts/identity/) — where the identities come from - [Architecture](/docs/concepts/architecture/) — what is built on this ------------------------------------------------------------------------------ PAGE: Trust and permission URL: /docs/concepts/trust/ ABOUT: Nothing works until a rule says so. What the gates are, where the rules live, and how to prove enforcement is actually on. ------------------------------------------------------------------------------ Once rules exist, the default is **deny**: anything not permitted is refused, and every capability is something you granted on purpose. **Until the first rule exists, nothing is enforced.** A freshly activated agent is permissive by design, so that installing or upgrading one can never lock an operator out of their own machine. **Writing the first rule is how you opt in.** The [installer](/docs/start/install/) does it for you: it writes a starting policy that admits only you. The boot line tells you which state you are in: ``` [licence] personal licence - N policy rule(s) in force ``` **`0 policy rule(s)` means nothing is being enforced.** Any other number means deny-by-default is live. Once it is on, the arrangement is the opposite of an API key, where the key means "everything this key can reach" and scoping it down is extra work nobody does. ## The one that locks you out ```json { "owner": "you@example.com" } ``` **Without `owner` in `hexaeight-agent.json`, no policy is enforced at all** — every rule present, none applied. The boot line tells you which state you are in: ``` [licence] personal licence - 10 policy rule(s) in force - agent may be exposed normally ``` `0 policy rule(s)` means the door is open. Check it after every change. ## What a rule says ``` , , , allow|deny ``` | part | is | |---|---| | principal | who is acting — a person's email, an agent's name, or `*` | | object | what they are reaching — an agent name, `op:*`, `editor:*`, or `*` | | direction | `inbound` (reaching this agent) or `outbound` (this agent reaching out) | Deny beats allow, so a deny holds even where a wildcard would admit. ### The rows people miss | rule | without it | |---|---| | `,op:*,outbound` | sign-in works and **skill runs fail** with `bind said 404` | | `,*,inbound` | the router's own replies come back as that identity and are refused | | `*,,outbound` | engines cannot reach the router — the sender is `engine:`, so this must be `*` | > **Never write a blanket `*,*,inbound,deny`.** It outranks everything else you wrote, including > the rules that let you in. ## Three stores, one turn An external turn is authorised **three times, by three components**, each with its own rule list: | # | who | where the rules are | |---|---|---| | 1 | the serving agent | its own folder | | 2 | the router, relay gate | the router's sealed policy | | 3 | the router, model gate | the same file | A rule in one is invisible to the other two. The router's file is sealed under the router's key, so the agent CLI cannot write it — and the router **reads it once at startup**. Restart after changes. ## Vouching — acting for a person An agent acting **on behalf of** someone is a separate, explicit grant: ```bash SUB=$(printf 'person@example.com' | sha512sum | cut -d' ' -f1) ./hexaeight-agent-linux-x64 vouch allow --caller --subject "$SUB" ``` The subject is the **hash**, not the address. This is what makes a turn bind to a *person* rather than to the agent, which two of the three gates require. ## Containment — what a turn can touch Identity and policy decide *who*. Two more mechanisms decide *what*. **The jail.** Every engine turn runs with the identity folder masked: ``` [hexaeight-agent] engine jail: ON (bwrap) masking [/home/you/heia-agent] ``` A turn cannot read `env-file` even though it is running as the agent. The mechanism differs by platform — **bwrap** on Linux, and on Windows because the agent runs under WSL; macOS uses its own sandbox. Check yours reports as working: ```bash hexaeight-activate sandbox ``` **The command set.** Shell access is denied unless a mission explicitly carries a cmdset: ``` [exec-policy] mission 'My_Workflow': enforce ON, NO cmdset — shell denied (memory/skills/native only) ``` ## Prove it rather than assume it A rule that is present but does not match reads as protection and is not. ```bash hexaeight-activate list-policy --subject person@example.com ``` That prints **what the enforcer decides**, not what is written down. It is the only check worth trusting. The baseline output also shows a deliberate failure: ``` inbound nobody@example.invalid -> DENY ok ``` A test that expects a refusal, and gets one. ## What this means for a security review - **No API keys** to issue, rotate, escrow or leak — identity is cryptographic and machine-bound - **Default-deny**, so the blast radius of a new agent is nothing until you widen it - **Revocation is a policy edit**, not a key rotation across every consumer - **Binaries gate on published hashes**, fetched at runtime — a bad build is withdrawn centrally - **Prompt injection is bounded by policy, not by prompting** — a caller of a sealed mission cannot choose the procedure, and the fence limits what the procedure may touch ------------------------------------------------------------------------------ PAGE: HexaEight and OAuth URL: /docs/concepts/oauth/ ABOUT: What each does, how they work together, and how to link your agent to your company's OAuth app — so other agents can check, on every message, that your company still stands behind it. ------------------------------------------------------------------------------ OAuth and HexaEight answer different questions, and they work side by side. | | OAuth | HexaEight | |---|---|---| | **The question it answers** | may this application act for this user, within these scopes? | who sent this message, and may they reach this agent? | | **What it issues** | tokens, from your identity provider | identities — for people from the Authenticator, for agents bound to a machine | | **The message itself** | protected by TLS, hop by hop | encrypted end to end between the two identities | | **Where it shines** | sign-in, delegation with scopes, central revocation, familiar tooling | messages that pass through other systems unread, agents that have never met, no provider in the path of a message | Most deployments use both. Your identity provider keeps doing what it already does — sign-in, provisioning, revocation — and HexaEight carries the messages between agents and proves who sent each one. ## Where they meet 1. **Your company vouches for your agent.** Link the agent to your company's OAuth app, and other agents check on every message that your company still stands behind it. [Below.](#link-your-agent-to-your-companys-oauth-app) 2. **Your agent calls APIs that expect OAuth.** An API you put behind an agent can use its own OAuth client. [Below.](#apis-that-expect-oauth) 3. **Your API learns who asked.** When another agent's request reaches your API through your agent, the call says which agent asked. [Below.](#your-api-learns-who-asked) ## Link your agent to your company's OAuth app **What you get:** every agent your agent writes to can check, on every message, that your company still stands behind it. Disable the app in your identity provider, and other agents refuse this one once the token it holds is used up — within an hour by default. **How it works** - Your agent gets a token from your company's OAuth app (client credentials) and carries it inside each encrypted message it sends to another agent. - The receiving agent looks up a DNS record on your agent's name, checks the token against your identity provider's published signing keys, and checks a rule of its own that names your agent and your client ID. - **The token must grant nothing.** It proves only that the agent is still authorised — no app roles, no API permissions, no scope beyond the one made for this proof. A token that grants more is refused and never sent. - The receiving agent removes the token before anything else sees the message, and records every check in its [audit trail](/docs/concepts/compliance/). - Once a receiving agent has seen your agent linked, it keeps requiring the token, even if a later DNS lookup fails. **On the sending agent** 1. In your identity provider, create an app for this proof, with a **dedicated audience** that is not a real API — for example `api://hexaeight-proof`. 2. From the agent's folder (on macOS the binary is `hexaeight-agent-osx-arm64`): ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json oauth-link set ``` It asks for the issuer, the client ID, the audience and the secret — the secret at a prompt that does not show it. It fetches a test token first, and **saves nothing** if that token grants anything. 3. Publish the DNS record it prints, as a TXT record on your agent's name: ``` hexaeight-oauth=v1; iss=; client_id=; aud= ``` 4. Check it: ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json oauth-link status ./hexaeight-agent-linux-x64 hexaeight-agent.json oauth-link dns ``` **On each receiving agent**, allow your agent with that client ID — by its exact name, or a domain such as `*.yourcompany.com` (a bare `*` never counts): ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json --add-rule ",clientid:,inbound,allow" ``` **Settings** | Command | What it sets | |---|---| | `oauth-link renew <1-60>` | how often the sending agent fetches a new token — 60 minutes by default | | `oauth-link max-age <5-120>` | on a receiving agent: the oldest token it accepts — 120 minutes by default | | `oauth-link off` · `on` | stop or resume sending the token | | `oauth-link except add ` | an agent the token is never sent to | | `oauth-link test` | fetch a token now and check it | ## APIs that expect OAuth When you [put an API behind an agent](/docs/extend/api/), the route can carry its own OAuth client: the agent fetches a token with client credentials and sends it with every call. ```bash ./hexaeight-agent-linux-x64 hexaeight-agent.json add-api --name --url \ --oauth-issuer --oauth-client-id --oauth-scope ``` 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. Before you use this workspace: the terms, with I understand and accept.

Consent. Each person accepts the terms before using the workspace. The acceptance is kept, sealed, with the exact words and their hash.

The message box, with the notice underneath that you are working with an AI system.

The AI notice. Under every message box, people are told they are working with an AI system.

The Advanced view of a chat: the memory_search step with the passages it found and the document each came from, then the answer.

Every step shown. The Advanced view lists each step the agent took and the sources it used.

A drafted HexaPilot job with its steps, and Ready with Start and Decline.

Nothing runs unasked. A drafted job does nothing until a person presses Start.

Agent keys: a key name and a value field, sent encrypted and never shown again.

Secrets stay sealed. An API key is sent encrypted and never shown again.

Terminal: one conversation in the audit trail, with the email addresses blurred.

The record. One conversation in the audit trail: who, when, which engine and model, and the question and the reply only as hashes.

Terminal: the HIPAA Security Rule checklist from the compliance report.

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. Terminal: audit-export for one session prints eight JSON lines: session.user, then for each of two turns turn.start, turn.end and the router's llm.call rows, each with its time, sequence number and the hash of the entry before it. The email addresses are blurred. 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. Terminal: the report header with the agent name, the time it was generated, the running build with its version and binary hash, and a heartbeat from each of the three processes. The host name is blurred. Terminal: Controls in force, as recorded by the running agent at its start: approved builds, reach, identity, licence, workspace sign-in, engine isolation, engines, routing, audit trail, SIEM sink, OAuth link, data at rest, idle sign-out, privacy notice; then control files changed since the start, and three consent records with the email addresses blurred. **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: Terminal: the HIPAA Security Rule checklist, each line with its status (In place, Partial or Organisation), the section of the rule and the evidence. Terminal: the EU AI Act checklist, from AI literacy and risk classification to logs, human oversight, robustness, transparency and the inventory of models in use. 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: Terminal: the access review header, workspace sign-in by one named owner, and the twelve policy rules. Email addresses and other agents' names are blurred. Terminal: 32 signed-in sessions, newest activity first, each shown by a short hash, and the number of distinct people. The email addresses are blurred. Terminal: the four machines this agent can reach, with every name and address blurred except the local one, whether other software can call it, and the agents it may reach or be reached by, with other agents' names 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: Terminal: the router's report header, running build, heartbeat, trail, model calls and tokens over the last 30 days, security events, the controls in force at its start, and the one control file that changed. Terminal: the router's eleven upstreams, each with the provider and region inferred from its address and whether its key is sealed. Two private Azure resource names are blurred. Terminal: the router's SOC 2 checklist: who may use which model, upstream credentials, data in transit, monitoring of model use, change management, confidential content kept out of logs and vendor management. ## 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…