1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
# 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.
|
