llamay reference

Every gateway config field, Agent field, Helm value, admin route, ledger record, error, metric, CLI flag and port of the MAQPNA integration with the llamay inference engine.

This page lists everything that configures or reports on the llamay integration, as the MAQPNA source defines it (cmd/maqpna-gateway/llamay.go, llamay_checkpoint.go, pkg/llamay, internal/controller/models_controller.go, deploy/helm/maqpna, cmd/maqpna/dev_integrations.go). For a step-by-step setup, read Use llamay models with MAQPNA.

When an endpoint is a llamay endpoint#

The gateway gives an endpoint the llamay behaviour (context binding, context fork, llamay_session stripping, audit gating) when any of these holds:

provider is compared exactly in gateway config: write llamay in lower case. llamay is OpenAI-compatible, so the gateway uses the openai adapter for it.

Gateway config: llamay#

The llamay block of gateway.json (LlamayConfig). All fields are optional. Without the block, and without a route that says provider: llamay, nothing changes.

llamay.auditAnchors[]#

How an anchor is checked:

1. At gateway start, every anchor is verified once before the first request, so a failClosed anchor gates routing from the start.
2. Each interval, the gateway verifies what was appended since the last verified offset.
3. Every 30th check re-verifies the whole file against the pinned verified head. This catches an in-place edit of an old record.
4. A shorter file is treated as a rotation. It must continue the verified head or start a new chain from genesis. A new chain is anchored at once with llamayAuditRestartedFrom (seq:hash of the replaced head).
5. A llamay/audit-anchor record is written whenever the head moves, and a llamay/audit-unverified record once per distinct failure. A failed ledger append is retried with backoff.

Startup validation errors (the gateway does not start):

Gateway config: model route fields used with llamay#

A llamay route is an ordinary entry under models (or in modelsFile, which the operator writes as ConfigMap maqpna-models). The fields that matter for llamay:

All route fields are in the gateway configuration reference.

Agent fields for provider llamay#

Agent.spec.model (Agent CRD):

The route name is <namespace>.<agent> (characters outside [A-Za-z0-9._-] become -; names over 63 characters are shortened with a hash). The sandbox gets MAQPNA_MODEL_ENDPOINT={gateway}/llm/<route>/v1.

Helm values#

The llamay block of the chart's values (Helm values):

The chart always runs llamay with -audit /var/lib/llamay/audit/audit.jsonl -audit-strict -audit-sync: a record that cannot be written stops llamay serving rather than going missing. Keys you set in gateway.config.llamay take precedence over the ones the chart renders (upstream, apiKeyFile); with anchor.enabled, the chart sets auditAnchors.

Render errors: llamay.profile must be cpu or cuda, llamay.enabled requires llamay.model ..., set llamay.models.pull or llamay.models.bundle.image, not both, llamay.models.pull downloads from the internet; with airgap.enabled use llamay.models.bundle.image, and llamay.audit.anchor.enabled requires llamay.audit.persistence.accessModes to include ReadWriteMany ....

Admin routes#

Both need an admin credential with role admin (the static MAQPNA_ADMIN_TOKEN locally; see the admin API) and llamay.checkpointDir.

POST /v1/sessions/{id}/llamay:checkpoint#

Body: {"namespace": "dev"}. Saves every context bound to session {id} in that namespace (GET /v1/contexts/{ctx}/snapshot on llamay).

{"session": "plan-1", "namespace": "dev", "checkpoints": [
  {"route": "llamay", "upstream": "http://127.0.0.1:11435/v1", "model": "<model>", "context": "ctx_<32 hex>",
   "agent": "coder", "user": "you@localhost", "file": "<session>-<context>-<stamp>.llamay-snapshot",
   "sha256": "<hex>", "bytes": 123456}]}

A session with no bound context returns an empty checkpoints list.

POST /v1/sessions/{id}/llamay:restore#

Body: {"namespace", "parentSession", "checkpoints": [...]}, where checkpoints is the list the checkpoint route returned and parentSession is the checkpointed session. Each file must be a plain name matching ^[A-Za-z0-9._-]{1,200}\.llamay-snapshot$ in checkpointDir, and its SHA-256 must match. The gateway loads it with POST /v1/contexts/restore?model= and binds session {id} to the new context.

{"session": "plan-1-restored", "parentSession": "plan-1",
 "restored": [{"route": "llamay", "model": "<model>", "context": "ctx_<new>", "from": "ctx_<old>"}]}

Errors of the admin routes#

Ledger records and ext keys#

Model calls on a llamay endpoint are ordinary model-call records (server llm/<route>, tool such as chat.completions) with these ext keys:

Observation records (decision observe), by rule:

Other events that drop contexts: a session that reports its result (POST /v1/sessions/self/result) loses its contexts at once; a GDPR erasure (DELETE /v1/memory/users/{user}) drops that user's contexts and lists llamay in the certificate's backends; a quarantine incident lists the dropped contexts as a step.

Errors agents see#

A bound context that llamay answers with 404 (expired, llamay restarted) or 409 (in use) is not an error for the agent: the gateway retries the call once unbound, and on 404 forgets the binding. A context create or fork that fails makes the call run unbound (fork first falls back to create). All other model errors are the usual ones in Error and reason codes.

Metrics#

From the gateway's GET /metrics (all metrics):

llamay exports its own metrics on its /metrics.

CLI#

maqpna dev up flags#

Files it writes in .maqpna/: llamay.key (0600), llamay-audit.jsonl, logs/llamay.log, checkpoints/llamay/. maqpna dev run then exports OPENAI_BASE_URL, MAQPNA_MODEL_ENDPOINT ({gateway}/llm/llamay/v1), MAQPNA_MODEL_PROVIDER=openai, MAQPNA_MODEL_NAME and, outside a sandbox, OPENAI_API_KEY. With --stub-llm too, the stub route is the one exported. See maqpna dev up.

Commands that carry llamay state#

maqpna llamay verify-audit#

maqpna llamay verify-audit [--continuation] FILE... [-o json]

Give rotated files oldest first. Output: llamay audit chain verified: <records> records, head seq <seq> <hash>, or llamay audit chain BROKEN: <error> (verified through seq <seq>). With -o json: verified, records, headSeq, headHash and, on failure, error. Exit code 0 verified, 3 broken. See maqpna llamay verify-audit.

Ports and endpoints between the gateway and llamay#

Routes the gateway calls on llamay, always with the gateway's key:

Agents reach llamay only through /llm/{route}/v1/chat/completions, /completions, /embeddings and /models on the gateway; llamay's context routes, Anthropic and Ollama routes are not proxied. Every gateway call to llamay goes through the gateway's residency-checked dialer.

Next steps#

• Use llamay models with MAQPNA
• Tutorial: build a fork-and-explore agent
• Gateway configuration
• Compatibility