# HexaEight

> Cryptographic identity for AI agents, applications and people. Every party gets an identity;
> every message 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. It proves who is calling, decides whether they are allowed, and
hands the work to an **engine** — either the built-in runtime (memories, sessions, a tool loop) 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.

## Facts an integration usually needs

- 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. Writing the first rule is how you opt in to deny-by-default.
- 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 **mission** is a written method the agent follows: a map, 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.
- 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

Do not work from this index. There is a file written for exactly that job, as procedure cards — one
per step, each with the exact commands, marked by operating system:

    https://www.hexaeight.com/llms-install.txt

Read it first, tell the person which OS section applies, and ask them for **the licence code and the
provider API key** before you start — those two are the only things you cannot do yourself.

Three ways an install ends up looking finished while no turn ever answers, all covered there:
macOS binary not re-signed after download (`Killed: 9`), macOS jail masking the folder instead of the
three credential files (`EPERM`), and engines sealed to an `-oai-` route
(`400 modelCode: does not exist`).

## Sections


### Start here

- [HexaEight Documentation](/docs/): what this is, and the shortest path
- [Install with an agent](/docs/llm-install/): POINT AN AGENT AT THIS TO INSTALL — the whole procedure as cards, per OS
- [Installing](/docs/start/install/): installing, by hand or by agent, with the per-OS differences
- [Before you begin](/docs/start/before-you-begin/): machine, .NET, the Authenticator app, a licence
- [1 · Your identity starts on your phone](/docs/start/your-identity/): your email becomes an identity on your phone
- [2 · Install your agent identity](/docs/start/identity/): bind it to a machine; an agent exists
- [3 · Connect a model](/docs/start/model/): a router holds the model keys; the agent starts
- [4 · Connect the workspace](/docs/start/workspace/): the browser console, and what each pane does
- [5 · Your first conversation](/docs/start/first-conversation/): confirm it works, and diagnose it if not

### Extending an agent

- [Documents it can search](/docs/extend/documents/): give it documents to search (memories)
- [An API you already run](/docs/extend/api/): put an HTTP service you already run behind it
- [Bring your own engine](/docs/extend/own-engine/): put your OWN code behind it: a process, declared argv in, JSON out
- [What a mission is](/docs/concepts/missions/): WHAT A MISSION IS: map, cards, fence, files, command set; guided vs direct; its life from workspace to runner
- [Frameworks](/docs/extend/frameworks/): agent frameworks behind an agent: CrewAI, LangGraph, PydanticAI, Agno as one-command sealed missions (enable); the rest as process engines
- [Quick start — a framework for outside callers](/docs/extend/framework-quickstart/): QUICK START: a framework behind a runner for outside callers — enable, add-runner, share documents and APIs as memories only, call it
- [CrewAI](/docs/extend/frameworks/crewai/): CrewAI: sealed mission via enable + process engine
- [LangGraph](/docs/extend/frameworks/langgraph/): LangGraph: sealed mission via enable + process engine
- [Pydantic AI](/docs/extend/frameworks/pydanticai/): Pydantic AI: sealed mission via enable + process engine
- [Agno](/docs/extend/frameworks/agno/): Agno: sealed mission via enable + process engine
- [AutoGen](/docs/extend/frameworks/autogen/): AutoGen: process engine; sealed mission coming soon
- [Google ADK](/docs/extend/frameworks/googleadk/): Google ADK: process engine; sealed mission coming soon
- [LlamaIndex](/docs/extend/frameworks/llamaindex/): LlamaIndex: process engine; sealed mission coming soon
- [OpenAI Agents SDK](/docs/extend/frameworks/openai-agents/): OpenAI Agents SDK: process engine; sealed mission coming soon
- [Semantic Kernel](/docs/extend/frameworks/semantickernel/): Semantic Kernel: process engine; sealed mission coming soon
- [smolagents](/docs/extend/frameworks/smolagents/): smolagents: process engine; sealed mission coming soon
- [A procedure it follows](/docs/extend/procedure/): a written procedure it follows every time (guided missions), field by field
- [Your own users](/docs/extend/your-users/): let your users in: BYOA, or alt-auth
- [Other software calling it](/docs/extend/external-callers/): let another company's software call it
- [Two agents talking to each other](/docs/extend/agents-talking/): TWO AGENTS TALKING: memory_search("connect-to-agent", "<agent> <question>") asks another agent by name (registry, DDE); no relay by default (--connector-relay); every rule on both agents and on the router(s); errors and fixes

### Model access

- [Run your own router](/docs/router/own/): run your own router; write its rules
- [Forward to an external router](/docs/router/forward/): forward to someone else's router, keeping your user list private

### How it works

- [Why this exists](/docs/concepts/problem/): why the existing stack cannot do this
- [Components](/docs/concepts/components/): the parts, one at a time
- [The harness engine](/docs/concepts/harness/): THE HARNESS ENGINE: the built-in runtime — memories, sessions, tool loop, missions, command gate, jail, harness root
- [Architecture](/docs/concepts/architecture/): how they fit together
- [Identity](/docs/concepts/identity/): where identities come from
- [The Authenticator](/docs/concepts/authenticator/): the phone app, screen by screen
- [Dead Drop Encryption](/docs/concepts/dde/): the encryption primitive
- [Trust and permission](/docs/concepts/trust/): permission, containment, and what is enforced when
- [Why not OAuth](/docs/concepts/why-not-oauth/): how this differs from tokens
- [Compliance](/docs/concepts/compliance/): what an auditor will ask
- [Glossary](/docs/concepts/glossary/): every term in one place

### Operating it

- [Policy](/docs/operate/policy/): who may do what
- [Lifecycle](/docs/operate/lifecycle/): start, stop, upgrade, revoke
- [Capacity](/docs/operate/capacity/): measured cost per turn, and sizing
- [Troubleshooting](/docs/operate/troubleshooting/): real error messages and what each means
- [hexaeight-activate — the whole CLI](/docs/reference/activate/): every hexaeight-activate command
- [Settings — every file, every key](/docs/reference/settings/): every setting, and which file it lives in

## Full text

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