Ports and endpoints

Every port each MAQPNA component listens on, the protocol and main endpoints behind it, which ones you can expose outside the cluster, and the NetworkPolicies the chart and the operator create.

This page lists every port MAQPNA components listen on, in a cluster and on a laptop. Use it when you write firewall rules or NetworkPolicies, expose the gateway to clients outside the cluster, or point Prometheus at the right port. For the design behind the network rules, read Network and egress and Trust zones.

Network at a glance#

flowchart LR
    subgraph ext["Outside the cluster"]
        C["MCP clients, SDKs,<br/>maqpna CLI"]
        T["MCP servers, model APIs,<br/>SIEM, WORM, OIDC"]
    end
    subgraph agents["Agent namespace (maqpna-agents)"]
        S["Sandbox pod<br/>exec :8888 (code interpreter)<br/>relay 127.0.0.1:3128 (browser)"]
    end
    subgraph sys["MAQPNA namespace (maqpna-system)"]
        GW["Gateway<br/>http :8080<br/>admin (adminListen)"]
        ID["Identity broker<br/>http :8081<br/>bootstrap :8083"]
        OP["Operator<br/>metrics :8080<br/>health :8081"]
        AT["Attestation<br/>http :8082"]
        EC["mcp-echo :8090"]
    end
    DNS["kube-dns :53"]
    C -->|"Service type NodePort or LoadBalancer,<br/>or your Ingress"| GW
    S -->|"TCP 8080"| GW
    S -->|"UDP/TCP 53"| DNS
    S -.->|"warm pool only: TCP 8083"| ID
    S -.->|"attested tiers"| AT
    GW -->|"TCP 8888 (exec)"| S
    GW -->|"JWKS, token exchange"| ID
    OP -->|"mint tokens"| ID
    GW --> EC
    GW -->|"egress, allowlisted"| T

Solid arrows are always allowed by the default policies. Dotted arrows are allowed only when the feature is on. Only the gateway reaches hosts outside the cluster. Sandboxes reach DNS and the gateway, nothing else.

Kubernetes installation#

Defaults come from the binaries' flags and the Helm chart (deploy/helm/maqpna/values.yaml). Names below assume the release is called maqpna in namespace maqpna-system, so the Services are maqpna-gateway, maqpna-identity and so on. Every Service the chart renders is ClusterIP, except the gateway's, whose type you choose.

Inside a sandbox pod, two more listeners exist. Neither has a Service.

Gateway endpoints by listener#

What you can expose outside the cluster#

The chart renders no Ingress, Route or Gateway API object. Only the gateway is meant to be reached from outside, in one of three ways:

1. gateway.service.type: LoadBalancer: your cloud gives the maqpna-gateway Service an external address on port 8080.
2. gateway.service.type: NodePort with gateway.service.nodePort (for example 30080 on kind).
3. Your own Ingress, OpenShift Route or HTTPRoute to the maqpna-gateway Service, port 8080, with TLS terminated there. See Production install with Helm.

Keep these cluster-internal: the identity broker, the operator, the attestation service, mcp-echo and llamay. The CLI reaches them, and the gateway admin port, with port-forwarding (maqpna console, maqpna port-forward).

NetworkPolicies#

MAQPNA needs a CNI that enforces NetworkPolicy (Calico, Cilium, OVN-Kubernetes and others).

From the chart#

Agent namespaces are those listed in networkPolicy.agentNamespaces.names (default maqpna-agents) and any namespace labelled maqpna.com/agent-namespace: "true".

FQDN egress for the gateway (optional)#

With networkPolicy.fqdnEgress.enabled: true, the chart mirrors the gateway's own egress allowlist (sovereignty.allowedEgressHosts, allowedEgressCIDRs and fqdnEgress.extraHosts) into the CNI, on fqdnEgress.ports (default [443]). The kernel then drops what the gateway would refuse.

For gke and eks, add the Kubernetes API server CIDR to fqdnEgress.clusterCIDRs when gateway.configSync or gateway.activity is on; the chart refuses to render otherwise.

From the operator, per session#

The operator creates one NetworkPolicy per session, selecting that session's pods:

A quarantined session gets an empty policy: no ingress and no egress. The policy stays until the session is deleted, so a lingering pod stays fenced.

Local MAQPNA (maqpna dev up)#

Everything binds to 127.0.0.1 unless you pass --kosa8, which serves the gateway on the host's LAN address.

Other CLI listeners:

See maqpna dev up and maqpna console.

Check it worked#

List the Services and their ports:

kubectl -n maqpna-system get svc -o wide
kubectl -n maqpna-system get networkpolicy

From a sandbox namespace, the gateway answers and the identity broker's main port does not:

kubectl -n maqpna-agents run nettest --rm -it --restart=Never --image=curlimages/curl -- \
  sh -c 'curl -s -m 3 http://maqpna-gateway.maqpna-system.svc:8080/healthz; echo; curl -s -m 3 http://maqpna-identity.maqpna-system.svc:8081/healthz || echo blocked'

On a laptop, curl -s http://127.0.0.1:8080/healthz answers {"status":"ok"} while maqpna dev up runs.

What can go wrong#

Next steps#

• Network and egress: why sandboxes reach only the gateway.
• Gateway configuration: listen, adminListen, tls and egress.
• Metrics: what each component exports on its metrics port.
• Security hardening: lock down exposure in production.
• Helm values: every networkPolicy.*, gateway.service.* and port value.