# HAAEEP and Collaboration

> **Companion summary — target architecture.** This page condenses
> [`../docs/08-ecosystem/haaeep-and-collaboration.md`](../docs/08-ecosystem/haaeep-and-collaboration.md),
> the canonical description of the **High Assurance Agent Edge Environment
> Platform (HAAEEP)**: a target architecture that Open-IOV exists to enable,
> and the collaboration models around it. HAAEEP is a proposal and a roadmap,
> not a shipped product. When this page and the docs tree disagree, the docs
> tree wins. Front door: [`../docs/README.md`](../docs/README.md).

Status: 2026-10-12, tree `master @ 2f066727`. Tags: `[proposal]` architecture and roadmap; `[target]` milestone to reach; `[goal]` end state; `[design]` integration point designed, not built.

## 1. What HAAEEP is

An AI agent harness (Claude Code, OpenCode, or any future equivalent) is an
untrusted, capability-constrained workload: it runs generated code, holds
credentials, and talks to a model. In a *cloud* deployment its requests leave
the device; in a *secure edge* deployment — a workstation, a kiosk, a vehicle,
a medical or industrial system — they must not.

HAAEEP is the platform shape for that edge deployment:

* inference runs **locally**, in its own VM, with the GPU;
* agents run in **their own VMs**, without the GPU and without the weights;
* other functions (desktop, networking, storage) run in **other VMs**, each
  isolated;
* the whole stack is **attestable**, so remote parties can verify it;
* and nothing in the design requires the model server, the agent, or the GPU
  driver to be modified.

Open-IOV is HAAEEP's GPU component. The broader motivation is in
[`../docs/01-orientation/02-the-ai-edge-and-ecosystem.md`](../docs/01-orientation/02-the-ai-edge-and-ecosystem.md).

## 2. Architecture

```text
┌──────────────────────────────────────────────────────────────────────────┐
│ EDGE DEVICE — one GPU, local inference only                              │
│                                                                          │
│  ┌─────────────────┐     ┌──────────────────┐    ┌───────────────────┐   │
│  │ Agent VM        │     │ Inference VM     │    │ Infrastructure    │   │
│  │ capability-     │────▶│ vLLM / SGLang    │    │ desktop, net,     │   │
│  │ constrained     │ API │ owns GPU via     │    │ storage VMs       │   │
│  │ no GPU          │     │ Open-IOV mdev or │    │ optional GPU accel│   │
│  │                 │     │ xen-pci + relay  │    │ via Open-IOV      │   │
│  └─────────────────┘     └────────┬─────────┘    └───────────────────┘   │
│                                   │                                      │
│  ┌────────────────────────────────┴───────────────────────────────────┐  │
│  │ Hypervisor: KVM / Xen + Argo/OpenXT / Qubes OS Air                 │  │
│  │  • Flask-XSM / HMX mandatory access control between VMs            │  │
│  │  • TrenchBoot measured boot: firmware → hypervisor → OS            │  │
│  │  • Open-IOV: per-VM virtual GPUs, IOMMU-enforced isolation         │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
```

## 3. Roles and trust

| Component | Trust | Why |
|---|---|---|
| Agent VM | untrusted | runs generated code; may be compromised |
| Inference VM | high (holds weights) | isolated from agents by MAC and by device virtualization |
| GPU-owning VM (optional) | high | owns the physical device; can serve others through Open-IOV |
| Infrastructure VMs | medium | GPU acceleration optional; no access to weights |
| Hypervisor | TCB | enforced by the platform (Argo/OpenXT/Qubes) |
| Open-IOV device | TCB-adjacent | must fail closed; audited (see the security doc) |

## 4. Data flow

1. An agent VM issues an API call to the inference VM over an internal,
   MAC-controlled channel.
2. The inference VM's vLLM/SGLang (unchanged) serves the request with the
   GPU, using its KV-cache plugins (also unchanged).
3. No request ever leaves the device: the platform's network policy forbids
   external inference endpoints by construction.

**Optional topology — GPU relay domain.** Where the platform prefers it (Xen
with `xen-pci`), one domain owns the physical GPU and relays acceleration to
other domains through Open-IOV: the process running the model is isolated
from the domain that owns the silicon, and agents are isolated from both.

## 5. Why Open-IOV fits

