Glossary

This glossary defines the key fields, concepts, and identifiers used across Axemere Gateway documentation and APIs. Every term includes its definition, who sets it, where it flows, its format, and an example value.

Identity and Tenancy
Attribution and Billing
Request and Action
HTTP Headers
Credentials and Delegation
Policy and Decisions
Infrastructure
Observability
Proxy and MITM
Environment Variables

Identity and Tenancy

`org_id`

Definition: The tenant identifier for your organization within Axemere Gateway. In hosted SaaS mode, org_id values are provisioned by the Control Plane via OrgService.ProvisionOrg and take the form of a UUIDv7. In embedded (self-hosted) mode, it is a free-form string you assign yourself.

Who sets it: The Axemere operator. In SaaS mode, the Control Plane assigns it during provisioning and returns it in ProvisionOrgResponse.org_id. In embedded mode, you choose the value and set it via MVGC_ORG_ID.

Where it flows: Present on every ActionRequest; stored in every ExecutionRecord, ApprovalRequest, and QuarantineEntry; used as a partition key in risk scoring, budget tracking, and dashboard queries; sent in gRPC calls (RegisterNode, SubmitRecordHash, GetPolicyBundle).

Tenant collision risk (SaaS mode): In distributed mode the gateway rejects requests whose org_id does not match MVGC_ORG_ID. Bootstrap tokens are scoped to exactly one org; a node registered with a token cannot operate as another tenant.

Format: UUIDv7 string (SaaS) or operator-defined string (embedded).

Example: "019508a3-1234-7abc-bdef-000000000001" (SaaS) or "org-example-001" (embedded).

`workload_id`

Definition: Identifies the logical workload (application, service, or team) submitting a request. Workloads are registered in the embedded control plane or via the admin API and carry default_attribution and allowed_connection_types.

Who sets it: The calling application developer, using a value registered by the operator.

Where it flows: Required on every ActionRequest; stored in execution records, approval requests, and quarantine entries; used as a key in risk scoring and budget tracking.

Format: Operator-defined string.

Example: "wl-prod-app-1"

`caller_id`

Definition: Identifies the specific caller within a workload -- often a user ID, service account, or agent instance. Optional but useful for per-caller policy rules and audit trails.

Who sets it: The calling application.

Where it flows: Included in ActionRequest and stored in execution records and approval requests.

Format: Operator-defined string.

Example: "user-42", "svc-billing", "caller-001"

`caller_ip`

Definition: The IP address of the client that sent the request, as observed at the gateway. Used for security audit and incident investigation.

Who sets it: The gateway, extracted server-side from the HTTP request. Never taken from the request body, so clients cannot inject a spoofed value.

Source priority:

X-Forwarded-For header (leftmost address in the comma-separated list)
X-Real-IP header
r.RemoteAddr (TCP remote address, port stripped)

Security note: X-Forwarded-For can be forged by clients when the gateway is not behind a trusted reverse proxy. Configure your load balancer or ingress to strip or overwrite this header before it reaches the gateway if IP integrity is required for access control decisions.

Where it flows: Stored in the ExecutionRecord JSON and in the caller_ip column of the execution_records Postgres table.

Format: IP address string (IPv4 or IPv6), no port.

Example: "203.0.113.42", "2001:db8::1"

`node_id`

Definition: Identifies a specific gateway instance. Set via MVGC_NODE_ID. In distributed mode the gateway registers its node_id with the Control Plane.

Who sets it: The gateway operator via MVGC_NODE_ID (default: "node-local-dev").

Where it flows: Stored in every execution record; sent in RegisterNode and SubmitRecordHash gRPC calls; used as a key in key_registry and node_registry tables.

Format: Operator-defined string, unique per gateway instance.

Example: "gw-prod-us-east-1", "node-local-dev"

Attribution and Billing

`project_id`

Definition: Associates a request with a billing project for chargeback and spend reporting. Required by budget enforcement rules.

Who sets it: The calling application in the attribution object.

Where it flows: Stored in execution records; used as the key in budget_spend table; used in /v1/reports/usage and /v1/reports/spend query parameters.

Format: Operator-defined string.

Example: "proj-123", "proj-frontend-qa"

`customer_id`

Definition: Identifies the end customer on behalf of whom the request is made. Useful for multi-tenant applications billing downstream customers.

Who sets it: The calling application in the attribution object.

Where it flows: Stored in execution records; available in policy DSL as context.attribution.customer_id.

Format: Operator-defined string.

Example: "cust-42", "tenant-acme-corp"

`account_id`

Definition: Identifies an account or team within your organization. Useful for departmental chargeback.

Who sets it: The calling application in the attribution object.

Where it flows: Stored in execution records; available in policy DSL as context.attribution.account_id.

Format: Operator-defined string.

Example: "acct-12", "team-infra"

`attribution`

Definition: An object grouping customer_id, account_id, project_id, and labels for chargeback and reporting. Fields not supplied by the caller are filled in from the workload's default_attribution config.

Who sets it: The calling application (partial or full); missing fields are back-filled from workload defaults.

Format: JSON object.

Example:

{
  "customer_id": "cust-42",
  "account_id":  "acct-12",
  "project_id":  "proj-123",
  "labels":      {"env": "prod", "team": "ml"}
}

`labels`

Definition: Arbitrary key-value pairs attached to the attribution object for additional segmentation or filtering in reports and policy rules.

Who sets it: The calling application.

Format: JSON object with string keys and string values.

Example: {"env": "prod", "region": "us-east-1"}

Request and Action

`request_id`

Definition: A client-supplied idempotency key for the request. If omitted, the gateway generates a UUIDv7.

Who sets it: The calling application (optional).

Where it flows: Echoed in the response body; stored in the execution record; used in approval matching.

Format: Unique string; UUIDv7 if auto-generated.

Example: "req-001", "019508a3-abcd-7def-9012-000000000001"

`connection_type`

Definition: The transport mechanism used to reach the gateway. Assigned automatically by the gateway; callers do not set this field.

Value	UI label	Description
`direct_api`	Direct API	Structured `ActionRequest` JSON body submitted to `POST /v1/actions:execute`
`sdk_redirect`	SDK Redirect	AI SDK pointed at the gateway via a base URL setting (e.g. `ANTHROPIC_BASE_URL`); gateway receives provider-format HTTP requests
`connect_proxy`	System Proxy	OS-level HTTPS proxy (`HTTPS_PROXY`); gateway performs TLS interception (MITM)

Who sets it: The gateway, based on which listener received the request and whether the request used HTTP CONNECT.

Where it flows: Stored in execution records; available as context.connection_type in policy conditions; surfaced as a filter and column in the Records UI.

`traffic_class`

Definition: The behavioral intent of the traffic: why this request is here. Assigned automatically by the gateway based on which port the connection arrived on.

Value	UI label	Description
`developer`	Developer	Deliberate per-session developer routing: SDK calls, CLI tools, or a manually set `HTTPS_PROXY` in a shell
`ambient`	Ambient	Background traffic from apps configured once via `mvgc-gateway install` or a PAC file: includes heartbeats, polling, and preflight requests

Who sets it: The gateway. direct_api and sdk_redirect are always developer. connect_proxy traffic is developer when arriving on port 7080 (developer listener) and ambient when arriving on port 7081 (ambient listener, activated by mvgc-gateway install).

Where it flows: Stored in execution records; surfaced as a primary filter in the Records UI.

`action.type`

Definition: Semantic type of the action being performed.

Who sets it: The calling application.

