# HexaEight

> An AI agent with its own identity, running on your own machine. Every party — a person, an agent,
> a service — gets a cryptographic identity; every message between them is encrypted end to end and
> proves who sent it. No API keys, no certificates, no key exchange, and the recipient need not be
> online.

This is the machine-readable index. If you are an agent helping someone install or integrate
HexaEight, read the sections in the order given: each assumes the one before it.

## What it is, in one paragraph

An **agent** is a running identity on its owner's machine. It proves who is calling, decides whether
they are allowed, and hands the work to an **engine** — usually the built-in **harness** (memories,
missions and a tool loop, run in a sandbox), or a process you wrote, which the agent runs with an
argv you declared. Agents never hold model credentials; they ask a **router** for a named route, and
the router holds the keys and decides who may use which model. Identity lives on the owner's phone,
in the **Authenticator**, and every agent is a **resource** assigned to a person's identity — which
is what puts a provable person behind it. People use an agent through the **workspace**, a browser
interface served from the same machine.

## Facts an integration usually needs

- The one-command installer sets up the licence, a router, the agent, the workspace and start at
  login: `curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash`,
  run twice from an interactive terminal. Folders: `~/hbia-agent` (licence only), `~/heia-router`,
  `~/heia-agent`. Ports: 5100 router, 8770 agent, 5620 workspace. Manage with
  `heia status|restart|logs`.
- Identity files are `env-file` and `hexaeight.mac`, both **machine-bound**. Never copy them to
  another machine; hardlink them when one machine needs them in two folders.
- A resource's **password, licence code and `hexaeight.mac` are tied together**. The password
  cannot be changed. Encrypting or decrypting needs the identity, the password AND the ASK.
- **Until the first policy rule exists, nothing is enforced.** `0 policy rule(s) in force` at boot
  means the door is open. The installer writes a baseline that admits only the owner.
- A person appears in policy as `sha512(their email)`, never the address.
- The router's only config file is `upstreams.yaml`; it holds the upstreams *and* settings such as
  `requireIdentifiedCaller`. There is no `router.yaml`.
- Start order is **router, then agent, then workspace**. An agent started first reports a licence
  error that has nothing to do with the licence.
- On Windows, run everything under WSL.
- A **memory** is how an agent reaches information: documents, an API, or another agent
  (`connect-to-agent`), searched by name.
- A **mission** is a written method the agent follows: a flowchart of capability cards, a fence,
  optionally files it carries and a command set sealed in the agent. A **direct** mission hands every
  message to one approved command with no model step — that is how `hexaeight-activate enable
  crewai|langgraph|pydanticai|agno` runs a framework.
- Every agent keeps a sealed, chained **audit trail** (`audit-export`, `audit-sink`) and produces
  read-only **compliance reports** (`--compliance-info`, `--access-review`).
- The agent opens every encrypted store before it starts; one that does not open stops the start, with
  the reason in `startup-check.json`.
- A **runner** sees only its own mission until a memory is shared into it
  (`hexaeight-activate runner-memory --share <name>`). `restart agent` acts on the current folder only.

## If you are here to INSTALL it

The person installs it with one command, in their own terminal, run twice; the licence step in
between is theirs:

    curl -fsSL https://raw.githubusercontent.com/HexaEightTeam/hbia-agent/main/install.sh | bash

Before the first run they need the HexaEight Authenticator on their phone, with their email identity
and a resource for the agent, and a licence code from store.hexaeight.com. The installer asks its
questions on the terminal and reads the provider key there without showing it. Walk them through
https://www.hexaeight.com/docs/start/install/.

## Sections

### Get started

- [HexaEight Documentation](/docs/): 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.
- [Installing](/docs/start/install/): 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.
- [What gets installed](/docs/start/what-gets-installed/): 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 agent

