Compatibility
Which llamay and kosa8 versions and platforms MAQPNA 2.1.0 works with, the API surface it needs from each, and which feature needs which product.
This page lists the versions and platforms of llamay and kosa8 that MAQPNA 2.1.0 has been checked against, what MAQPNA needs from each product's API, and which MAQPNA features need which product. Read it before you install, and again before you upgrade llamay or kosa8.
Version matrix#
| Product | Version | Status with MAQPNA 2.1.0 |
|---|---|---|
| MAQPNA | 2.1.0 | This release. |
| llamay | 0.4.5 | Helm chart default image tag (llamay.image.tag: "0.4.5"). The context routes, llamay_session and the audit record format were read in the 0.4.5 source. |
| llamay | development build after 0.4.5, CPU, macOS arm64 | Run live: the llamay integration test and a maqpna dev end-to-end run (context binding, streaming, fork, audit anchor, checkpoint and restore). |
| llamay | sovereign build | Context routes and llamay_session are present. Needs -api-keys and -audit to start. Context export and import are absent; MAQPNA does not use them. |
| kosa8 | 0.5.0, macOS arm64 | Run live: egress allow-list, token delivery, live fork, re-key, and a maqpna dev end-to-end run with llamay. |
| kosa8 | 0.9.36, macOS arm64 | Run live after an upgrade from 0.5.0: the kosa8 integration test, the sandbox driver conformance suite, and dev up --kosa8 --llamay with dev attest, dev snapshot, dev restore and dev fork. No MAQPNA change was needed. |
| kosa8 | Linux (Cloud Hypervisor on KVM) | Same API. Not run by Kosa8 Labs against MAQPNA 2.1.0. |
Required API surface#
llamay#
The gateway talks to llamay over HTTP with Authorization: Bearer <key>. It needs these routes:
| Route | Used for |
|---|---|
POST /v1/chat/completions, POST /v1/completions, POST /v1/embeddings, GET /v1/models |
The governed model path. These are the only operations /llm proxies. |
POST /v1/contexts {"model"} |
Create the session's context on its first call. |
POST /v1/contexts/{id}/fork?n=1&model= |
Fork the parent's context for a forked session. |
DELETE /v1/contexts/{id} |
Drop idle, ended, revoked and erased sessions' contexts. |
GET /v1/contexts/{id}/snapshot |
Session checkpoint (llamay.checkpointDir) and quarantine snapshots (llamay.quarantineSnapshotDir). |
POST /v1/contexts/restore?model= |
Session restore. |
GET /healthz |
Health check in maqpna dev up --llamay. |
Body field llamay_session |
Binds a generation to a context. There is no header form. |
Request audit file (llamay serve -audit FILE) |
JSONL, SHA-256 hash chain, genesis of 64 zeros. Read from disk: llamay has no HTTP endpoint for the chain head. |
llamay's Anthropic /v1/messages and Ollama /api/* routes are not governed paths.
kosa8#
MAQPNA talks to kosa8d, the kosa8 daemon, over HTTP/JSON. By default it uses the per-user unix
socket ~/.kosa8/run/kosa8.sock. A TCP daemon (kosa8d --listen ADDR --token T) needs a bearer
token. Write requests carry the header X-Kosa8-Actor: tool.
| Route | Used by |
|---|---|
GET /kosa8/v1/health |
maqpna dev up --kosa8 (reachability check) |
POST /kosa8/v1/sandboxes, GET /kosa8/v1/sandboxes, DELETE /kosa8/v1/sandboxes/{id}?wipe=1 |
The kosa8 sandbox driver: create, find and remove sandboxes |
POST …/{id}/pull, POST …/{id}/start-interactive, POST …/{id}/containers/{cid}/stdin, GET …/{id}/containers |
Pull the image, start the agent, deliver the token over stdin |
POST …/{id}/exec, POST …/containers/{cid}/attach |
Re-key a fork, stream agent output |
POST …/{id}/fork |
maqpna dev fork |
POST …/{id}/snapshot, POST /kosa8/v1/snapshots/{id}/restore |
maqpna dev snapshot, maqpna dev restore |
GET …/{id}/egress, GET …/{id}/inventory |
Egress proof and measurements: maqpna dev attest and the identity broker's sandbox check |
GET /kosa8/v1/audit/verify, GET /kosa8/v1/audit?limit=1 |
Anchor kosa8's audit head in the ledger |
POST /kosa8/v1/ai/records |
Mirror MCP decisions into kosa8's audit chain |
… stands for /kosa8/v1/sandboxes.
Platforms#
| Product | macOS | Linux | Windows | Kubernetes |
|---|---|---|---|---|
MAQPNA CLI (maqpna, maqpna dev) |
Yes | Yes: amd64, arm64, ppc64le, s390x packages |
Yes | — |
| MAQPNA control plane | — | Container images | — | Yes, Helm chart |
| llamay | macOS 13 or later; Apple Silicon, Intel through the command-line build | x86-64 and arm64 (.deb, .rpm) |
Windows 10 or later, x86-64 and arm64 | Yes, as part of the MAQPNA chart (llamay.profile: cpu or cuda) |
| kosa8 sandboxes | Apple Silicon (Virtualization framework) | x86-64 with KVM, cloud-hypervisor and virtiofsd |
Windows 11 x86-64 through WSL2 (preview) | No |
Platform data for llamay and kosa8 is from llamay.com/download
and the kosa8 install guide. Machines that cannot run
kosa8 sandboxes, such as Intel Macs, can use a remote kosa8 worker; MAQPNA's maqpna dev path has
been run only with a local kosa8d.
Which feature needs which product#
| MAQPNA feature | MAQPNA alone | Needs llamay | Needs kosa8 |
|---|---|---|---|
| Governed tool, model and egress calls, policy, budgets, DLP, approvals | Yes | — | — |
| Local model with no data leaving the perimeter | Any self-hosted OpenAI-compatible model | Or llamay | — |
| Per-session inference context (no re-prefill each turn) | — | Yes | — |
Context fork with session fork (ext.llamayContextParent) |
— | Yes | — |
Session checkpoint and restore of model state (llamay:checkpoint, llamay:restore) |
— | Yes, with llamay.checkpointDir |
— |
Model-request audit anchored in the ledger (llamay/audit-anchor) |
— | Yes | — |
| Agent in a microVM on a laptop, egress pinned to the gateway | — | — | Yes |
Broker-verified sandbox before mint (maqpna_substrate claim, policy substrate.checks: [kosa8]) |
Other drivers: agent-sandbox, e2b |
— | Yes, for kosa8 |
maqpna dev fork, dev snapshot, dev restore, dev attest |
Other drivers via --sandbox |
Model state is included when llamay is on | Default driver |
MCP decisions mirrored into a second audit chain (kosa8/audit-anchor) |
— | — | Yes |
Laptop and Kubernetes#
| Feature | Laptop (maqpna dev) |
Kubernetes |
|---|---|---|
| llamay serving | maqpna dev up --llamay MODEL starts llamay serve on 127.0.0.1:11435 |
Helm llamay.enabled: true: one replica, port 8081, Service and NetworkPolicy |
| llamay API key | Generated into .maqpna/llamay.key, passed as LLAMAY_API_KEY |
Generated Secret (or llamay.apiKey.existingSecret), mounted into the gateway only |
| llamay audit anchor | On, every 10 seconds, failClosed: true |
llamay.audit.anchor.enabled: true (default off), every 60 seconds, failClosed: true; needs ReadWriteMany |
| Session checkpoints | llamay.checkpointDir set to .maqpna/checkpoints/llamay |
Not set by the chart; set gateway.config.llamay.checkpointDir yourself |
| Air-gapped models | — | llamay.models.bundle.image (models.pull is refused with airgap.enabled) |
| Agent sandbox | kosa8 microVM (dev run --kosa8-image) or a host process |
Trust tiers: gVisor, Kata microVM, confidential VM |
| Fork with model state | maqpna dev fork |
Session fork on the cluster tiers; the gateway forks the llamay context the same way |
| kosa8 audit cross-anchoring | Set by dev up --kosa8 (mirror on, anchor every 30 seconds) |
A kosa8 block with url (HTTPS) and tokenFile; not run by Kosa8 Labs |
Known limits that affect a cluster:
- llamay context bindings live in the gateway process. With several gateway replicas, a session that lands on another replica gets a fresh context. This is correct but costs one prefill.
- The chart runs one llamay replica.
AgentSessionSnapshotdoes not save llamay contexts yet.maqpna dev snapshotdoes.