MAQPNADocs

Environment variables

Every environment variable a MAQPNA binary, SDK or install script reads, grouped by component, with its default and meaning.

This page lists every environment variable that MAQPNA code reads: the maqpna CLI and its maqpna-install plugin, the gateway, the identity broker, the operator, the attestation components, the sandbox helpers, the Python, TypeScript and Go SDKs, and the install scripts. Use it when you set up a deployment by hand, debug a sandbox, or want to know why a flag has a default you did not set.

Each table has four columns. Used by names the binary, command or library that reads the variable. Default is the value used when the variable is unset ("—" means no default: the feature is off or the value is required).

How components get their settings#

flowchart LR
    H["Helm chart"] -->|"env + Secrets"| GW["maqpna-gateway"]
    H -->|"env + Secrets"| ID["maqpna-identity"]
    H -->|"env + Secrets"| OP["maqpna-operator"]
    OP -->|"injects MAQPNA_* env"| SB["Agent in sandbox"]
    SB --> SDK["SDK from_env / fromEnv"]
    U["Your shell"] --> CLI["maqpna CLI"]
    U --> INS["install.sh / install.ps1"]

Reading secrets from files (_FILE)#

Some server binaries read secrets through a helper that accepts a file instead of a value. For a variable NAME, set NAME_FILE to the path of a file that holds the value. When both are set, NAME_FILE wins. A trailing newline in the file is removed. The file must not be empty and must be at most 1 MiB.

Use this with the Secrets Store CSI driver, Vault Agent or an External Secrets volume, so the secret does not show in kubectl describe, crash dumps or child processes.

The _FILE form works for exactly these variables:

Variable Read by
MAQPNA_ADMIN_TOKEN maqpna-gateway
MAQPNA_AUDIT_HMAC_KEY maqpna-gateway
MAQPNA_AUDIT_WORM_ACCESS_KEY, MAQPNA_AUDIT_WORM_SECRET_KEY, MAQPNA_AUDIT_WORM_SESSION_TOKEN maqpna-gateway
MAQPNA_BROKER_TOKEN maqpna-identity, maqpna-operator, maqpna-attest

CLI (maqpna)#

Target, context and credentials#

Name Used by Default Meaning
MAQPNA_CONFIG maqpna, maqpna-install $XDG_CONFIG_HOME/maqpna/config.yaml, else ~/.config/maqpna/config.yaml Path of the CLI config file. Login tokens are stored in tokens/ next to it. See CLI configuration.
XDG_CONFIG_HOME maqpna, maqpna-install ~/.config Base directory of the default config file, on every OS.
MAQPNA_CONTEXT maqpna, maqpna-install the config file's currentContext Context to use for this invocation. Same as --context; the flag wins.
MAQPNA_GATEWAY_URL maqpna (every command with --gateway) the context's gateway Gateway base URL. A global --gateway before the command wins over it.
MAQPNA_ADMIN_TOKEN maqpna (admin API commands) — Static admin-API bearer token (adminAuth.mode token or both). Default for --token. Use it for development and break-glass only.
MAQPNA_OIDC_TOKEN_FILE maqpna (admin API commands, doctor, support-bundle) — File holding an OIDC access token for the admin API. Default for --oidc-token-file. It wins over --token.
MAQPNA_ALLOW_GATEWAY_MISMATCH maqpna (admin API commands) off 1 sends the context's stored login token to a gateway other than the one it was issued for. Same as --allow-gateway-mismatch.
KUBECONFIG maqpna, maqpna-install ~/.kube/config, then in-cluster config Kubeconfig for Kubernetes-backed commands, when neither --kubeconfig nor the context's kubeconfig is set.

Session and tool-call commands#

Name Used by Default Meaning
MAQPNA_AGENT_TOKEN, then MAQPNA_TOKEN maqpna call — Session token for the debugging tool call. The first non-empty one is used as the --token default.
MAQPNA_BROKER_TOKEN maqpna token mint — Bearer token for the identity broker. Default for --broker-token.
MAQPNA_SESSION maqpna infra apply — Session ID. Default for --session.
MAQPNA_TOKEN_FILE maqpna infra apply — File holding the session token. Default for --token-file.
MAQPNA_TOKEN maqpna infra apply — Session token, used when no token file is given.

Audit, evidence and licensing#