Common values: "ai.infer" (inference request to an AI provider), "ai.embed", "ai.moderate".

Format: Dot-separated string.

Example: "ai.infer"

`action.target_host`

Definition: The hostname of the upstream AI provider to route to.

Who sets it: The calling application.

Where it flows: Used by the connector manager to select the appropriate connector; evaluated in targets policy layer; stored in execution records and approval requests.

Format: Hostname without scheme or path.

Example: "api.openai.com", "api.anthropic.com", "generativelanguage.googleapis.com"

`action.target_path`

Definition: The path on the upstream provider host. If omitted, the connector uses its default (e.g. /v1/chat/completions for OpenAI).

Who sets it: The calling application (optional).

Example: "/v1/chat/completions", "/v1/messages"

`action.params`

Definition: The provider-specific request body -- the JSON payload forwarded to the upstream API (e.g. model, messages, max_tokens).

Who sets it: The calling application.

Format: JSON object.

Example:

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 50
}

`idempotency_key`

Definition: A caller-supplied deduplication key included in an ActionRequest. The gateway checks for an existing execution record with the same (org_id, idempotency_key) pair. If found, it replays the cached result without re-executing the connector call. When set, the key is also forwarded to upstream providers that support it via the Idempotency-Key HTTP header (e.g. OpenAI, Anthropic).

Who sets it: The calling application (optional).

Where it flows: Stored in the idempotency_key column of execution_records; forwarded to upstream providers as Idempotency-Key header; returned in the execution record response.

Scope: Per org_id -- different orgs can reuse the same key without collision.

Format: Arbitrary string, typically a business-meaningful identifier.

Example: "payment-batch-2026-03-12-item-47", "order-12345-retry-2"

HTTP Headers

In transparent proxy mode, attribution and identity are passed via X-MVGC-* request headers instead of a JSON body. These headers are the proxy-mode equivalents of the corresponding ActionRequest JSON fields.

`X-MVGC-Org-ID`

Definition: Proxy-mode equivalent of org_id. Identifies the tenant organization for the request.

Required in proxy mode: Yes.

Maps to: org_id in the execution record and policy evaluation context.

Format: Same as org_id.

Example: X-MVGC-Org-ID: org-example-001

`X-MVGC-Workload-ID`

Definition: Proxy-mode equivalent of workload_id. Identifies the logical workload submitting the request.

Required in proxy mode: Yes.

Maps to: workload_id in the execution record and policy evaluation context.

Format: Same as workload_id.

Example: X-MVGC-Workload-ID: wl-prod-app-1

`X-MVGC-Project-ID`

Definition: Proxy-mode equivalent of attribution.project_id. Associates the request with a billing project for chargeback and spend reporting.

Required in proxy mode: No (optional). Falls back to the workload's default_attribution.project_id when omitted.

Maps to: attribution.project_id.

Format: Same as project_id.

Example: X-MVGC-Project-ID: proj-123

`X-MVGC-Customer-ID`

Definition: Proxy-mode equivalent of attribution.customer_id. Identifies the end customer on behalf of whom the request is made.

Required in proxy mode: No (optional). Falls back to workload defaults when omitted.

Maps to: attribution.customer_id.

Format: Same as customer_id.

Example: X-MVGC-Customer-ID: cust-42

`X-MVGC-Account-ID`

Definition: Proxy-mode equivalent of attribution.account_id. Identifies an account or team within your organization for departmental chargeback.

Required in proxy mode: No (optional). Falls back to workload defaults when omitted.

Maps to: attribution.account_id.

Format: Same as account_id.

Example: X-MVGC-Account-ID: acct-12

`X-MVGC-Target-Host`

Definition: Proxy-mode header to explicitly declare the upstream AI provider hostname. Acts as the highest-priority override in the target host resolution chain: (1) this header, (2) request Host header, (3) /proxy/{provider}/ path prefix, (4) 400 error.

Required in proxy mode: No (optional). Needed only for Azure OpenAI or other providers not in the built-in provider registry, or to override path-prefix routing for a specific request.

Maps to: action.target_host.

Format: Hostname without scheme or path. Same as action.target_host.

Example: X-MVGC-Target-Host: my-resource.openai.azure.com

`path-prefix routing`

Definition: The mechanism by which the gateway resolves the upstream AI provider from the /proxy/{provider}/ URL prefix. When a request arrives at a path starting with /proxy/, the gateway reads the first path segment after /proxy/ as the provider ID, strips the prefix, and forwards the remainder of the path to the provider's base URL.

Supported providers: openai (api.openai.com), anthropic (api.anthropic.com), gemini (generativelanguage.googleapis.com), cohere (api.cohere.com). Azure OpenAI has no fixed upstream hostname and is not in the provider registry; use X-MVGC-Target-Host instead.

Usage: Set the SDK base URL to http://<gateway>:<port>/proxy/<provider>. The SDK sends all requests to that base URL; the gateway resolves the provider automatically. No gateway config change is required.

Resolution order: If X-MVGC-Target-Host is present it takes precedence. If not, the request Host header is checked. If neither provides a usable hostname, the path prefix is tried. If none resolves, the gateway returns HTTP 400.

Example: ANTHROPIC_BASE_URL=http://localhost:7080/proxy/anthropic

`provider registry`

Definition: The gateway's built-in mapping from provider IDs to upstream base URLs, used by path-prefix routing. The registry currently contains:

Provider ID	Upstream base URL
`openai`	`api.openai.com`
`anthropic`	`api.anthropic.com`
`gemini`	`generativelanguage.googleapis.com`
`cohere`	`api.cohere.com`

Providers not in this registry (e.g. Azure OpenAI) must use X-MVGC-Target-Host.

`auto-rule`

Definition: A policy rule automatically generated and managed by the control plane when a credential of type ai_provider is registered via UpsertCredential. Auto-rules follow the naming convention auto.allow.{provider} (e.g. auto.allow.openai) and are inserted into the connectors and credentials layers of the org's policy overlay.

When a credential is deleted via DeleteCredential, the corresponding auto-rules are removed from the overlay automatically. Auto-rules use the auto. prefix so they can be identified and managed separately from operator-authored rules.

Who creates them: The control plane on UpsertCredential. Not written to any file; stored in the org's policy overlay in the CP database.

Scope: Applies to the org that owns the credential. Self-hosted gateways using file-based policy do not have auto-rules; see the configs/policies/credential-rules.yaml example instead.

Example rule ID: auto.allow.anthropic

`X-MVGC-Delegation-ID`

Definition: Proxy-mode equivalent of delegation_id. A reference identifier for a delegation token, recorded in the execution record for audit purposes.

Required in proxy mode: No (optional).

Maps to: delegation_id.

Notes: In proxy mode the delegation token payload is not verified: the ID is recorded but the token signature is not checked by the gateway. Use explicit action request mode for full delegation token verification.

Format: Operator-defined string. Same as delegation_id.

Example: X-MVGC-Delegation-ID: dt-abc123

Credentials and Delegation

`api_key`

Definition: Long-lived credential used to authenticate requests to Axemere Gateway in managed gateway mode. The plaintext key is returned exactly once at creation time via OrgService.CreateAPIKey. The control plane stores only the SHA-256 hash of the key; the gateway validates incoming requests by hashing the presented key and comparing it against the stored hash.

Who sets it: The Axemere operator or platform automation, via the control plane gRPC OrgService.CreateAPIKey endpoint.

