Architecture
How the operator, gateway and identity broker fit together, and how a tool call flows through them.
Solution architecture overviewThe big picture of MAQPNA, its control plane and data plane, every component and the systems it connects to, and how one session flows through them.Deployment topologiesThe six ways MAQPNA is deployed, from a laptop to a confidential, air-gapped, multi-tenant installation, and what changes between them.OperatorThe maqpna-operator turns Agent and AgentSession resources into sandboxes, tokens and NetworkPolicies, and renders every policy and registry the gateway reads.GatewayThe maqpna-gateway is the one component every tool, model, agent-to-agent and egress call passes through; it decides, holds, forwards and records each call.Identity brokerThe maqpna-identity broker issues short-lived Ed25519 session tokens with SPIFFE-style subjects, publishes its public keys, exchanges and delegates tokens, and bootstraps warm-pool pods.Attestation servicemaqpna-attest and maqpna-attest-agent release a session token to a tier-2 confidential VM only after its hardware report is verified and appraised against your reference values.State backendpkg/state puts every durable store of the gateway and the attestation service behind one abstraction with two backends, fsynced files or one shared PostgreSQL schema.Console and MAQPNA DeskThe MAQPNA Console and the MAQPNA Desk desktop app are thin clients of the gateway's admin API, served locally by the maqpna CLI; they add no credentials and no privileges.CLI and pluginThe maqpna CLI is one static binary for developers, approvers, auditors and platform teams; the Helm lifecycle commands live in the separate maqpna-install plugin.Session lifecycleHow an AgentSession becomes a running sandbox with its own identity, and how it ends, is finalised and reported for usage.A governed tool callEvery check an MCP tools/call passes through in the MAQPNA gateway, in the order the code runs them, from token verification to the audit record.Approval flowHow a held tool call is created, announced to approvers, decided with separation of duties and four-eyes quorum, and consumed exactly once, or expires.User approval (CIBA)How the gateway asks the person an agent acts for to confirm a held call on their own device, through the customer's identity provider in CIBA poll mode.DLP decision flowHow the gateway picks a data loss prevention (DLP) profile for a call, scans requests, responses and streams, and redacts, denies or withholds.Taint propagationHow a session picks up taint labels from untrusted content, how rules use them, how they spread across replicas and forks, and how they are cleared.Budget enforcementHow budgets are rendered from Agents and BudgetPolicies, checked before every tool and model call, limited per minute, persisted and reported, and how the operator caps concurrent sessions.Kill switch and revocationHow a revocation, declared as an AgentRevocation or created break-glass at the gateway, stops matching calls on every replica within seconds and suspends or terminates sessions.Identity broker flowsHow the identity broker issues short-lived session tokens, bootstraps warm-pool pods, exchanges and delegates tokens, binds workload certificates and rotates its signing keys.Attestation-gated secretsHow a tier-2 session's token is released only to a confidential VM that proves, with a hardware-signed report, that it runs a measurement you approved, and how the token is renewed.Model call governanceHow a model call goes through the gateway's OpenAI-compatible route, from authentication and budgets to DLP, routing and failover, metering and the audit record.A2A call with delegationHow one agent calls another over agent-to-agent (A2A) v1.0 through the gateway, governed like a tool call, audited on both hops, and how the callee acts for the caller with a delegation token.Audit ledger flowHow every decision is appended to a SHA-256 hash chain, sealed with signed checkpoints, verified with maqpna audit verify, exported as evidence and shipped to SIEM and write-once (WORM) storage.Licensing and entitlementsHow a MAQPNA licence is verified offline, how it switches paid features on, and why no licence state ever blocks or degrades agent traffic.Usage metering and node countingHow sandbox time, governed calls, model tokens and approvals are metered into hourly buckets, signed into verifiable usage reports, and how billable nodes are counted.Install and upgrade flowHow maqpna preflight, install, upgrade, upgrade check, rollback and uninstall run through the maqpna-install plugin and the Helm v3 SDK, with CRDs applied server-side before Helm, and how an air-gapped install differs.Developer loopHow maqpna dev up starts a local MAQPNA without a cluster, how maqpna dev run gives your agent its own session identity, and how maqpna dev timeline shows every decision.CRD data modelThe 13 kinds of the maqpna.com/v1alpha1 API, how they reference each other and the upstream agent-sandbox kinds, and the gateway files the operator renders from them.Gateway request pipelineInside maqpna-gateway - listeners, middleware, route families and the ordered stages a Model Context Protocol (MCP) tool call passes through, with the function that implements each.Policy evaluationHow pkg/policy turns a request into allow, deny or require_approval - native rules, Cedar text in a ToolPolicy, an optional OPA sidecar, rate limits, dry run and the evaluation trace.State backend schema and leader electionThe pkg/state abstraction, its file and PostgreSQL backends, the tables, journals, blobs and counters MAQPNA keeps, and how replicas elect a leader for background jobs.Ledger record formatThe fields of an audit record, the canonical JSON and SHA-256 hash chain, schema 2 ext keys, HMAC and Ed25519 checkpoints, and the evidence bundle, with golden vectors you can reproduce in any language.Error envelope and reason codesEvery error the gateway generates carries the same fields - domain, reason, detail, policy, rule - in the place each protocol allows, with one published, append-only list of reason tokens.HA and failure handlingHow many replicas each MAQPNA component runs, what they share, how leadership moves, and exactly what happens when each dependency fails - which failures deny calls and which do not.Security boundaries and trust zonesThe trust zones of a MAQPNA installation, what crosses each boundary, which credential authenticates each crossing, and what is designed never to cross.Network and egress designDefault-deny networking for every session, the chart's control-plane NetworkPolicies, the residency-checking and SSRF-guarded dialers, governed web fetch and the browser egress path.Key managementWhich keys a MAQPNA installation holds, where each lives, the pkg/keys URI schemes that reference them (file, PKCS#11, KMS, Azure Key Vault), what is implemented and what is Planned, and how keys are rotated.ObservabilityThe Prometheus metrics each MAQPNA component exports, the alerts and dashboards the Helm chart ships, OpenTelemetry tracing linked to the audit ledger, and the posture checks behind maqpna doctor.