Name Used by Default Meaning
MAQPNA_AUDIT_HMAC_KEY maqpna audit verify — Checkpoint HMAC key. --checkpoint-key-env names the variable to read; its default is MAQPNA_AUDIT_HMAC_KEY. When set, <FILE>.checkpoints must exist and verify.
MAQPNA_EVIDENCE_KEY maqpna evidence generate, maqpna audit anchor — Key URI of the audit-checkpoint signing key (path, file:///, pkcs11: or kms://). Default for --key.
MAQPNA_EVIDENCE_PQ_KEY maqpna evidence generate — ML-DSA key that also signs the pack (hybrid). Default for --pq-key.
MAQPNA_CAPTURE_KEY maqpna replay — Key URI of the argument-capture key. Default for --capture-key.
MAQPNA_LICENSE_FILE maqpna evidence generate the licence installed in the cluster Licence file to evaluate when --license is not given.
MAQPNA_INSTALLATION_ID maqpna usage report and export the kube-system namespace UID Installation ID written into the usage report.
MAQPNA_GATEWAY_BIN maqpna config validate — Path of a maqpna-gateway binary. When set, the command also runs its -check-config. Default for --gateway-binary.

Approvals and people#

Name Used by Default Meaning
MAQPNA_APPROVER maqpna desk $USER, else $USERNAME Approver name recorded with a static admin token. An OIDC token names you itself.
USER, USERNAME maqpna approvals, maqpna kill, maqpna taint, maqpna desk, maqpna config bundle build — Your OS user name, used as the default approver, actor or createdBy value, and in the default bundle issuer <user>@maqpna-cli.

Local MAQPNA (maqpna dev) and plugins#

Name Used by Default Meaning
MAQPNA_DL_BASE maqpna dev (server binary download) the MAQPNA release mirror Mirror to download maqpna-gateway and maqpna-identity from when they are not installed.
MAQPNA_RELEASES_URL maqpna dev (server binary download) the release repository listed on maqpna.com/download Release repository used when the mirror does not have the binary. Setting only this variable skips the mirror.
MAQPNA_INSTALL_PLUGIN maqpna (install, upgrade, rollback, uninstall, preflight) next to the maqpna binary, then PATH Path of the maqpna-install plugin binary.
MAQPNA_PROG_NAME maqpna, maqpna-install from the binary name Program name shown in help and usage, such as maqpnactl or ma. The Windows install script sets it in its .cmd shims.
PATH maqpna plugin — Searched for maqpna-NAME plugins.
TAG maqpna airgap bundle this CLI's version Image tag to bundle when --tag is not given.

Downloaded server binaries are cached in your OS user cache directory under maqpna/<version>/bin.

Terminal output and editors#

Name Used by Default Meaning
NO_COLOR maqpna, maqpna-install — Any value turns colour off. Same as --no-color.
CLICOLOR_FORCE, FORCE_COLOR maqpna, maqpna-install — Any value other than 0 forces colour, even when output is not a terminal. NO_COLOR and --no-color still win.
TERM maqpna, maqpna-install — dumb turns colour and Unicode symbols off.
MAQPNA_ASCII maqpna, maqpna-install — Any value other than 0 prints ASCII symbols (+ x ! *) instead of Unicode ones.
LC_ALL, LC_CTYPE, LANG maqpna, maqpna-install — The first one set decides whether Unicode symbols are used (it must name UTF-8).
WT_SESSION, TERM_PROGRAM, ConEmuANSI maqpna, maqpna-install on Windows — Detect Windows Terminal, VS Code or ConEmu, which show Unicode symbols.
KUBE_EDITOR, then EDITOR maqpna edit — Editor to open the resource in.
SHELL, ZDOTDIR maqpna alias install — Pick the shell, and the .zshrc location for zsh.

Lifecycle plugin (maqpna-install)#

Name Used by Default Meaning
MAQPNA_CHART_USERNAME maqpna install, maqpna upgrade — Registry or chart repository user name. Default for --username.
MAQPNA_CHART_PASSWORD maqpna install, maqpna upgrade — Registry or chart repository password. Default for --password.
HELM_DRIVER maqpna-install secret Helm release storage driver to read (secret or configmap), as Helm uses it.

Gateway (maqpna-gateway)#

Core#

Name Used by Default Meaning
MAQPNA_GATEWAY_CONFIG maqpna-gateway /etc/maqpna/gateway.json Path of the gateway configuration file. Default for -config.
MAQPNA_ADMIN_TOKEN (or _FILE) maqpna-gateway — Static bearer token for the admin API (/v1/* admin endpoints). When unset, the gateway logs admin API disabled for static-token access.
MAQPNA_AUDIT_HMAC_KEY (or _FILE) maqpna-gateway — Key for HMAC audit checkpoints. When set, the gateway writes them and doctor reports them in the posture.
MAQPNA_JURISDICTION maqpna-gateway the sovereignty policy's jurisdiction Jurisdiction the gateway records on WORM audit objects, SIEM records and memory stores. The chart sets it from sovereignty.jurisdiction.
POD_NAMESPACE maqpna-gateway — Default for configSync.namespace. With configSync on, one of the two is required.
KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT maqpna-gateway set by Kubernetes API server address for activity, configSync and k8sOps, when their apiServer key is not set.
HTTP_PROXY, HTTPS_PROXY, NO_PROXY maqpna-gateway — Proxy for connections to MCP servers. Ignored when a sovereignty policy is active, because the residency check must see the real upstream.

Model routes#

Name Used by Default Meaning
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN maqpna-gateway (aws-sigv4 model routes) — AWS credentials when the route's auth has no credential files. Cloud workload identity is used after them.
GOOGLE_OAUTH_ACCESS_TOKEN maqpna-gateway (gcp model routes) — Access token for Vertex AI routes. When set, it wins over workload identity.
any name in auth.tokenEnv maqpna-gateway (model routes) — A route can name an environment variable that holds its access token.

WORM audit shipping#

The chart sets these when audit.sink is worm. They ship ledger segments to an in-country object store with a retention lock.

Name Used by Default Meaning
MAQPNA_AUDIT_SINK maqpna-gateway local worm turns WORM shipping on.
MAQPNA_AUDIT_WORM_PROVIDER maqpna-gateway s3 Store type: s3, gcs or azure.
MAQPNA_AUDIT_WORM_ENDPOINT maqpna-gateway the GCS endpoint for gcs; else — Object store endpoint. Required except for gcs.
MAQPNA_AUDIT_WORM_BUCKET maqpna-gateway — Bucket or container. Required.
MAQPNA_AUDIT_WORM_REGION maqpna-gateway us-east-1 Region for S3 signing.
MAQPNA_AUDIT_WORM_OBJECT_LOCK_DAYS maqpna-gateway the sovereignty policy's audit retention Retention days; a positive integer. The gateway verifies the bucket's lock before it starts shipping.
MAQPNA_AUDIT_WORM_INTERVAL_SECONDS maqpna-gateway 300 How often to ship; a positive integer.
MAQPNA_AUDIT_WORM_CREDENTIALS maqpna-gateway static; aws for s3 without an access key static (keys, token or SAS files) or keyless workload identity: aws (for s3), gcp (for gcs) or azure (for azure).
MAQPNA_AUDIT_WORM_ACCESS_KEY (or _FILE) maqpna-gateway — S3 access key ID (static credentials).
MAQPNA_AUDIT_WORM_SECRET_KEY (or _FILE) maqpna-gateway — S3 secret access key (static credentials).
MAQPNA_AUDIT_WORM_SESSION_TOKEN (or _FILE) maqpna-gateway — STS session token for temporary S3 credentials.
MAQPNA_AUDIT_WORM_TOKEN_FILE maqpna-gateway — File holding an OAuth bearer token (gcs, azure), re-read when it changes.
MAQPNA_AUDIT_WORM_SAS_FILE maqpna-gateway — File holding an Azure SAS query string (azure). For azure, set exactly one of the token file and the SAS file, or use azure credentials.
MAQPNA_AUDIT_WORM_ALLOW_UNLOCKED_POLICY maqpna-gateway false true accepts an unlocked GCS retention policy. Use it for test buckets only.

Identity broker, operator and attestation#

Name Used by Default Meaning
MAQPNA_BROKER_TOKEN (or _FILE) maqpna-identity — Bearer token that callers of the broker's protected API must present.
MAQPNA_BROKER_TOKEN (or _FILE) maqpna-operator, maqpna-attest — Bearer token they send to the identity broker. When empty, the operator logs that broker and attest calls are unauthenticated.
MAQPNA_IDENTITY_FEDERATION_KEY maqpna-identity — Key URI (ES256 or RS256) that signs federation JWTs for AWS STS, Google STS and Entra. Default for -federation-key.
MAQPNA_IDENTITY_FEDERATION_ISSUER maqpna-identity the -issuer value HTTPS issuer of federation JWTs. Default for -federation-issuer.
HOSTNAME maqpna-operator set by Kubernetes Pod name, recorded in the operator's version report.

Attestation agent (maqpna-attest-agent)#

The operator injects the attestation agent into tier-2 (confidential VM) sandboxes and sets these variables.

Name Used by Default Meaning
MAQPNA_ATTEST_MODE maqpna-attest-agent init init (one-shot release), sidecar (token renewal loop) or bootstrap (warm-pool sidecar). Default for --mode.
MAQPNA_ATTEST_URL maqpna-attest-agent — Base URL of maqpna-attest. Default for --attest-url.
MAQPNA_ATTEST_STATE_DIR maqpna-attest-agent /var/run/maqpna-attest Private state directory. Default for --state-dir.
MAQPNA_ATTEST_CA_FILE maqpna-attest-agent — PEM CA bundle pinned for an HTTPS attest URL. Default for --ca-file.
MAQPNA_ATTEST_RESPONSE_PUBKEY_FILE maqpna-attest-agent — Ed25519 PEM public key that must have signed attest responses. Default for --attest-response-pubkey.
MAQPNA_ATTEST_RESPONSE_PUBKEY maqpna-attest-agent — The same key as inline PEM. The operator sets this one.
MAQPNA_RELEASE_ID maqpna-attest-agent — Release ID. Default for --release-id.
MAQPNA_RELEASE_NONCE, then MAQPNA_NONCE maqpna-attest-agent — Release nonce. Default for --nonce.
MAQPNA_SAMPLE_MEASUREMENT maqpna-attest-agent — Measurement to claim in a sample report. Development only.

Sandbox environment (set by the operator)#

The operator sets these variables in the agent container of every session. The SDKs read them, so your agent code usually does not have to. maqpna dev run sets the same core variables for an agent on your laptop.

Name Set by Value Meaning
MAQPNA_GATEWAY_URL operator, maqpna dev run the gateway URL Gateway base URL.
MAQPNA_SESSION operator, maqpna dev run the session name Session ID sent with every call.
MAQPNA_AGENT operator, maqpna dev run the agent name Agent name.
MAQPNA_TOKEN_FILE operator /var/run/maqpna/token Session token file. The operator re-mints the token in place, so read it on every call.
MAQPNA_TOKEN maqpna dev run the session token Static session token for local development. Sandboxes get only the token file.
MAQPNA_TOOL_<NAME>_URL operator, maqpna dev run <gateway>/mcp/<name> One per MCP server the agent may use. <NAME> is the server name in upper case, with characters other than letters and digits replaced by _ (my-tool.v2 becomes MAQPNA_TOOL_MY_TOOL_V2_URL).
MAQPNA_MODEL_ENDPOINT operator, maqpna dev run <gateway>/llm/<route>/v1 OpenAI-compatible base URL of the governed model route.
MAQPNA_MODEL_ROUTE operator the route name Model route name.
MAQPNA_MODEL_PROVIDER operator, maqpna dev run spec.model.provider (openai in dev) Model provider of the agent.
MAQPNA_MODEL_NAME operator spec.model.name Model name.
MAQPNA_ANTHROPIC_BASE_URL operator <gateway>/llm/<route>/anthropic Native Anthropic Messages base URL, set when the model adapter is anthropic or bedrock. Use the session token as the API key.
OPENAI_BASE_URL maqpna dev run the model route URL Set for OpenAI SDKs when the local gateway proxies a model route.
MAQPNA_TASK operator the session task The task text, when it is at most 4 KiB.
MAQPNA_TASK_FILE operator /var/run/maqpna/input/task The task file, when the input comes from a Secret.
MAQPNA_WORKSPACE operator the workspace mount path (/workspace for profiles) Workspace directory, when the agent has a workspace.
MAQPNA_PARENT_SESSION operator the parent session name Set in a forked session.
MAQPNA_PROFILE operator browser or code-interpreter profile name Agent profile, for profile sandboxes.
MAQPNA_BROWSER_CDP_URL operator http://127.0.0.1:9222 Chrome DevTools URL of the browser profile.
MAQPNA_CDP_PORT operator 9222 DevTools port of the browser container.
MAQPNA_EGRESS_RELAY operator http://127.0.0.1:3128 Local egress relay of the browser profile.
MAQPNA_LIVE_VIEW operator 1 Set when live view is on for the browser profile.
MAQPNA_EVIDENCE_URL operator <gateway>/v1/sessions/<session>/evidence Where the browser profile posts evidence.
MAQPNA_EXEC_URL operator <gateway>/v1/sessions/<session>/exec Governed code execution endpoint of the code-interpreter profile.
MAQPNA_ATTEST_URL, MAQPNA_RELEASE_ID, MAQPNA_NONCE operator per session Attestation settings for tier-2 sandboxes (see above).
MAQPNA_RUNTIME maqpna dev sandbox drivers the runtime name Runtime of a local sandbox.

Sandbox helpers#

Name Used by Default Meaning
MAQPNA_EXEC_LISTEN maqpna-exec :8888 Listen address of the code execution server.
MAQPNA_EXEC_WORKDIR maqpna-exec /workspace Working directory for executed code.
MAQPNA_EXEC_MAX_TIMEOUT_SECONDS maqpna-exec 300 Longest run allowed; a positive integer.
MAQPNA_EXEC_MAX_OUTPUT_BYTES maqpna-exec 10485760 (10 MiB) Largest output kept; a positive integer.
MAQPNA_EXEC_KEY_FILE maqpna-exec — File holding the key callers must present. Must not be empty when set.
MAQPNA_EGRESS_RELAY_LISTEN maqpna-egress-relay 127.0.0.1:3128 Listen address of the egress relay.
MAQPNA_EGRESS_PROXY_URL maqpna-egress-relay — Gateway URL that egress is relayed to.
MAQPNA_TOKEN_FILE maqpna-egress-relay — Session token file sent with relayed requests.
MAQPNA_EGRESS_CA_FILE maqpna-egress-relay system roots PEM CA bundle trusted for the gateway.

maqpna-exec removes every MAQPNA_EXEC_* variable from the environment of the code it runs.

SDKs#

The Python MaqpnaClient.from_env(), the TypeScript fromEnv() and the Go ConfigFromEnv / NewFromEnv read the sandbox environment. Arguments you pass in code win over the environment.

Name Python TypeScript Go Default Meaning
MAQPNA_GATEWAY_URL yes yes yes — Gateway base URL. Required.
MAQPNA_SESSION yes yes yes — Session ID.
MAQPNA_AGENT — — yes — Agent name.
MAQPNA_TOKEN_FILE yes yes yes /var/run/maqpna/token (when no MAQPNA_TOKEN) Session token file, re-read on every request.
MAQPNA_TOKEN yes yes yes — Static session token (local development).
MAQPNA_TOOL_<NAME>_URL yes yes yes — MCP server URLs, one per server.
MAQPNA_MODEL_ENDPOINT yes yes yes — Governed model route base URL.
MAQPNA_MODEL_NAME yes yes yes — Model name of the route.
MAQPNA_MCP_PROTOCOL yes yes yes auto MCP protocol: auto, 2026-07-28 or 2025-06-18.
MAQPNA_ASYNC_APPROVALS yes yes yes off 1, true or yes: return at once when a call is held for approval, instead of waiting.
MAQPNA_DPOP — — yes off 1, true or yes: create a DPoP key and send sender-bound requests.
MAQPNA_IDENTITY_URL — — yes — Identity broker base URL.
TRACEPARENT, TRACESTATE yes yes yes — W3C trace context from a parent process, sent on every call.
MAQPNA_BOOTSTRAP_URL yes yes yes — Warm-pool pods: when set and no token is available, the SDK waits for the pod to be adopted and fetches the session from the identity broker.
MAQPNA_BOOTSTRAP_DIR yes — yes — Directory for bootstrap state.
MAQPNA_BOOTSTRAP_TOKEN_FILE yes yes yes — Also write each bootstrapped token to this file (mode 0600), for example for a sidecar.
MAQPNA_MODEL_ROUTE — — example only — Read by the Go model-loop example.

Key backends#

Any binary that loads a key URI (kms://vault/…, kms://openbao/…, kms://gcp/…, pkcs11:…) reads these. That includes the gateway, the identity broker and the CLI commands that sign.

Name Used by Default Meaning
VAULT_ADDR kms://vault, kms://openbao keys — Vault or OpenBao address. Required.
VAULT_NAMESPACE kms://vault, kms://openbao keys — Vault Enterprise namespace.
VAULT_CACERT kms://vault, kms://openbao keys system roots CA certificate for Vault TLS.
VAULT_TOKEN_FILE kms://vault, kms://openbao keys — File holding a Vault token. Checked first.
VAULT_TOKEN kms://vault, kms://openbao keys — Vault token. Checked second.
MAQPNA_VAULT_K8S_ROLE kms://vault, kms://openbao keys — Vault Kubernetes auth role. Used when no token is set.
MAQPNA_VAULT_K8S_MOUNT kms://vault, kms://openbao keys kubernetes Mount path of the Kubernetes auth method.
MAQPNA_VAULT_K8S_TOKEN_FILE kms://vault, kms://openbao keys /var/run/secrets/kubernetes.io/serviceaccount/token Service account token sent to Vault.
MAQPNA_GCP_KMS_ENDPOINT kms://gcp keys the public Cloud KMS endpoint Overrides the Cloud KMS endpoint.
MAQPNA_PKCS11_MODULE pkcs11: keys — PKCS#11 module path when the URI has no module-path.
any name in pin-source=env:NAME pkcs11: keys — The HSM PIN. The PIN is never read from the URI itself.

Cloud workload identity#

The gateway, the identity broker and the CLI use one credential library for KMS keys, the keyless WORM sink and cloud model routes. It reads the clouds' standard variables, plus a few MAQPNA ones. You can also set these in the gateway's cloudCredentials key; the config value wins.

Name Cloud Default Meaning
AWS_REGION, AWS_DEFAULT_REGION AWS — Region.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN AWS — Static credentials.
AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_ROLE_SESSION_NAME AWS — IRSA web identity.
AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE, AWS_CONTAINER_AUTHORIZATION_TOKEN AWS — EKS Pod Identity and container credentials.
AWS_ENDPOINT_URL_STS AWS — STS endpoint override.
MAQPNA_AWS_IMDS AWS false true allows the EC2 instance metadata (IMDSv2) fallback. Off by default, because on EKS it yields the node role shared by every pod.
MAQPNA_AWS_PARTITION_DNS_SUFFIX AWS derived from the region DNS suffix of the partition, for example amazonaws.eu for the European Sovereign Cloud.
AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_CLIENT_SECRET_FILE, AZURE_FEDERATED_TOKEN_FILE Azure — Entra application and Workload ID settings.
AZURE_AUTHORITY_HOST Azure the public Entra authority Entra authority host, for sovereign clouds.
AZURE_KUBERNETES_TOKEN_PROXY, AZURE_KUBERNETES_CA_FILE, AZURE_KUBERNETES_CA_DATA, AZURE_KUBERNETES_SNI_NAME Azure — AKS identity-binding token proxy.
MAQPNA_AZURE_IDENTITY_BINDING Azure false true sends Workload ID token requests through the AKS identity-binding proxy.
MAQPNA_AZURE_MANAGED_IDENTITY Azure false true allows the IMDS managed-identity fallback. Off by default, because on AKS it is the node's kubelet identity.
GOOGLE_APPLICATION_CREDENTIALS Google Cloud — Credentials file (including workload identity federation).
GCE_METADATA_HOST Google Cloud — Metadata server override.
MAQPNA_OCI_AUTH OCI — oke-workload-identity or resource-principal.
OCI_RESOURCE_PRINCIPAL_VERSION, OCI_RESOURCE_PRINCIPAL_RPST, OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM, OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM_PASSPHRASE, OCI_RESOURCE_PRINCIPAL_REGION OCI — Resource principal settings.
MAQPNA_OCI_REALM_DOMAINS OCI — Extra realm domains, comma-separated (for example oraclegovcloud.com), besides oraclecloud.com.

Sandbox drivers#

maqpna dev and the identity broker's substrate checks use the sandbox drivers. Each driver reads its own variables.

Name Driver Default Meaning
MAQPNA_AGENT_SANDBOX_NAMESPACE agent-sandbox the kubeconfig context's (or the pod's) namespace Namespace for sandboxes.
MAQPNA_AGENT_SANDBOX_RUNTIME_CLASS agent-sandbox gvisor RuntimeClass of the sandbox pods.
MAQPNA_AGENT_SANDBOX_ISOLATION agent-sandbox from the RuntimeClass Isolation class to report.
MAQPNA_AGENT_SANDBOX_API_VERSION agent-sandbox v1beta1 API version of the upstream agent-sandbox resources.
MAQPNA_AGENT_SANDBOX_GATEWAY_NAMESPACE agent-sandbox maqpna-system Namespace of the gateway pods.
MAQPNA_AGENT_SANDBOX_GATEWAY_APP agent-sandbox maqpna-gateway App label of the gateway pods.
MAQPNA_AGENT_SANDBOX_NETWORKPOLICY_ENFORCED agent-sandbox detect true asserts that the CNI enforces NetworkPolicy, false that it does not. detect looks for a NetworkPolicy-enforcing CNI among kube-system DaemonSets.
E2B_API_KEY e2b — E2B API key. Required.
E2B_DOMAIN, E2B_API_URL, E2B_SANDBOX_URL e2b the E2B defaults E2B endpoints.
MAQPNA_E2B_TIMEOUT e2b 1h Sandbox timeout, as a Go duration.
MAQPNA_E2B_USER e2b user User that runs commands in the sandbox.
MAQPNA_E2B_GATEWAY e2b — Gateway used to restore a snapshot whose source sandbox is gone.
KOSA8_HOST kosa8 the local Kosa8 socket Kosa8 API URL.
KOSA8_TOKEN kosa8 — Kosa8 API token, used with KOSA8_HOST.

Install scripts#

install.sh (macOS and Linux) and install.ps1 (Windows) read these. Each has a matching flag or parameter, which wins.

Name install.sh install.ps1 Default Meaning
MAQPNA_VERSION --version -Version the latest stable release (from the mirror's stable.txt) Version to install.
MAQPNA_BINS --bin — (-Bin only) maqpna maqpna-install maqpna-sovereign Binaries to install, space-separated.
MAQPNA_INSTALL_DIR --dir -InstallDir /usr/local/bin if writable, else ~/.local/bin; on Windows %LOCALAPPDATA%\Programs\maqpna\bin Install directory.
MAQPNA_DL_BASE --base -Base https://dl.maqpna.com Release mirror.
MAQPNA_RELEASES_URL --releases-url -ReleasesUrl the release repository listed on maqpna.com/download Release repository used when a binary is not on the mirror, or with --github / -GitHub.
MAQPNA_COSIGN --cosign / --no-cosign — (-Cosign / -NoCosign only) auto (verify when cosign is on PATH) 1 requires a valid cosign signature; 0 skips cosign.
MAQPNA_ALLOW_UNSIGNED_PLATFORM --allow-unsigned-platform -AllowUnsignedPlatform 0 1 also trusts the image-release workflow as signer (builds without Apple or Authenticode signatures). In PowerShell, 1, true or yes. 
curl -fsSL https://maqpna.com/install.sh | MAQPNA_VERSION=v2.1.0 MAQPNA_INSTALL_DIR="$HOME/.local/bin" sh

Set by the Helm chart but not read by a binary#

The chart's sovereignty helper also sets MAQPNA_REGION and MAQPNA_KEY_CUSTODY on its pods. No MAQPNA binary reads them today; they only record the declared values in the pod spec.

What can go wrong#

Symptom Cause Fix
MAQPNA_ADMIN_TOKEN_FILE: … is empty at gateway start The _FILE file exists but is empty. Write the token into the file, or unset MAQPNA_ADMIN_TOKEN_FILE.
audit sink 'worm' requires MAQPNA_AUDIT_WORM_ENDPOINT and MAQPNA_AUDIT_WORM_BUCKET MAQPNA_AUDIT_SINK=worm without a store. Set both, or set the chart's WORM values.
configSync.namespace is required (or set POD_NAMESPACE) configSync is on outside a pod. Set configSync.namespace in gateway.json.
context "x" is not defined (maqpna context list) MAQPNA_CONTEXT names a context that is not in the config file. Run maqpna context list, then unset or fix MAQPNA_CONTEXT.
The SDK raises gatewayUrl is required (set MAQPNA_GATEWAY_URL) The agent runs outside a sandbox or maqpna dev run. Run it with maqpna dev run -- <command>, or pass the gateway URL in code.
MAQPNA_EXEC_MAX_TIMEOUT_SECONDS must be a positive integer A non-numeric or zero value. Set a positive whole number of seconds.

Next steps#