Where it flows: Sent by clients in the Authorization: Bearer <key> HTTP header on every gateway request. The key hash is stored in the api_keys table along with the associated org_id, scopes, and expiry. Never logged in plaintext.

Format: Opaque string prefixed with mvgc_k_.

Example: "mvgc_k_abc123...xyz789"

`credential_id`

Definition: Unique identifier for a server-side credential registration (alias mode). Callers reference the credential_id instead of the raw API key.

Who sets it: The gateway operator via the admin API (PUT /v1/admin/credentials).

Format: Operator-defined string.

Example: "cred-openai", "cred-anthropic"

`credential_hint`

Definition: Per-request credential override.

byok: Supply the raw API key. The gateway passes it to the provider.
alias: Supply a credential_id. The gateway resolves the secret server-side.

If omitted, the policy engine selects a credential via SelectedCredentialID.

Who sets it: The calling application (optional).

Where it flows: Passed to the credential resolver; never logged.

`connector_hint`

Definition: An optional field in an ActionRequest that overrides automatic connector selection for the request. When set, the gateway routes to the specified connector instead of deriving the connector from action.target_host. Only available in explicit action request mode; ignored in transparent proxy mode.

Who sets it: The calling application (optional).

Where it flows: Passed to the connector manager; stored in the execution record.

Valid values: Any connector_id registered on the gateway. Built-in values: openai, anthropic, gemini, azure_openai, generic_http. Use GET /v1/admin/connectors to list all registered connectors.

Format: String.

Example: "connector_hint": "anthropic"

`secret_ref`

Definition: The name of the environment variable that holds the API key for an alias credential. The gateway calls os.Getenv(secret_ref) at request time.

Who sets it: The gateway operator in the credential configuration YAML and admin API.

Format: Environment variable name (uppercase, underscores).

Example: "OPENAI_API_KEY", "ANTHROPIC_API_KEY"

credential modes

Mode	Description
`byok`	Caller supplies the API key in `credential_hint`. No server-side config needed.
`alias`	Operator registers a credential with `secret_ref`; gateway resolves the key at runtime. Caller never sees the key.

`distribution`

Definition: Controls which gateway nodes receive a credential when the CP distributes its credential set. One of org_wide or node_scoped.

Value	Meaning
`org_wide`	Credential is delivered to every node in the org via `ListNodeCredentials`.
`node_scoped`	Credential is only delivered to nodes that have an explicit assignment in `node_credential_assignments`.

Who sets it: Operator via CredentialService.UpsertCredential. Immutable after creation: changing distribution requires deleting and re-creating the credential.

Where it flows: Stored in credentials.distribution; evaluated in ListNodeCredentials query.

`credential_type`

Definition: Classifies the purpose of a credential. Determines whether it is distributed to gateway nodes.

Value	Meaning
`ai_provider`	API key for an AI backend (OpenAI, Anthropic, etc.). Delivered to nodes via `ListNodeCredentials`.
`export_auth`	Auth token for a SIEM/webhook export destination. Never distributed to gateway nodes via `ListNodeCredentials`; resolved only on the CP side via `GetNodeExportDestinations`.

Who sets it: Operator via CredentialService.UpsertCredential.

node credential assignment

Definition: An explicit mapping between a node_scoped credential and a specific gateway node, stored in the node_credential_assignments junction table. Created via CredentialService.AssignNodeCredential and removed via UnassignNodeCredential. Can also be created atomically at node registration via RegisterNodeRequest.initial_credential_ids.

Key constraint: Only node_scoped credentials can be assigned. Attempting to assign an org_wide credential returns INVALID_ARGUMENT.

export destination

Definition: Configuration record for a SIEM or webhook endpoint where a gateway node ships audit events. Stored in export_destinations; may be org-level (shared default, node_id IS NULL) or node-specific (node_id set).

Resolution order for a node:

If the node has its own destinations → use them exclusively.
If the node list is empty and inherit_org_defaults = true → fall back to org-level destinations.
If inherit_org_defaults = false → no export (node silences org defaults).

Managed via: ExportConfigService gRPC service.

`delegation_id`

Definition: A reference identifier for a delegation token. Logged for audit purposes.

Who sets it: The calling application (optional, alongside delegation_token).

Example: "dt-abc123"

`delegation_token`

Definition: A base64-encoded, Ed25519-signed JSON token that grants a downstream workload scoped, time-limited authorization. The gateway verifies the signature, checks expiry, and populates delegation context for policy evaluation.

Wire format: Schema "mvgc.delegation.v2" (per wire spec section 4.2). Includes org_id and workload_id scoping fields -- the gateway validates that org_id matches the request and that the token is used by the declared workload.

Who sets it: An upstream service that creates and signs the token using delegation.CreateToken.

Format: Base64-encoded JSON.

Verification: Set MVGC_DELEGATION_VERIFY_KEY to the public key PEM.

Policy and Decisions

`effective_bundle`

Definition: The result of merging a base policy bundle with org-level and node-level policy overlays. In managed gateway mode, the control plane pre-computes and caches effective bundles in the effective_bundles table. Gateways receive the effective bundle rather than the raw layers, reducing merge overhead at request time.

Merge order: Base bundle -> org overlay -> node overlay. Later layers override earlier ones.

Where it flows: Stored in effective_bundles (keyed by org_id, node_id, bundle_id); pushed to gateways via PolicyUpdatedEvent in managed mode or returned by GetPolicyBundle in self-hosted mode.

`plan_tier`

Definition: Subscription level for an organization controlling which policy overlay layers are permitted. Stored in the org_plans table.

Tiers:

Tier	Overlay Layers Allowed
`starter`	`identity`, `budgets`
`pro`	All standard layers
`enterprise`	All layers + custom

Who sets it: The platform operator via the org_plans table.

Where it flows: Enforced when UpdateOrgPolicyOverlay is called -- overlays referencing layers not permitted by the tier are rejected.

Format: One of "starter", "pro", "enterprise".

`policy_bundle_id` (also `bundle_id`)

Definition: Identifies the policy bundle loaded by the gateway. Set in the bundle YAML header. In distributed mode, the gateway fetches the bundle specified by MVGC_BUNDLE_ID from the Control Plane.

Who sets it: The policy author in the YAML front-matter; operators set MVGC_BUNDLE_ID.

Example: "bundle-inline-001", "default"

`policy_overlay`

Definition: Org-specific or node-specific partial YAML that modifies a base policy bundle. Overlays must only reference layers permitted by the organization's plan tier. Org overlays are stored in org_policy_overlays; node overlays are stored in node_policy_overlays.

Who sets it: Org admins via PolicyService.UpdateOrgPolicyOverlay (org level); platform operators via the node_policy_overlays table (node level).

Where it flows: Merged with the base bundle to produce the effective bundle distributed to gateways.

Format: YAML following the same structure as a policy bundle, but only including the layers and rules to be overridden.

`decision`

Definition: The outcome of policy evaluation for a request.

Value	HTTP	Meaning
`allow`	200	Request is permitted and executed
`deny`	403	Request is blocked
`downgrade`	200	Request is allowed with mutations (e.g. model swap)
`require_approval`	202	Request held for manual approval
`rate_limit`	429	Request rate-limited; check `Retry-After`
`quarantine`	403	Request blocked and quarantined due to risk signals
`require_attribution`	403	Request denied; required attribution fields are missing (see `require_attribution`)

`require_attribution`

Definition: A policy decision type that denies a request because required attribution fields (customer_id, account_id, or project_id) are missing. Distinct from a generic deny -- the reason_codes array in the response lists the specific missing fields, guiding the caller to include them on retry.

