Gateway configuration file

Every key of gateway.json, the MAQPNA gateway's configuration file, with types, defaults, validation rules and the Helm values that set them.

The MAQPNA gateway reads one JSON file at start-up, gateway.json. It holds the listen addresses, the identity keys it trusts, where policies, the audit ledger and state live, and the settings of every optional feature. This page lists every key the gateway accepts, grouped by area, as defined by the Config struct in cmd/maqpna-gateway/config.go and the files it embeds.

You need this page when you run the gateway outside Helm (for example on a VM or at the edge), when you set gateway.config overrides in the Helm chart, or when maqpna config validate or the gateway reports a key it does not like.

How the gateway loads the file#

flowchart LR
    A["-config flag"] --> P{"path"}
    B["MAQPNA_GATEWAY_CONFIG"] --> P
    C["/etc/maqpna/gateway.json"] --> P
    P --> D["strict JSON decode<br/>(unknown key = error)"]
    D --> E["normalize: fill defaults,<br/>validate every block"]
    E -->|errors| X["exit 1, all errors listed"]
    E --> F["-listen overrides listen"]
    F --> G["serve"]

1. The path is the -config flag. Without it the gateway uses MAQPNA_GATEWAY_CONFIG, then /etc/maqpna/gateway.json.
2. The decoder rejects unknown fields.
3. Each block fills its defaults and validates. The gateway collects every error and prints them together.
4. -listen replaces listen after validation.

The gateway binary has four flags:

Two secrets never go in the file. They come from the environment (or a _FILE variant that names a file holding the value): MAQPNA_ADMIN_TOKEN (static admin token; without it the admin API is disabled in mode token) and MAQPNA_AUDIT_HMAC_KEY (HMAC audit checkpoints). See environment variables.

Check a file before you deploy it#

1. Validate offline with the CLI. It applies the core rules shared with the gateway and warns about unknown keys and missing files:

   maqpna config validate gateway.json
   

2. Add --strict to turn warnings into errors, and --gateway-binary (or MAQPNA_GATEWAY_BIN) to also run the gateway's own full check:

   maqpna config validate gateway.json --strict --gateway-binary ./maqpna-gateway
   

3. Or run the gateway check directly:

   maqpna-gateway -check-config -config gateway.json
   

maqpna config validate exits 0 when valid (warnings allowed) and 3 on errors. See maqpna config validate.

Minimal file#

The gateway needs a policy file, an audit path, a way to verify session tokens and at least one route (an MCP server, a model route, upstreamsFile or modelsFile):

{
  "listen": ":8080",
  "policyFile": "/etc/maqpna/policies/policies.json",
  "auditPath": "/var/lib/maqpna/audit/ledger.jsonl",
  "identity": {
    "jwksURL": "http://maqpna-identity.maqpna-system.svc:8081/.well-known/jwks.json"
  },
  "upstreamsFile": "/etc/maqpna/upstreams/upstreams.json"
}

Core rules#

These rules are shared by the gateway and maqpna config validate (pkg/gatewayconfig):

• policyFile is required.
• auditPath is required.
• identity.publicKeyFiles or identity.jwksURL is required.
• At least one of upstreams, upstreamsFile, models or modelsFile is set.
• adminListen must differ from listen (default :8080).
• auditFailurePolicy is open or closed.
• modelPolicy is scope-only or policy.
• tokenExchangeURL, when set, is an http or https URL with a host.
• Each upstreams name matches ^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$ and each URL is http(s) with a host.
• sessionBudgetUSD is 0 or more.
• shutdownDelaySeconds and shutdownTimeoutSeconds are not negative.

Listeners and HTTP limits#

Identity and token verification#

identity is an object.

Each identity.trustedIssuers[] entry:

Policies#

MCP servers#

A server name is resolved for the caller in this order: an Agent binding <ns>/<agent>/<server>, the namespace's own MCPServer, exactly one MCPServer shared with the namespace (two or more is ambiguous_server), static upstreams (deprecated), then the implicit server from Agent.spec.tools[].upstreamURL (deprecated). Anything else is unknown_server.

The upstreams.json file is written by the operator, not by hand. Its shape is {"servers": {...}, "bindings": {...}, "agentWeb": {...}}; each server carries url, namespaces, implicit, trust, dataClass, jurisdiction, protocolVersions, timeoutSeconds, caPEM, auth, dlpProfile, pins and toolLabels, rendered from the MCPServer spec.

Model routes#

Each model route (models.<route>):

modelRouting:

See model providers for worked examples.

Audit ledger#

Each auditSinks[] entry:

See SIEM and audit forwarding.

Approvals and admin access#

A quorum rule (approvalQuorum.default or a rules value) has minApprovers (int, default 1, range 0 to 10), approverGroups ([]string; restricts approvers) and userConfirmation (ciba: the delegating user confirms instead of approvers).

adminAuth:

Each notifiers[] entry:

See human approvals and notifications.

Kill switch and revocations#

Budgets and cost#

DLP, taint and guards#

Binding precedence: the server's or route's own dlpProfile, then dlp.servers / dlp.models, then dlp.namespaces, then dlp.defaultProfile. none disables DLP for that binding.

A DLP profile (dlpProfiles.<name>):

Each guards[] entry:

captureArgs:

