kosa8 reference

Every MAQPNA setting, flag, policy field, ledger rule, kosa8d API call, environment variable, path, metric and error of the kosa8 integration, read from the source.

This page lists everything MAQPNA reads, writes and calls for kosa8, the microVM container platform from Kosa8 Labs. For the steps, see Run MAQPNA sessions in kosa8 sandboxes. The source is pkg/kosa8 (client), pkg/sandbox/kosa8sandbox (sandbox driver), cmd/maqpna-gateway/kosa8.go (decision mirror and audit anchor) and cmd/maqpna/dev_sandbox.go (maqpna dev commands).

flowchart LR
    CLI["maqpna dev<br/>run, fork, snapshot,<br/>restore, attest"] -->|"sandbox driver"| K["kosa8d"]
    BR["Identity broker<br/>-sandbox-check kosa8"] -->|"read sandbox, egress, inventory"| K
    GW["Gateway<br/>kosa8 block"] -->|"POST /kosa8/v1/ai/records"| K
    GW -->|"GET /kosa8/v1/audit/verify, /audit?limit=1"| K

Gateway config: kosa8#

The kosa8 block of gateway.json turns on the decision mirror and the audit anchor. It is off unless mirrorDecisions is true or anchorIntervalSeconds is above 0.

Validation errors (the gateway refuses to start; maqpna-gateway -check-config reports them):

maqpna dev up --kosa8 writes "kosa8": {"mirrorDecisions": true, "anchorIntervalSeconds": 30}. To change it, pass --gateway-config FILE with a kosa8 object: top-level keys of that file replace the generated ones. A full example is in the MAQPNA source, examples/integrations/gateway-llamay-kosa8.json.

Helm values#

The chart has no kosa8 values. kosa8d is a per-user daemon on a workstation or edge host, not a cluster service, so the integration is built for maqpna dev. gateway.config is rendered into the gateway's gateway.json as is, so a gateway.config.kosa8 block reaches a gateway in a cluster:

gateway:
  config:
    kosa8:
      url: https://kosa8-worker.example.eu
      tokenFile: /mnt/secrets-store/kosa8-token
      anchorIntervalSeconds: 60
  secretsStoreCSI:
    enabled: true
    secretProviderClass: maqpna-kosa8-token

This is not a tested setup: no kosa8 sandbox runs in the cluster, and the operator does not use the kosa8 driver. See MAQPNA on Kubernetes and Helm values.

maqpna dev flags#

Full flag lists: maqpna dev up, dev run, dev fork, dev snapshot, dev restore, dev attest.

Sandbox driver: kosa8#

Sandbox labels (the broker check reads them; a copy keeps its source's labels):

Token delivery inside the sandbox:

Identity broker flags#

maqpna dev up --kosa8 passes the first two. Use them on your own maqpna-identity:

The broker refuses a mint (403, error identity: proof refused: …) when:

• the proof names no sandbox, or kosa8d does not list it;
• the sandbox's labels name another namespace, agent or user, or another session (a copy passes when kosa8 reports a parent and the labelled session is the request's parent session or fork root);
• the egress kosa8 enforces now is not exactly the gateway;
• isolation or attestation is below the floor;
• a measurement is not in -sandbox-check-allowed.

On success the token carries maqpna_substrate: check (kosa8), sandbox, isolation, attestation, egress, digest (SHA-256 over the sorted name=sha256 measurements) and platform (for example kosa8 0.9.36 f6124c0).

ToolPolicy substrate fields#

A rule's substrate condition matches the verified substrate. Every set field must hold.

The gateway's JSON policy rules also take providers, regions, notRegions, countries and notCountries; the ToolPolicy CRD has the five fields above. A kosa8 check reports no jurisdiction. See ToolPolicy.

Ledger records#

ext keys: kosa8AuditSeq, kosa8AuditHead, kosa8AuditVerified. A failed append is retried with backoff; the anchored position moves only once the record is in the ledger.

Mirrored mcp.decision record#

kosa8d API calls#

All calls go to kosa8d's native API. State-changing calls send X-Kosa8-Actor: tool. TCP calls send Authorization: Bearer <token>. Non-streaming calls time out after 2 minutes (10 seconds in the gateway).

Errors from kosa8d come back as kosa8: HTTP <status>: <error> (<remediation>).

Gateway routes used by dev snapshot and dev restore#

Environment variables#

MAQPNA_TOKEN, and any variable whose value contains the token, are removed from a sandbox's environment.

Ports, sockets and files#

Metrics#

On the gateway's /metrics:

Errors#

Next steps#

• Run MAQPNA sessions in kosa8 sandboxes, step by step.
• Tutorial: private coding agent.
• Gateway config and Ports and endpoints.
• Sandbox drivers.