HTTP status: 403 Forbidden with "error": "require_attribution".

Short-circuits evaluation: require_attribution is included in the bundle stop_on list, so evaluation halts immediately when any rule produces this decision -- subsequent layers are not evaluated.

Who triggers it: The policy engine, when a rule evaluates the require_attribution effect and the request lacks the required attribution fields.

Caller action: Add the missing attribution fields listed in reason_codes and re-submit the request.

Example reason_codes: ["missing:customer_id", "missing:project_id"]

`policy_trace`

Definition: Diagnostic information about which rules matched during policy evaluation. Included in execution records and API responses.

Fields: bundle_id, version, matched_rule_ids.

`stop_on`

Definition: A list of decision types that cause policy evaluation to halt immediately when any rule produces that decision. Configured in the policy bundle header under evaluation.stop_on. Subsequent layers are not evaluated once a matching decision is reached.

Who sets it: The policy author in the bundle YAML front-matter.

Where it flows: Evaluated by the policy engine after each layer; controls short-circuit behavior.

Format: YAML list of decision strings.

Example: stop_on: [deny, require_approval, require_attribution]

`merge_strategy`

Definition: Controls how decisions from multiple matching rules within a layer are combined. Configured in the policy bundle header under evaluation.merge_strategy.

Who sets it: The policy author in the bundle YAML front-matter.

Values:

Value	Behavior
`first_match`	Use the decision from the first matching rule (by priority, descending); ignore subsequent matches
`strict`	All matching rules must agree on the decision; conflict results in `deny`

Default: first_match

Example: merge_strategy: first_match

`inline_rules`

Definition: A map of layer names to rule lists embedded directly in the policy bundle YAML, rather than referencing external rule files via the files key. When both inline_rules and files are present in a bundle, inline_rules takes precedence. Enables fully self-contained bundle pushes via PUT /v1/admin/policies without requiring files to exist on the gateway filesystem.

Who sets it: The policy author or operator pushing a hot-reload bundle.

Where it flows: Parsed at bundle load time; rules are merged into the evaluation context as if loaded from files.

Format: YAML map from layer name to list of rule objects.

Example:

inline_rules:
  identity:
    - id: identity.allow.all
      priority: 100
      when:
        field: context.connection_type
        equals: direct_api
      effect:
        decision: allow

`model_override`

Definition: An effect type in the transforms policy layer that replaces the model specified in the request with a substitute value before the request is forwarded to the upstream provider. Used to implement cost-based model downgrade without modifying the caller's request.

Who sets it: The policy author in a transforms-layer rule.

Where it flows: Applied by the policy engine to action.params.model before connector dispatch; stored in the execution record's policy_trace as a matched mutation.

DSL key: action.params.model (via mutations list in the rule effect)

Other mutable keys: action.headers.*, action.target_host, action.target_path, action.method, action.params.* (any dot-path key in the action)

Example:

transforms:
  - id: transforms.downgrade.cost_spike
    priority: 100
    when:
      field: context.risk.signals
      in: ["cost_anomaly"]
    effect:
      decision: downgrade
      mutations:
        - key: action.params.model
          value: "gpt-4o-mini"

policy add-on

Definition: A self-contained YAML rule file placed in the available/ subdirectory under MVGC_POLICIES_DIR. An add-on becomes active when a symlink (or copy) to it is present in the addons/ subdirectory. The gateway loads all add-ons from addons/ on startup when the active bundle has no inline_rules or files: list. This provides a Unix-style drop-in mechanism for enabling and disabling policy rules without modifying the bundle or rewriting rule files.

Who sets it: The gateway administrator using mvgc-gateway addon enable <name> / mvgc-gateway addon disable <name>.

Where it flows: Loaded by FileLoader.loadAddons() on startup; rules are merged into the policy evaluation context by layer.

Format: YAML file with schema: mvgc.rule_file.v1, a layer field, and a rules list. Filename (without .yaml) is the add-on name.

Catalog: Core add-ons shipped by default: core-identity, provider-openai, provider-anthropic, provider-gemini, provider-azure-openai, provider-cohere, deny-unknown-host. Optional: claude-cli-proxy.

Example:

schema: mvgc.rule_file.v1
layer: connectors
rules:
  - id: proxy.allow.openai
    priority: 100
    when:
      field: action.target_host
      equals: api.openai.com
    effect:
      decision: allow
      select_credential: cred-openai

`approval_id`

Definition: UUID assigned to an approval request when a policy returns require_approval. Returned in the HTTP 202 response body. Used to track, approve, or deny the held request via the admin API.

Who sets it: The gateway (auto-generated UUID).

Format: UUID string.

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Infrastructure

`check-in`

Definition: Periodic gRPC call from a self-hosted gateway to the control plane to detect stale policy, workload, credential, or export configurations. The gateway sends its current version strings for each resource; the control plane responds with staleness flags. The gateway only fetches updated resources when a version is stale.

RPC: RegistryService.CheckIn

Request fields: node_id, org_id, policy_bundle_version, workloads_version, credentials_version, export_config_version

Response fields: policy_stale, workloads_stale, credentials_stale, export_config_stale, min_idle_threshold (int64 seconds; 0 = no change)

Interval: Configurable via MVGC_CHECKIN_IDLE_THRESHOLD (default: 60 seconds). The control plane may also return a min_idle_threshold in the response to adjust the interval server-side.

Where it flows: Sent by the gateway at each interval; response drives subsequent GetPolicyBundle, GetWorkloads, ListNodeCredentials, or GetNodeExportDestinations fetches.

`config syncer`

Definition: Gateway component that keeps configuration synchronized with the control plane. In self-hosted mode, it runs a periodic check-in loop. In managed mode, it subscribes to a gRPC streaming channel (ConfigService.SubscribeUpdates) and applies configuration events in real time.

Modes:

Gateway Mode	Sync Mechanism
`self-hosted`	Polling via `CheckIn` + fetch on stale
`managed`	Streaming via `SubscribeUpdates`

`credential cache`

Definition: In-memory store of credential configurations fetched from the control plane. Uses a 60-second TTL -- shorter than the workload cache because credential changes (especially revocations) are security-sensitive. In managed mode, CredentialUpdatedEvent pushes revocations immediately, bypassing the TTL.

TTL: 60 seconds

`embedded mode`

Definition: The default operating mode of Axemere Gateway. In embedded mode, the gateway runs as a single binary with its own Postgres-backed control plane. No external Control Plane service is required. Policy files are loaded from MVGC_POLICIES_DIR; configuration is managed via the local admin API. Embedded mode is the recommended starting point for new deployments.

Contrast: distributed mode

Activated by: Default (no MVGC_CP_ADDR set)

Example env: # MVGC_CP_ADDR is unset

`distributed mode`

Definition: An optional operating mode activated by setting MVGC_CP_ADDR. In distributed mode, the gateway connects to the hosted Axemere Control Plane over gRPC/mTLS to: register its node identity, fetch signed policy bundles, submit execution record hashes to the central ledger, and participate in Merkle batching and anchoring. Embedded policy loading and local config remain available as a fallback when the CP is unreachable.

Contrast: embedded mode

Activated by: Setting MVGC_CP_ADDR to the CP gRPC address

Example env: MVGC_CP_ADDR=gcp.cp.axemere.ai:9090

`bootstrap_token`