Sessions, sandbox tools and memory#

web configures the built-in maqpna-web MCP server:

k8sOps configures the governed Kubernetes operations MCP server:

infra governs Terraform and OpenTofu plans:

Agent-to-agent, delegation and user credentials#

tokenVault keeps users' OAuth tokens for per-user MCP servers:

ciba asks the delegating user to confirm on their own device:

TLS and workload identity#

State and high availability#

See state backend and scaling and HA.

Tenants and licence#

Telemetry#

See OpenTelemetry and GenAI telemetry.

Evidence and anchoring#

See config bundles and transparency log.

Offline edge and collector#

See offline edge.

Product integrations#

See Kosa8 sandboxes and llamay models.

Cloud credentials#

cloudCredentials overrides the cloud environment used by KMS key backends, the keyless WORM sink, keyless SIEM sinks and cloud model providers.

See cloud identity and keys.

Complete annotated example#

JSON has no comments, so the notes follow the file. This example is a production-style single-region gateway with OIDC admin access, signed checkpoints, a SIEM sink, DLP and a PostgreSQL state backend.

{
  "listen": ":8080",
  "adminListen": "10.0.0.5:9090",
  "logLevel": "info",
  "policyFile": "/etc/maqpna/policies/policies.json",
  "policyReloadSeconds": 2,
  "upstreamsFile": "/etc/maqpna/upstreams/upstreams.json",
  "upstreamCredentialsDir": "/var/run/maqpna-upstream-credentials",
  "tokenExchangeURL": "http://maqpna-identity.maqpna-system.svc:8081/v1/exchange",
  "modelsFile": "/etc/maqpna/models/models.json",
  "revocationsFile": "/etc/maqpna/revocations/revocations.json",
  "budgetsFile": "/etc/maqpna/budgets/budgets.json",
  "budgetTimezone": "Europe/Berlin",
  "identity": {
    "jwksURL": "http://maqpna-identity.maqpna-system.svc:8081/.well-known/jwks.json",
    "audience": "maqpna-gateway",
    "leewaySeconds": 30
  },
  "auditPath": "/var/lib/maqpna/audit/ledger.jsonl",
  "auditFailurePolicy": "closed",
  "auditCheckpointKey": "file:///var/run/maqpna-audit-key/audit-signing.pem",
  "auditCheckpointIntervalSeconds": 60,
  "auditSinks": [
    {
      "name": "siem",
      "type": "syslog",
      "address": "tls://siem.example.eu:6514",
      "caFile": "/etc/maqpna/sinks/siem/tls/ca.crt"
    }
  ],
  "approvalTimeoutSeconds": 300,
  "approvalStorePath": "/var/lib/maqpna/audit/approvals.jsonl",
  "approvalPreview": { "mode": "redacted" },
  "approvalQuorum": {
    "rules": { "payments/*": { "minApprovers": 2, "approverGroups": ["treasury"] } }
  },
  "adminAuth": {
    "mode": "both",
    "oidc": {
      "issuer": "https://sso.example.eu/realms/maqpna",
      "audience": "maqpna-admin",
      "groupsClaim": "groups"
    },
    "roles": { "admin": ["platform"], "auditor": ["security"], "killswitch": ["security"] },
    "namespaceRoles": { "team-a": { "approver": ["team-a-leads"] } }
  },
  "dlpProfiles": {
    "strict": { "requestAction": "redact", "responseAction": "redact", "onSecret": "deny" }
  },
  "dlp": { "defaultProfile": "strict" },
  "pinStorePath": "/var/lib/maqpna/audit/toolpins.jsonl",
  "taintStorePath": "/var/lib/maqpna/audit/taint.jsonl",
  "stateBackend": { "type": "postgres", "dsnFile": "/var/run/maqpna-state/dsn" },
  "shutdownDelaySeconds": 5
}

What each part does:

• listen / adminListen: agents reach :8080; the admin API and /metrics are only on the private 10.0.0.5:9090.
• policyFile to budgetsFile: the files the operator renders from your resources. The gateway polls them every 2 seconds.
• identity: session tokens are verified against the identity broker's JWKS.
• auditFailurePolicy: closed: no allowed call is forwarded unless its intent record is durable.
• auditCheckpointKey: checkpoints are signed every 60 seconds or 1000 records.
• auditSinks: every record is streamed over TLS syslog.
• approvalQuorum: rules of policy payments need two approvers from group treasury.
• adminAuth: OIDC for people, the static token kept as break-glass.
• dlp: every call uses profile strict, which redacts personal data and denies secrets.
• stateBackend: approvals, revocations, taint and counters are shared between replicas.

Helm values that set gateway.json#

The chart renders gateway.json into ConfigMap <release>-gateway-config. It starts from gateway.config (copied as is, so any key on this page can go there) and then fills keys from other values. A key you set in gateway.config usually wins; the exceptions are noted.

To see the rendered file for your values, render the chart and read the ConfigMap:

helm template maqpna oci://$REGISTRY/charts/maqpna --version 2.1.0 -f values.yaml \
  --show-only templates/gateway.yaml

REGISTRY is the release registry listed on maqpna.com/download. See Helm values.

What can go wrong#

Next steps#

• Environment variables
• Helm values
• Ports and endpoints
• Gateway architecture
• Production install with Helm