| Alternative | Why it is not enough |
|---|---|
| Discrete passthrough | gives the GPU to exactly one VM; HAAEEP needs the GPU in the inference VM *and* optional acceleration elsewhere |
| Process-level sharing (host CUDA with containers) | no VM-level isolation, which is the whole point of the platform |
| Proprietary vGPU | cannot build a sovereign, auditable, redistributable edge platform on a licensed host stack you cannot inspect or modify |
| Software GPU emulation | cannot run models usefully |

Open-IOV is the component in this design that *must* be open, permissively
licensed and version-durable — so it is the component we are building. Its
isolation model is described in
[`GMMU-Multi-Tenant-Protection.md`](GMMU-Multi-Tenant-Protection.md).

## 6. Roadmap (proposal)

| Milestone | Depends on |
|---|---|
| CUDA execution in a guest (rung 3) | rung 2 (runtime start) is green; CE-class work is forwarded with release and fault relay in place (default off); for GR the guest launch reaches the front-end but no grid has dispatched yet — the frontier is tracked in [`Execution-Frontier.md`](Execution-Frontier.md) |
| Two-VM coexistence (inference + agent) with isolation | Open-IOV multi-tenancy + platform MAC |
| Xen/OpenXT or Qubes Air variant | Open-IOV transport backends |
| Attested boot-to-inference chain | TrenchBoot integration |
| Published reference platform (scripts, docs) | all of the above |

Each milestone is documented as it lands, with the same evidence discipline as
the rest of the project. Nothing in this table is claimed today: it is the
proposal.

## 7. Collaboration models

**Open source projects.** Adopt the code under BSD-3-Clause (kernel modules
are GPL-2.0 — see
[`../docs/09-reference/legal-and-licensing.md`](../docs/09-reference/legal-and-licensing.md)).
We treat interface requirements as design inputs (transports, IRQ models,
memory interfaces), provide the transport abstraction rather than asking for
forks, and test against partner platforms in the matrix.

**Commercial partners.** Welcome, with no license fee: ship Open-IOV in
products and differentiate above it; sponsor support for specific
hardware/driver versions; co-develop under the same permissive terms.

**Hardware vendors.** Nothing is required. The goal is that new hardware works
through configuration and measurement; if you want to accelerate support,
share hardware and traces, and we publish what we learn.

**Security researchers.** The emulation's attack surface is small and
documented. Break it. Findings and fixes are published, with credit.

## 8. Cross-project notes

| Project | Relationship |
|---|---|
| **Qubes OS Air** | compartmentalization on modern hardware; Open-IOV makes GPU acceleration usable per compartment (especially AI workloads) |
| **TrenchBoot** | measured/attested boot; combined, the platform can attest the inference path |
| **Argo / OpenXT** | hypervisor-mediated exchange (HMX) and Flask-XSM MAC; Open-IOV respects and complements that policy |
| **KVM/VFIO gaming** | established the fast-passthrough pattern; Open-IOV serves users who need *multiple* VMs or cannot dedicate the GPU |
| **vLLM / SGLang** | remain the inference answer; Open-IOV isolates them without changing them; KV-cache plugins keep working |

## 9. How to help

* **Platform builders**: bring your hypervisor; tell us the transport you need.
* **Security engineers**: review the isolation model and the debug surface.
* **AI-infrastructure engineers**: define the reference HAAEEP deployment with
  us (model server, KV cache, agent harness).
* **Everyone**: run the evaluation ladder on your hardware and send the
  evidence.

Contact and participation channels are in
[`../docs/README.md`](../docs/README.md) §6 "How to get involved".
We would rather have a hundred partners than a hundred forks.

## 10. Related documentation

* [`../docs/08-ecosystem/haaeep-and-collaboration.md`](../docs/08-ecosystem/haaeep-and-collaboration.md) — canonical HAAEEP architecture, roadmap and collaboration models.
* [`../docs/01-orientation/02-the-ai-edge-and-ecosystem.md`](../docs/01-orientation/02-the-ai-edge-and-ecosystem.md) — the AI-edge motivation and ecosystem stance.
* [`../docs/05-operations/01-performance-correctness-security.md`](../docs/05-operations/01-performance-correctness-security.md) — the evaluation ladder behind every milestone.
* [`Project-Status.md`](Project-Status.md) and [`System-Overview.md`](System-Overview.md) — current status and component map.
* [`Execution-Frontier.md`](Execution-Frontier.md) and [`Physical-GPU-Backend.md`](Physical-GPU-Backend.md) — the GR frontier and how work reaches real hardware.
* [`Hardware-Software-Matrix.md`](Hardware-Software-Matrix.md) — what runs where, and how support is added.