Definition: A one-time credential that a gateway node presents to the Control Plane during initial registration (RegisterNode). In SaaS mode, bootstrap tokens are issued by OrgService.CreateBootstrapToken, stored as SHA-256 hashes, scoped to exactly one org_id, single-use, and expiry-bounded. In embedded mode, the token is a free-form string set via MVGC_BOOTSTRAP_TOKEN.

Who sets it: SaaS: operator calls CreateBootstrapToken after provisioning an org. Embedded: operator sets MVGC_BOOTSTRAP_TOKEN env var.

SaaS collision protection: The Control Plane enforces req.OrgId == token.org_id. A token issued for org A cannot be used to register a node as org B.

Format: Base64url string (SaaS) or operator-defined string (embedded).

`kid` (key ID)

Definition: The identifier for an Ed25519 key pair. Computed as a base32-encoded SHA-256 hash of the public key bytes. Embedded in every signed execution record envelope.

Who sets it: Computed automatically from the public key.

Format: "kid_<base32>".

Example: "kid_ABCDEFGHIJ2345678"

`managed gateway`

Definition: Axemere Gateway operating in multi-tenant SaaS mode with API key authentication, per-org policy isolation, streaming configuration updates, and usage metering. In managed mode, the gateway authenticates every request against the api_keys table and derives the org_id from the key. Configuration is pushed to gateways in real time via ConfigService.SubscribeUpdates.

Contrast: self-hosted gateway

Activated by: MVGC_GATEWAY_MODE=managed

See also: Managed Gateway Guide

`record_id`

Definition: Unique identifier for an execution record. Auto-generated as a UUIDv7 by the gateway when a request completes (or is denied).

Who sets it: Gateway.

Where it flows: Returned in API responses; primary key in execution_records Postgres table; used in the Merkle tree and ledger.

Format: UUIDv7 string.

Example: "019508a3-1234-7abc-bdef-000000000001"

`self-hosted gateway`

Definition: Axemere Gateway deployed by a customer with pull-based check-in for configuration distribution. The gateway polls the control plane at a configurable interval (default 60 seconds) and supports durable policy caching for offline resilience. Authentication uses bootstrap tokens rather than API keys.

Contrast: managed gateway

Activated by: MVGC_GATEWAY_MODE=self-hosted (default)

`workload cache`

Definition: In-memory store of workload configurations fetched from the control plane. Uses a 5-minute TTL. In managed mode, WorkloadUpdatedEvent pushes changes immediately, supplementing the TTL-based refresh.

TTL: 5 minutes

Observability

`org_monthly_usage`

Definition: Per-organization metering aggregate tracking request counts, token usage, and cost for a billing period. Stored in the org_monthly_usage table, keyed by (org_id, period_start) where period_start is the first day of the billing month.

Metrics:

Field	Description
`request_count`	Total requests processed
`tokens_in`	Total input tokens consumed
`tokens_out`	Total output tokens generated
`cost_usd_millicents`	Total cost in millicents (1/1000 of a cent)
`workloads_active`	Number of active workloads during the period

Where it flows: Incremented by the gateway after each successful request; queried by billing and usage reporting systems.

`cost_usd`

Definition: The estimated or final cost of a single request in US dollars, represented as an exact decimal string (e.g. "0.003750"). Never stored as floating-point.

How it is computed: At request time, the gateway computes a cost_estimate_usd from the model name, input token count, and max_tokens cap. After the upstream provider responds, the actual output token count is used to compute the final cost_usd stored in the execution record. See the Pricing Reference for per-model rates.

Where it flows: Written to execution_records.cost_usd; aggregated into org_monthly_usage.cost_usd_millicents; enforced by budget.usd_max policy rules.

Format: Decimal string, e.g. "0.003750" (USD)

See also: Pricing Reference

`risk score`

Definition: A composite float in [0.0, 1.0] computed from four signals before each request is evaluated. Available to policy DSL rules via context.risk.score.

Signals: rate_spike (0.40), cost_anomaly (0.30), target_diversity (0.15), time_of_day (0.15).

`risk signals`

Definition: The names of active risk signals for the current request. Available in policy DSL via context.risk.signals.

Example: ["rate_spike", "cost_anomaly"]

`quarantine_id`

Definition: UUID assigned to a quarantine entry when a policy returns quarantine. Used to identify the entry in admin API operations (list, release).

Who sets it: Gateway (auto-generated UUID).

Format: UUID string.

Example: "q9z8y7x6-..."

`execution record`

Definition: The canonical, tamper-evident record of every request processed by the gateway. Contains the policy decision, attribution context, action metadata, metering data (tokens, cost), and an Ed25519 signature. Stored in the execution_records Postgres table and optionally in a JSONL audit log. Every request, including denied, rate-limited, and quarantined ones, produces an execution record.

Schema: mvgc.execution_record.v2

`record_hash`

Definition: The hex-encoded SHA-256 hash of the JCS-canonical (RFC 8785) serialization of an execution record. Used as the leaf value in the Merkle tree and as the key for inclusion proof lookups. Returned in every action response as X-MVGC-Record-Hash and in the response body.

Format: 64-character hex string.

Example: "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"

`inclusion proof`

Definition: A cryptographic proof that a specific execution record was included in a Merkle batch at a specific position. Consists of the sibling hash path from the leaf to the Merkle root, plus the signed root metadata. Returned by GET /v1/verify/{record_hash} when the record has been batched.

Schema: mvgc.inclusion_proof.v1

Fields: record_hash, batch_id, leaf_index, leaf_count, path (sibling hashes), root (signed root metadata).

See also: Merkle Proof Verification, anchor

`anchor`

Definition: An optional external timestamp binding for a Merkle root. When anchoring is enabled, the control plane submits the root_hash to an RFC 3161 Timestamp Authority (TSA) after building each Merkle batch. The TSA returns a signed timestamp token that proves the root existed at or before the TSA's genTime. The token is stored in the anchor.ref field of the root metadata.

Type: rfc3161 (v1 only type)

Fields: type, ref (base64-encoded DER TimeStampToken), published_at

`overlay layer`

Definition: A policy customization that overrides or extends a specific layer of the base bundle. Org overlays and node overlays follow the same layer structure as a policy bundle (identity, delegation, targets, budgets, risk, etc.) but only need to include the layers being modified. Layers permitted in overlays are determined by the org's plan tier.

Three levels: base bundle → org overlay (org_policy_overlays) → node overlay (node_policy_overlays) → effective bundle

`scope` (delegation token)

Definition: The set of restrictions embedded in a delegation token that limit what actions the token holder may perform. Contains up to four fields:

Field	Description
`actions_allow`	Permitted action types (e.g. `["ai.infer"]`)
`targets_allow`	Permitted target hostnames (e.g. `["api.openai.com"]`)
`methods_allow`	Permitted HTTP methods (e.g. `["POST"]`)
`resource_patterns_allow`	Permitted URL path patterns (Go regex)

An empty or omitted list means no restriction on that dimension. The gateway intersects the token scope with policy; both must permit the action.

`model_tokens_max`

Definition: A per-delegation token cap on total model tokens (input + output combined) for the token's lifetime. Enforced by the gateway alongside usd_max. Requests that would exceed the cap are denied.

Field location: budget.model_tokens_max in the delegation token JSON.

`target diversity`

Definition: A risk signal that fires when the number of distinct target hosts contacted by a workload in a recent time window exceeds a multiple of the baseline. Weight: 0.15 of the composite risk score. Default threshold multiplier: 2.0 (MVGC_RISK_TARGET_DIVERSITY_THRESHOLD).