- [Memories](/docs/extend/documents/): How your agent reaches information — your documents, documents another agent serves, an API, another agent — all as memories it searches by name, and cites.
- [Missions](/docs/concepts/missions/): 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.
- [A procedure it follows](/docs/extend/procedure/): 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.
- [An API you already run](/docs/extend/api/): 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.
- [Bring your own engine](/docs/extend/own-engine/): 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.
- [Frameworks](/docs/extend/frameworks/): Ten agent frameworks, verified end to end through the Identity Agent with zero code changes to any of them.
- [Quick start — a framework for outside callers](/docs/extend/framework-quickstart/): 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.
- [CrewAI](/docs/extend/frameworks/crewai/): CrewAI as a sealed mission — identity, policy and approvals by HexaEight, the crew by CrewAI. Also verified as a process engine.
- [AutoGen](/docs/extend/frameworks/autogen/): Verified through the Identity Agent with no code changes. Session persistence by save_state / load_state blob.
- [Agno](/docs/extend/frameworks/agno/): Agno as a sealed mission — identity, policy and approvals by HexaEight, the agent by Agno. Also verified as a process engine.
- [Google ADK](/docs/extend/frameworks/googleadk/): Verified through the Identity Agent with no code changes. Native DatabaseSessionService persistence.
- [LangGraph](/docs/extend/frameworks/langgraph/): LangGraph as a sealed mission — identity, policy and approvals by HexaEight, the agent by LangGraph. Also verified as a process engine.
- [LlamaIndex](/docs/extend/frameworks/llamaindex/): Verified through the Identity Agent with no code changes. Context serialize and restore.
- [OpenAI Agents SDK](/docs/extend/frameworks/openai-agents/): Verified through the Identity Agent with no code changes. Native SQLiteSession persistence.
- [Pydantic AI](/docs/extend/frameworks/pydanticai/): Pydantic AI as a sealed mission — identity, policy and approvals by HexaEight, the agent by Pydantic AI. Also verified as a process engine.
- [Semantic Kernel](/docs/extend/frameworks/semantickernel/): Verified through the Identity Agent with no code changes. ChatHistory serialize and restore.
- [smolagents](/docs/extend/frameworks/smolagents/): Verified through the Identity Agent with no code changes. Session persistence by wrapper-owned transcript.
- [Policy](/docs/operate/policy/): The rules that decide who may reach an agent and what it may reach — and how to prove they are in force.

### The workspace

- [The workspace](/docs/start/workspace/): 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 router

- [The router](/docs/router/overview/): 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.
- [Run your own router](/docs/router/own/): You hold the provider keys. One place to rotate them, one place that decides which agent may use which model, and per-caller accounting.
- [Serve models to agents](/docs/router/providers/): 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.

### Serving other people

- [Your own users](/docs/extend/your-users/): 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.
- [Other software calling it](/docs/extend/external-callers/): Let someone else's software call your agent — over DDE, bound to a person, running one sealed mission it cannot choose.
- [Two agents talking to each other](/docs/extend/agents-talking/): 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.

### How it works

- [Why this exists](/docs/concepts/problem/): What the API-key world assumed, what agents broke, and why the existing identity stack cannot be bent to fit.
- [Components](/docs/concepts/components/): Every piece of HexaEight, what it does, where it runs, and what you need to touch.
- [The harness](/docs/concepts/harness/): 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.
- [Architecture](/docs/concepts/architecture/): How identity, agents, engines and the router fit together, on one machine and across many.
- [Identity](/docs/concepts/identity/): Where identities come from — vault, generic resource, domain resource — and how one becomes a running agent that can encrypt to anybody.
- [The Authenticator](/docs/concepts/authenticator/): Your identity lives on your phone. Resources are assigned to it, and that is what proves who owns an agent.
- [Dead Drop Encryption](/docs/concepts/dde/): The primitive underneath everything — how two identities that have never met derive a shared key, and why we never see your data.
- [Trust and permission](/docs/concepts/trust/): Nothing works until a rule says so. What the gates are, where the rules live, and how to prove enforcement is actually on.
- [HexaEight and OAuth](/docs/concepts/oauth/): 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.

### Security and compliance

- [Compliance](/docs/concepts/compliance/): What the architecture provides toward GDPR, HIPAA, DPDPA and the EU AI Act — what it does not provide, and what remains yours.
- [Audit trail](/docs/operate/audit/): 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.
- [Compliance reports](/docs/operate/compliance-reports/): 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.
- [Admin settings](/docs/operate/admin-settings/): 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.

### Running it

- [Lifecycle](/docs/operate/lifecycle/): Start, stop, update, roll back and renew the licence, and where the records of what happened are kept.
- [Encrypted stores](/docs/operate/stores/): 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.
- [Capacity](/docs/operate/capacity/): What one machine actually serves, measured rather than estimated.
- [Troubleshooting](/docs/operate/troubleshooting/): The real messages, what each one actually means, and the fix. Most of these name something other than the cause.

### Reference

- [hexaeight-activate — the whole CLI](/docs/reference/activate/): 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.
- [Settings — every file, every key](/docs/reference/settings/): Which file each setting lives in, what it does, and which tool changes it. The answer to "where does this go?
- [Glossary](/docs/concepts/glossary/): Every term the docs use, in one place — agent, runner, engine, mission, memory, route, vouch, subject, and the rest.
- [For AI agents](/docs/llm/): A machine-readable index of these docs, and the full text in one file — for an agent helping someone install or integrate HexaEight.

## Full text

Every page, concatenated: [/llms-full.txt](/llms-full.txt)