The Kosa8 Labs stack

What MAQPNA, llamay and kosa8 each do, how they fit together, and which combination to run on a laptop or a cluster.

Kosa8 Labs makes three products that work together. MAQPNA governs what agents may do. llamay runs the model on your own hardware. kosa8 runs the agent in a microVM. You can use MAQPNA alone, or add one or both of the others. This page explains what each one does, how a call flows through all three, and which combination fits your case.

What each product does#

MAQPNA is the only required part. llamay and kosa8 are opt-in: nothing changes in MAQPNA until a model route says provider: llamay, gateway.json has a llamay or kosa8 block, or you start maqpna dev up with --llamay or --kosa8.

How they fit#

MAQPNA sits in the middle. The agent never talks to llamay or kosa8 directly for governed work: model calls go through the gateway's model route (/llm), and the sandbox can reach only the gateway.

flowchart TB
    subgraph K["kosa8 microVM (laptop)"]
        A["Agent"]
    end
    subgraph M["MAQPNA"]
        IB["Identity broker"]
        GW["Gateway"]
        L[("Audit ledger")]
    end
    LL["llamay serve"]
    MCP["MCP servers"]
    KD["kosa8d"]
    IB -->|"verifies sandbox, mints token"| A
    IB -.->|"asks"| KD
    A -->|"session token"| GW
    GW -->|"/llm, gateway key"| LL
    GW -->|"/mcp"| MCP
    GW --> L
    GW -.->|"decision mirror, audit head"| KD
    LL -.->|"request audit file"| GW

• Identity. The identity broker issues each session a signed, short-lived token. With kosa8, the broker first asks kosa8d whether the sandbox exists, runs that session and has egress pinned to the gateway.
• Governance. The gateway checks the token, the policy, budgets and DLP on every call, then forwards it. Model calls go to llamay with the gateway's own llamay key.
• Evidence. Every decision is written to the audit ledger. llamay's request audit and kosa8's audit head are anchored into the same ledger.

One model call, end to end#

sequenceDiagram
    autonumber
    participant Ag as Agent (kosa8 microVM)
    participant GW as MAQPNA gateway
    participant LL as llamay
    participant L as Audit ledger
    Ag->>GW: POST /llm/llamay/v1/chat/completions (session token)
    GW->>GW: verify token, scope, policy, budget, DLP
    GW->>GW: strip any llamay_session the agent sent
    GW->>LL: POST /v1/contexts (first call of the session)
    LL-->>GW: ctx_…
    GW->>LL: chat/completions with llamay_session=ctx_… (gateway key)
    LL-->>GW: completion and usage
    GW->>L: record with ext.llamayContext, tokens, cost
    GW-->>Ag: completion

The agent cannot pick a llamay context: the gateway removes llamay_session from every request and binds the session's own context. The same context id appears in llamay's own audit record, so the two chains can be matched.

Which combination to use#

Some guidance for choosing:

• Add llamay when prompts must not leave your perimeter, when you want a model price of zero or an internal transfer price, or when long agent conversations should not be prefilled again on every turn.
• Add kosa8 when you develop agents on a laptop and want them to run as they will in production: isolated, with default-deny egress and their own short-lived identity, instead of as a process with your API keys.
• Use all three for fork-and-explore work: maqpna dev fork clones the running microVM and the gateway forks its llamay context, so the child continues from the parent's exact disk, memory and model state.

What works where#

kosa8 is a developer-machine runtime in this release. It is not a Kubernetes RuntimeClass, so in a cluster agents run in the gVisor, Kata and confidential VM trust tiers instead.

Operating systems differ per product. See Compatibility for the full matrix.

Pick your path#

1. Compatibility: versions, platforms and which feature needs which product.
2. Stack quickstart: all three on one laptop in a few minutes.
3. MAQPNA with llamay and the llamay reference.
4. MAQPNA with kosa8 and the kosa8 reference.
5. Developer workflow: run, fork, snapshot and restore an agent.
6. On Kubernetes: llamay in the cluster with the Helm chart.
7. Security model: trust boundaries and how to verify the audit chain end to end.
8. Troubleshooting: error messages and fixes.
9. Tutorials: fork and explore an agent and a private coding agent.

Next steps#

• Stack quickstart
• Compatibility
• Serve models with llamay
• Run agents in kosa8 sandboxes