Limitation: The 5-minute baseline window subsumes the 1-minute recent window, making this signal most useful for detecting extreme host fan-out rather than gradual drift.

`cost anomaly`

Definition: A risk signal that fires when the estimated cost-per-minute for a workload exceeds a multiple of its recent baseline. Weight: 0.30 of the composite risk score. Default threshold multiplier: 3.0 (MVGC_RISK_COST_THRESHOLD). Requires at least 5 observations in the baseline window before it can fire.

See also: Risk Scoring — cost_anomaly

`connector_id`

Definition: Identifies the connector selected to execute the upstream AI provider call. Set in policy as SelectedConnectorID, or derived by the connector manager from action.target_host.

Built-in values: "openai", "anthropic", "gemini", "azure_openai", "generic_http"

Proxy and MITM

`MITM proxy`

Definition: Man-in-the-middle proxy mode. When MVGC_PROXY_MITM_ENABLED=true, the gateway intercepts HTTPS traffic to managed domains by terminating the client's TLS connection with a dynamically generated leaf certificate signed by the proxy CA, applying the full execution pipeline (policy, attribution, budget, connectors, records), then re-establishing a separate TLS connection to the upstream provider. Traffic to non-managed domains passes through as an opaque TCP tunnel with zero intervention.

Safety gate: Disabled by default (MVGC_PROXY_MITM_ENABLED=false). A structured warning is logged on every gateway restart when active.

See also: Configuring SSL MITM Proxy

`managed domain`

Definition: A hostname or wildcard pattern declared as subject to MITM proxy interception. Configured via MVGC_MANAGED_DOMAINS (env var) or proxy.managed_domains in policy YAML. HTTPS CONNECT requests to managed domains are intercepted; all others pass through as opaque TCP tunnels.

Pattern syntax: Exact hostname (api.openai.com) or single-level wildcard prefix (*.anthropic.com matches api.anthropic.com but not anthropic.com itself). Case-insensitive.

Example: api.openai.com, *.anthropic.com, generativelanguage.googleapis.com

`bypass domain`

Definition: A hostname explicitly excluded from MITM proxy interception, even if it appears in the managed domain list. Configured via proxy.bypass_domains in policy YAML. Bypass domains always receive transparent TCP passthrough. Use for domains that require certificate pinning, workload-identity mTLS, or direct connectivity.

Precedence: bypass_domains overrides both MVGC_MANAGED_DOMAINS and policy managed_domains.

`leaf certificate`

Definition: A short-lived TLS certificate dynamically generated per hostname during MITM proxy interception. The leaf cert has the target hostname as CN and DNS SAN, is signed by the proxy CA, and is served to the client during the TLS handshake. Clients that trust the proxy CA will validate it successfully. Cached in memory with a configurable TTL (default 24h, MVGC_PROXY_LEAF_CERT_TTL).

Key properties: ECDSA P-256 (default) or RSA 2048-bit; validity = TTL from generation time; serverAuth extended key usage; signed by proxy CA private key (never transmitted).

`proxy CA`

Definition: The self-signed root Certificate Authority generated by the gateway for MITM proxy mode. The proxy CA signs all leaf certificates. Clients must install the proxy CA cert into their trust store for TLS validation to succeed. The CA cert is served unauthenticated at GET /v1/proxy/ca.crt.

Key properties: ECDSA P-256 (default) or RSA 2048-bit; 10-year validity; stored under MVGC_KEY_DIR as proxy-ca.key (mode 0600) and proxy-ca.crt (mode 0644); separate from the gateway's Ed25519 node identity key.

See also: Retrieving the CA certificate

Environment Variables

Environment variables configure a running Axemere gateway. All are read at startup unless noted otherwise. Variables in the Distributed Mode group have no effect unless MVGC_CP_ADDR is set.

Core

`DATABASE_URL`

Definition: Postgres connection string for the gateway database. Required; the process will not start without it. Provide a separate value per component (gateway and CP) when running both.

Default: (required)

Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>

Standard Postgres DSN. Port defaults to 5432 when omitted. Use sslmode=require in production.

Example: postgres://mvgc_gateway:<password>@db.internal:5432/mvgc_gateway?sslmode=require

`MVGC_LISTEN_ADDR`

Definition: TCP address the gateway HTTP server binds to.

Default: :7080

Example: 0.0.0.0:7080, :9000

`MVGC_NODE_ID`

Definition: Unique identifier for this gateway instance. Used as the key pair filename under MVGC_KEY_DIR and as the primary key in node_registry. Change this when running multiple gateway instances to avoid key and registry collisions. See node_id.

Default: node-local-dev

Example: gw-prod-us-east-1

`MVGC_POLICIES_DIR`

Definition: Directory containing policy YAML files. All .yaml and .yml files in this directory are loaded at startup and watched for hot-reload. Subdirectories are not traversed. In distributed mode, bundles fetched from the CP via MVGC_BUNDLE_ID supplement or replace file-based policies.

Default: configs/policies

`MVGC_CREDENTIALS_DIR`

Definition: Directory containing the credential seed file (credentials.yaml). The gateway reads this file at startup and inserts any credentials not already present in the database (existing DB records always win). Resolves the hardcoded relative path so the gateway works correctly from any working directory, including the / default used by systemd.

Default: configs/credentials

Package defaults:

deb/rpm: /etc/mvgc/credentials (set in /etc/default/mvgc-gateway)
Homebrew: $(brew --prefix)/var/mvgc/configs/credentials (set by the service plist)
Kubernetes: /configs/credentials (set automatically when credentials: is populated in values.yaml)

`MVGC_WORKLOADS_DIR`

Definition: Directory containing the workload seed file (workloads.yaml). The gateway reads this file at startup and inserts any workloads not already present in the database (existing DB records always win). Resolves the hardcoded relative path so the gateway works correctly from any working directory, including the / default used by systemd.

Default: configs/workloads

Package defaults:

deb/rpm: /etc/mvgc/workloads (set in /etc/default/mvgc-gateway)
Homebrew: $(brew --prefix)/var/mvgc/configs/workloads (set by the service plist)
Kubernetes: /configs/workloads (set automatically when workloads: is populated in values.yaml)

`MVGC_RECORD_LOG_FILE`

Definition: Path to the append-only JSONL file where execution records are written in addition to Postgres. Provides a local audit trail that survives database failures. Each line is a signed execution record envelope. See record_id.

Default: /tmp/mvgc-records.jsonl

Notes: Point this to a persistent volume in production; /tmp is lost on pod restart.

`MVGC_ADMIN_TOKEN`

Definition: Bearer token required for all admin API endpoints (/v1/admin/*). Callers send it as Authorization: Bearer <token>. If empty, admin endpoints are unauthenticated.

Default: (empty)

Notes: Always set this in production. Generate with openssl rand -hex 32. Never log or commit this value.

`MVGC_PROXY_ENABLED`

Definition: When true, the gateway also operates as a transparent HTTP proxy. Standard provider API calls (OpenAI, Anthropic, etc.) intercepted by the proxy are evaluated through the same policy engine as explicit action requests.

Default: true

`MVGC_DEFAULT_DAILY_BUDGET_USD`

Definition: Per-project daily spend cap in USD applied when no project-specific budget rule is defined in policy. Requests that would push a project over this cap are denied.

Default: (empty; unlimited when unset)

Format: Decimal string. Never use a float.

Example: 50.00, 100.00

`MVGC_KEY_DIR`

Definition: Directory where the gateway stores its Ed25519 key pair PEM files. Files are named <MVGC_NODE_ID>.priv.pem (mode 0600) and <MVGC_NODE_ID>.pub.pem. The directory and key pair are created automatically on first startup if they do not exist.

Default: ./keys

Notes: Protect this directory as secret material. The private key signs every execution record. See kid for key ID derivation.

`MVGC_BUNDLE_VERIFY_SIGNATURES`

Definition: When true, the gateway rejects any policy bundle received from the CP that lacks a valid Ed25519 signature. The public key is fetched automatically from the CP via ListKeys: no local key file is required. Gateway startup fails immediately if MVGC_BUNDLE_VERIFY_SIGNATURES=true and no scope=policy key is available.

Default: false

Notes: Requires the CP to be running with MVGC_BUNDLE_SIGN=true and MVGC_CP_POLICY_SIGNING_KEY set. Contact your Axemere representative for the full rollout procedure.

`MVGC_HEALTHZ_STARTUP_GRACE`

Definition: Duration after process start during which the /healthz endpoint returns {"status":"starting"} with HTTP 200 instead of {"status":"ok"}. This gives load balancers and readiness probes a window to detect that the gateway is still initializing (running migrations, loading policies, connecting to the control plane).

Default: 10s

Format: Go duration string (e.g. 10s, 30s, 1m).

Managed Mode

These variables control managed gateway behavior.

`MVGC_CP_TOKEN`

Definition: Bearer token for authenticating to the control plane's admin gRPC services (OrgService, WorkloadService, CredentialService). Required when the CP is running with MVGC_CP_ADMIN_TOKEN set. The gateway sends this token in the authorization metadata on gRPC calls.

Default: (empty)

Format: String.

`MVGC_GATEWAY_MODE`

Definition: Gateway operating mode. Controls how the gateway receives configuration updates and whether API key authentication is enforced on requests.

Value	Behavior
`self-hosted`	Periodic check-in polling; no API key auth required on `/v1/actions:execute` (default)
`managed`	Real-time streaming via `ConfigService.SubscribeUpdates`; API key auth enforced on `/v1/actions:execute`

Default: self-hosted

Format: String: "self-hosted" or "managed".

`MVGC_CHECKIN_IDLE_THRESHOLD`

Definition: Interval between check-in calls to the control plane in self-hosted mode. The gateway polls at this interval to detect stale policy, workload, or credential configurations. Has no effect when MVGC_GATEWAY_MODE=managed.

Default: 60s

Format: Go duration string (e.g. "30s", "2m").

Distributed Mode

These variables have no effect when MVGC_CP_ADDR is unset; embedded mode is used instead.

`MVGC_CP_ADDR`

Definition: gRPC address of the Axemere Control Plane. Setting this variable enables distributed mode: the gateway registers with the CP on startup, fetches signed policy bundles, submits record hashes to the central ledger, and participates in Merkle batching.

Default: (empty; embedded mode preserved)

Example: cp.mvgc.io:9090, localhost:9090

`MVGC_CP_CA_CERT`

Definition: Path to a PEM CA certificate used to verify the CP's TLS certificate. If empty, the system certificate pool is used.

Default: (empty)

Example: /etc/mvgc/cp-ca.pem

`MVGC_NODE_CERT`

Definition: Path to the PEM client certificate presented during mTLS handshake with the CP. Required only if the CP enforces mutual TLS.

Default: (empty; mTLS not used)

Example: /etc/mvgc/node.crt

`MVGC_NODE_CERT_KEY`

Definition: Path to the PEM private key corresponding to MVGC_NODE_CERT.

Default: (empty)

Notes: Protect as secret material; never log or commit.

`MVGC_BOOTSTRAP_TOKEN`

Definition: One-time credential presented to the CP during initial node registration. In SaaS mode, obtain this value from OrgService.CreateBootstrapToken. The token is consumed on first successful registration and cannot be reused. See bootstrap_token.

Default: (empty)

`MVGC_DELEGATION_VERIFY_KEY`

Definition: Path to a PEM Ed25519 public key used to verify delegation_token values on incoming requests. If empty, delegation token verification is disabled.

Default: (empty)

`MVGC_POLICY_CACHE_TTL`

Definition: How long the gateway caches a policy bundle fetched from the CP before re-fetching. When the CP is unreachable, the cached bundle continues to be used beyond this TTL rather than dropping to deny-all. See policy_bundle_id.

Default: 5m

Format: Go duration string (e.g. 5m, 1h, 30s).

`MVGC_HASH_SUBMIT_INTERVAL`

Definition: How often the gateway retries draining the offline hash submission queue. When the CP is unreachable, execution record hashes accumulate in a local queue and are submitted in batches when connectivity resumes.

Default: 10s

Format: Go duration string.

`MVGC_ORG_ID`

Definition: Org ID sent to the CP during node registration and used to scope bundle fetches. At runtime, every request whose org_id field differs from this value is denied with "org_id mismatch" before policy evaluation. See org_id.

Default: (empty; not enforced in embedded mode)

`MVGC_BUNDLE_ID`

Definition: Identifier of the policy bundle to fetch from the CP's PolicyService. See policy_bundle_id.

Default: default

Performance Tuning

`MVGC_DB_MAX_OPEN_CONNS`

Definition: Maximum number of simultaneous open connections the gateway maintains to Postgres. A good starting value is pg_max_connections / replica_count * 0.8.

Default: 25

Format: Integer.

`MVGC_DB_MAX_IDLE_CONNS`

Definition: Maximum number of idle connections retained in the Postgres connection pool. Idle connections above this limit are closed immediately.

Default: 10

Format: Integer.

`MVGC_DB_CONN_MAX_LIFETIME`

Definition: Maximum lifetime of a Postgres connection before it is closed and replaced. Helps prevent stale connections on managed databases that terminate long-lived sessions.

Default: 5m

Format: Go duration string.

`MVGC_CONNECTOR_MAX_CONCURRENT`

Definition: Maximum number of concurrent upstream HTTP calls across all connectors. Acts as a semaphore to prevent provider rate-limit storms when the gateway is under high load.

Default: 50

Format: Integer.

`MVGC_CONNECTOR_TIMEOUT`

Definition: Timeout applied to upstream connector HTTP calls for non-streaming requests only. When the upstream provider does not respond within this duration, the connector returns a timeout error and the gateway returns HTTP 502. Prevents indefinite hangs when a provider stalls on non-streaming calls.

Streaming requests ("stream": true in action.params) are exempt from this timeout. Their response bodies are read incrementally as SSE chunks arrive and can legitimately run for minutes (e.g. compaction of large contexts in Claude Code). The client's HTTP connection lifecycle governs cancellation for streaming responses.

Default: 30s

Format: Go duration string (30s, 1m, 2m30s).

Notes: If you see 502 responses on non-streaming calls under normal load, increase this value. Values above 5m are not recommended for non-streaming; consider setting provider-side timeouts instead. For streaming 502s, see Streaming request hangs or returns empty.

`MVGC_RECORD_QUEUE_SIZE`

Definition: Buffer size for the async execution record write queue. When the queue is full, new records are dropped with a warning log rather than blocking the request path.

Default: 1000

Format: Integer.

`MVGC_RECORD_WORKERS`

Definition: Number of background goroutines draining the async record write queue and writing to Postgres and the JSONL log file.

Default: 4

Format: Integer.

Observability and Risk

`MVGC_APPROVAL_TTL`

Definition: How long an approval_id remains in pending state before the gateway automatically transitions it to expired. Expired approvals cannot be approved or denied via the admin API.

Default: 24h

Format: Go duration string.

`MVGC_APPROVAL_ENABLED`

Definition: Controls the HTTP response for a require_approval decision. When true, returns HTTP 202 with an approval_id. When false, returns HTTP 403 for backward compatibility with clients that do not handle 202.

Default: true

`MVGC_METRICS_ENABLED`

Definition: Enable the Prometheus metrics endpoint at GET /metrics. Exposes request counts, decision distribution, budget counters, and risk score histograms.

Default: true

`MVGC_EXPORT_WEBHOOK_URL`

Definition: URL to POST SIEM events as JSON. Events include request executions, approval state changes, quarantine actions, and risk alerts. Empty disables webhook export.

Default: (empty)

Example: https://siem.corp.example.com/ingest

`MVGC_EXPORT_WEBHOOK_TOKEN`

Definition: Bearer token sent in the Authorization header of outbound webhook SIEM export requests. Optional; required only if the webhook endpoint enforces authentication.

Default: (empty)

Notes: Treat as a secret; never log or commit.

`MVGC_EXPORT_SYSLOG_ADDR`

Definition: Syslog server address for SIEM event export. Empty disables syslog export.

Default: (empty)

Format: tcp://host:port or udp://host:port

Example: udp://siem.corp.example.com:514

`MVGC_RISK_RATE_THRESHOLD`

Definition: Multiplier above the baseline request rate that activates the rate_spike entry in risk signals. A value of 3.0 means a 3x spike over the baseline window triggers the signal. Contributes 40% of the composite risk score.

Default: 3.0

Format: Float string.

`MVGC_RISK_COST_THRESHOLD`

Definition: Multiplier above the baseline spend rate that activates the cost_anomaly entry in risk signals. Contributes 30% of the composite risk score.

Default: 3.0

Format: Float string.

`MVGC_RISK_WINDOW_SIZE`

Definition: Duration of the sliding window used to compute the baseline request rate and cost rate for risk score signals. Shorter windows react faster; longer windows smooth over transient spikes.

Default: 5m

Format: Go duration string.

`MVGC_RISK_BUSINESS_HOURS`

Definition: Business hours specification. Requests arriving outside this window activate the time_of_day entry in risk signals, contributing 15% of the composite risk score. Empty disables the signal entirely.

Default: (empty; signal disabled)

Format: HH:MM-HH:MM,Timezone where Timezone is a Go time.LoadLocation name.

Example: 09:00-17:00,America/New_York

SSL MITM Proxy

`MVGC_PROXY_MITM_ENABLED`

Definition: Master switch for MITM proxy mode. When true, the gateway intercepts HTTPS CONNECT tunnels to managed domains for policy evaluation and attribution. A structured warning is logged on every restart when active.

Default: false

Format: true or false

`MVGC_MANAGED_DOMAINS`

Definition: Comma-separated list of hostnames and wildcard patterns that the MITM proxy should intercept. Exact hostnames and single-level *. wildcards are supported. Case-insensitive. If empty (default), all CONNECT traffic passes through transparently.

Default: (empty; all CONNECT traffic passes through)

Format: Comma-separated string, e.g. api.openai.com,*.anthropic.com,generativelanguage.googleapis.com

`MVGC_PROXY_LEAF_CERT_TTL`

Definition: Time-to-live for cached leaf certificates in MITM proxy mode. After expiry, the leaf cert is regenerated on the next CONNECT request for that hostname. Shorter values reduce the exposure window for any individual leaf cert's private key.

Default: 24h

Format: Go duration string (e.g. 1h, 6h, 24h).

`MVGC_PROXY_CA_KEY_TYPE`

Definition: Key algorithm used for both the proxy CA root key and all leaf certificate keys in MITM proxy mode. ecdsa generates P-256 keys; rsa generates RSA 2048-bit keys.

Default: ecdsa

Format: ecdsa or rsa

`MVGC_PROXY_CA_KEY`

Definition: Path to the proxy CA private key PEM file. If the file does not exist at startup and MVGC_PROXY_MITM_ENABLED=true, the gateway generates a new CA key and cert automatically. Must be stored with mode 0600.

Default: $MVGC_KEY_DIR/proxy-ca.key

Format: Absolute or relative file path.

`MVGC_PROXY_CA_CERT`

Definition: Path to the proxy CA certificate PEM file. This is the public cert distributed to clients for trust store installation. Also served unauthenticated at GET /v1/proxy/ca.crt.

Default: $MVGC_KEY_DIR/proxy-ca.crt

Format: Absolute or relative file path.

Glossary

Table of Contents

Identity and Tenancy

org_id

workload_id

caller_id

caller_ip

node_id

Attribution and Billing

project_id

customer_id

account_id

attribution

labels

Request and Action

request_id

connection_type

traffic_class

action.type

action.target_host

action.target_path

action.params

idempotency_key

HTTP Headers

X-MVGC-Org-ID

X-MVGC-Workload-ID

X-MVGC-Project-ID

X-MVGC-Customer-ID

X-MVGC-Account-ID

X-MVGC-Target-Host

path-prefix routing

provider registry

auto-rule

X-MVGC-Delegation-ID

Credentials and Delegation

api_key

credential_id

credential_hint

connector_hint

secret_ref

credential modes

distribution

credential_type

node credential assignment

export destination

delegation_id

delegation_token

Policy and Decisions

effective_bundle

plan_tier

policy_bundle_id (also bundle_id)

policy_overlay

decision

require_attribution

policy_trace

stop_on

merge_strategy

inline_rules

model_override

policy add-on

approval_id

Infrastructure

check-in

config syncer

credential cache

embedded mode

distributed mode

bootstrap_token

kid (key ID)

managed gateway

record_id

self-hosted gateway

workload cache

Observability

org_monthly_usage

cost_usd

risk score

risk signals

quarantine_id

execution record

`org_id`

`workload_id`

`caller_id`

`caller_ip`

`node_id`

`project_id`

`customer_id`

`account_id`

`attribution`

`labels`

`request_id`

`connection_type`

`traffic_class`

`action.type`

`action.target_host`

`action.target_path`

`action.params`

`idempotency_key`

`X-MVGC-Org-ID`

`X-MVGC-Workload-ID`

`X-MVGC-Project-ID`

`X-MVGC-Customer-ID`

`X-MVGC-Account-ID`

`X-MVGC-Target-Host`

`path-prefix routing`

`provider registry`

`auto-rule`

`X-MVGC-Delegation-ID`

`api_key`

`credential_id`

`credential_hint`

`connector_hint`

`secret_ref`

`distribution`

`credential_type`

`delegation_id`

`delegation_token`

`effective_bundle`

`plan_tier`

`policy_bundle_id` (also `bundle_id`)

`policy_overlay`

`decision`

`require_attribution`

`policy_trace`

`stop_on`

`merge_strategy`

`inline_rules`

`model_override`

`approval_id`

`check-in`

`config syncer`

`credential cache`

`embedded mode`

`distributed mode`

`bootstrap_token`

`kid` (key ID)

`managed gateway`

`record_id`

`self-hosted gateway`

`workload cache`

`org_monthly_usage`

`cost_usd`

`risk score`

`risk signals`

`quarantine_id`

`execution record`

`record_hash`

`inclusion proof`

`anchor`

`overlay layer`

`scope` (delegation token)

`model_tokens_max`

`target diversity`

`cost anomaly`

`connector_id`

`MITM proxy`

`managed domain`

`bypass domain`

`leaf certificate`

`proxy CA`