Gateway Configuration Reference (`mvgc.yaml`)

Complete reference for all mvgc.yaml settings and corresponding environment variables for the Free Gateway and Self-Hosted Gateway.

Config file location
Precedence rules
.env file support
gateway — listener and identity
database — Postgres connection
policies — policy engine
records — execution logging
security — key management
control_plane — Control Plane connection
connectors — upstream HTTP
risk — anomaly detection
approvals — human-in-the-loop
metrics — Prometheus
export — SIEM integration
discovery — domain tracking
telemetry — anonymous usage reporting
transparent_proxy — MITM forward proxy
env — environment variable injection
Env-only settings
Complete example

Config file location

The gateway searches for mvgc.yaml in the following order:

Priority	Source
1	`MVGC_CONFIG=/path/to/mvgc.yaml` environment variable
2	`./mvgc.yaml` in the current working directory
3	`/opt/homebrew/etc/mvgc/mvgc.yaml` (Homebrew, Apple Silicon)
4	`/usr/local/etc/mvgc/mvgc.yaml` (Homebrew, Intel Mac)
5	`/etc/mvgc/mvgc.yaml` (Linux deb/rpm packages)
6	Default — env vars and built-in defaults only

A missing config file is not an error. Every setting has a built-in default and can be configured via environment variable instead.

Precedence rules

For every setting: environment variable > config file value > built-in default.

Setting an environment variable always overrides the config file, even if the config file has a more specific value. This lets secrets and deployment-specific overrides stay out of the file while keeping general configuration in YAML.

`.env` file support

The gateway reads a .env file (or MVGC_ENV_FILE if set) before applying any other configuration. Lines follow KEY=VALUE format; comments start with #. Existing environment variables are never overwritten; .env entries are applied only for variables that are not already set in the shell or service manager environment.

# .env
DATABASE_URL=postgres://mvgc:secret@db:5432/mvgc?sslmode=require
MVGC_ADMIN_TOKEN=your-admin-token

`gateway` — listener and identity

Controls the HTTP listener address, TLS, node identity, CORS, and workload defaults.

YAML key	Env var	Type	Default	Description
`listen_addr`	`MVGC_LISTEN_ADDR`	string	`127.0.0.1:7080`	HTTP listen address. Defaults to loopback; set to `:7080` or a specific interface for network access.
`node_id`	`MVGC_NODE_ID`	string	`node-local-dev`	Unique identifier for this gateway node. Appears in execution records and the Control Plane node registry.
`org_id`	`MVGC_ORG_ID`	string	`""`	Organization ID from the Axemere console. Required for Self-Hosted Gateway (CP-connected mode).
`admin_token`	`MVGC_ADMIN_TOKEN`	string	`""`	Token for admin API authentication (`X-Admin-Token` header). Required in all deployments.
`default_workload_id`	`MVGC_DEFAULT_WORKLOAD_ID`	string	`default`	Workload ID used for requests that do not include a `workload_id`.
`credentials_dir`	`MVGC_CREDENTIALS_DIR`	string	`configs/credentials`	Directory containing credential definition YAML files.
`workloads_dir`	`MVGC_WORKLOADS_DIR`	string	`configs/workloads`	Directory containing workload definition YAML files (embedded mode only).
`proxy_enabled`	`MVGC_PROXY_ENABLED`	bool	`true`	Enable the transparent HTTP/HTTPS forward proxy. Required for MITM interception mode.
`cors_origins`	`MVGC_CORS_ORIGINS`	list	`[]`	Allowed CORS origins. Empty = CORS disabled. Comma-separated via env var (e.g. `https://app.example.com,https://dev.example.com`).
`allowed_connection_types`	`MVGC_ALLOWED_CONNECTION_TYPES`	list	`[]` (all)	Restrict accepted connection types. Values: `direct_api`, `connect_proxy`. Empty = all types allowed. Comma-separated via env var.
`tls_cert`	`MVGC_TLS_CERT`	string	`""`	Path to PEM-encoded TLS certificate for the listener. Must be paired with `tls_key`.
`tls_key`	`MVGC_TLS_KEY`	string	`""`	Path to PEM-encoded TLS private key for the listener. Must be paired with `tls_cert`.
`tls_auto`	`MVGC_TLS_AUTO`	bool	`false`	Issue a TLS certificate for the listener from the MITM CA (requires `proxy_enabled: true` and `tls_hostname`).
`tls_hostname`	`MVGC_TLS_HOSTNAME`	string	`""`	Hostname used in the auto-issued TLS certificate (required when `tls_auto: true`).
`allow_plaintext`	`MVGC_ALLOW_PLAINTEXT`	bool	`false`	Allow plain HTTP when binding to a non-loopback address. Required when TLS is handled by a load balancer or ingress controller.
`pac_proxy_addr`	`MVGC_PAC_PROXY_ADDR`	string	`""`	Listen address for the ambient PAC proxy listener (e.g. `127.0.0.1:7081`).
`pac_proxy_enabled`	(YAML only)	bool	`false`	Enable the ambient PAC proxy listener. Configure only via YAML.
~~`cors_enabled`~~	—	bool	—	Deprecated. Use `cors_origins` instead.

`database` — Postgres connection

YAML key	Env var	Type	Default	Description
`url`	`DATABASE_URL`	string	`""`	Required. Postgres connection string. Format: `postgres://user:password@host:port/dbname?sslmode=require`
`max_open_conns`	`MVGC_DB_MAX_OPEN_CONNS`	int	`25`	Maximum simultaneous open connections to Postgres.
`max_idle_conns`	`MVGC_DB_MAX_IDLE_CONNS`	int	`10`	Maximum idle connections retained in the pool.
`conn_max_lifetime`	`MVGC_DB_CONN_MAX_LIFETIME`	duration	`5m`	Maximum connection lifetime before recycling. Go duration string (e.g. `5m`, `1h`).

Schema migrations run automatically on startup: no manual step is required.

`policies` — policy engine

YAML key	Env var	Type	Default	Description
`dir`	`MVGC_POLICIES_DIR`	string	`configs/policies`	Directory containing policy YAML bundle files.
`cache_ttl`	`MVGC_POLICY_CACHE_TTL`	duration	`5m`	How long policy bundles are cached in memory. Stale bundles are served during Control Plane outages.
`bundle_id`	`MVGC_BUNDLE_ID`	string	`default`	Policy bundle identifier to load from the Control Plane. Self-Hosted Gateway only. Only set this when using a non-default bundle.

`records` — execution logging

YAML key	Env var	Type	Default	Description
`log_file`	`MVGC_RECORD_LOG_FILE`	string	`/tmp/mvgc-records.jsonl`	Path for the append-only JSONL execution record log. The gateway rotates the file on `SIGUSR1` (for use with `logrotate`).
`queue_size`	`MVGC_RECORD_QUEUE_SIZE`	int	`1000`	Buffer size for the async record write queue. When full, the gateway returns HTTP 503.
`workers`	`MVGC_RECORD_WORKERS`	int	`4`	Background worker threads draining the record write queue.

`security` — key management

YAML key	Env var	Type	Default	Description
`key_dir`	`MVGC_KEY_DIR`	string	`./keys`	Directory for the node Ed25519 key pair (auto-generated on first start). Protect this directory as you would any secret.
`delegation_verify_key`	`MVGC_DELEGATION_VERIFY_KEY`	string	`""`	Path to the PEM public key for delegation token verification. Required when using delegation tokens.

`control_plane` — Control Plane connection

Self-Hosted Gateway only. Leave this section empty for Free Gateway (embedded mode).

Setting addr is what activates CP-connected mode. Without it, all other fields in this section are ignored.

YAML key	Env var	Type	Default	Description
`addr`	`MVGC_CP_ADDR`	string	`""`	Control Plane gRPC address. Setting this enables CP-connected mode (e.g. `us.cp.axemere.ai:9090`).
`bootstrap_token`	`MVGC_BOOTSTRAP_TOKEN`	string	`""`	One-time registration token from the Axemere console. Used on first connection to provision the node.
`ca_cert`	`MVGC_CP_CA_CERT`	string	`""`	Path to the CA certificate PEM for verifying the CP's TLS certificate. Not required for `us.cp.axemere.ai` (uses a publicly-trusted cert).
`node_cert`	`MVGC_NODE_CERT`	string	`""`	Path to the client certificate PEM for mutual TLS (mTLS) node authentication.
`node_cert_key`	`MVGC_NODE_CERT_KEY`	string	`""`	Path to the client certificate private key (paired with `node_cert`).
`hash_submit_interval`	`MVGC_HASH_SUBMIT_INTERVAL`	duration	`10s`	Interval for retrying pending Merkle hash submissions to the CP.
`key_refresh_interval`	`MVGC_KEY_REFRESH_INTERVAL`	duration	`5m`	How often to refresh signing keys from the CP keyring.
`bundle_id`	(same as `policies.bundle_id`)	string	`default`	Alias: prefer setting `policies.bundle_id`.
`no_tls`	`MVGC_CP_NO_TLS`	bool	`false`	Disable TLS on the CP gRPC connection. Development only.
`skip_tls_verify`	`MVGC_CP_SKIP_TLS_VERIFY`	bool	`false`	Skip TLS certificate verification for the CP connection. Development only.

To connect to the Axemere Control Plane:

Sign in to console.axemere.ai → Gateways → + Enroll Gateway.
Click Generate Token and copy it (this is the value for bootstrap_token) along with your Organization ID.
Set in mvgc.yaml:

gateway:
  org_id: "org_abc123"

control_plane:
  addr: "us.cp.axemere.ai:9090"
  bootstrap_token: "btkn_..."

`connectors` — upstream HTTP

Controls how the gateway makes outbound calls to AI providers.

YAML key	Env var	Type	Default	Description
`timeout`	`MVGC_CONNECTOR_TIMEOUT`	duration	`30s`	Timeout for non-streaming upstream calls. Streaming requests run until the client disconnects.
`max_concurrent`	`MVGC_CONNECTOR_MAX_CONCURRENT`	int	`50`	Maximum concurrent outbound connections across all connectors.
`http_idle_conn_timeout`	`MVGC_HTTP_IDLE_CONN_TIMEOUT`	duration	`90s`	HTTP keep-alive idle connection timeout.
`credential_cache_ttl`	`MVGC_CREDENTIAL_CACHE_TTL`	duration	`5m`	How long credentials are cached in memory (CP-connected mode).
`allow_generic_http`	`MVGC_ALLOW_GENERIC_HTTP`	bool	`true`	Allow the generic HTTP connector as a fallback for uncatalogued providers. Set to `false` to restrict outbound calls to known AI provider connectors only.

SSRF protection: The HTTP connector blocks connections to RFC-1918 private ranges, loopback, and link-local addresses by default. To allow specific private hosts (e.g. on-premise model servers), set:

MVGC_HTTP_CONNECTOR_TRUSTED_HOSTS=my-model.internal,gpu-server.corp.example.com

This env var has no YAML equivalent.

`risk` — anomaly detection

The risk scorer compares current request rate and cost against a rolling baseline. Exceeding a threshold sets a risk signal that policies can evaluate.

YAML key	Env var	Type	Default	Description
`rate_threshold`	`MVGC_RISK_RATE_THRESHOLD`	float	`3.0`	Request rate spike multiplier. A value of `3.0` means "3× the baseline rate triggers the risk signal."
`cost_threshold`	`MVGC_RISK_COST_THRESHOLD`	float	`3.0`	Cost anomaly multiplier. Same interpretation as `rate_threshold`.
`window_size`	`MVGC_RISK_WINDOW_SIZE`	duration	`5m`	Rolling window for baseline calculation.
`business_hours`	`MVGC_RISK_BUSINESS_HOURS`	string	`""`	Business hours spec in `HH:MM-HH:MM,TZ` format (e.g. `09:00-17:00,America/New_York`). Requests outside business hours trigger the `time_of_day` risk signal.

`approvals` — human-in-the-loop

YAML key	Env var	Type	Default	Description
`enabled`	`MVGC_APPROVAL_ENABLED`	bool	`true`	When `true`, policies with `require_approval` return HTTP 202 (pending) and pause execution. When `false`, `require_approval` returns HTTP 403 (rejected immediately).
`ttl`	`MVGC_APPROVAL_TTL`	duration	`24h`	How long an approval request remains pending before auto-expiring.

`metrics` — Prometheus

YAML key	Env var	Type	Default	Description
`enabled`	`MVGC_METRICS_ENABLED`	bool	`true`	Enable Prometheus metrics at `GET /metrics`. Exposes `mvgc_*` business metrics alongside Go runtime metrics.

`export` — SIEM integration

Push execution events to external destinations in addition to the record log file.

YAML key	Env var	Type	Default	Description
`webhook_url`	`MVGC_EXPORT_WEBHOOK_URL`	string	`""`	HTTPS endpoint to receive execution events as JSON (Splunk HEC, Datadog Logs, custom ingest). Must be `http://` or `https://` without embedded credentials.
`webhook_token`	`MVGC_EXPORT_WEBHOOK_TOKEN`	string	`""`	Bearer token sent in the `Authorization` header for webhook requests.
`syslog_addr`	`MVGC_EXPORT_SYSLOG_ADDR`	string	`""`	Syslog server address. Format: `tcp://host:port` or `udp://host:port`.

All three destinations are independent and can be combined. The webhook URL is validated at startup; invalid URLs disable that destination with a warning.

`discovery` — domain tracking

When enabled, the gateway counts every unique domain passing through the forward proxy and exposes the list via the admin API. Useful for auditing what AI providers developers are reaching before formal configuration.

YAML key	Env var	Type	Default	Description
`enabled`	`MVGC_DISCOVERY_ENABLED`	bool	`false`	Enable domain discovery mode. Counts are kept in memory and reset on restart.

`telemetry` — anonymous usage reporting

The gateway sends anonymous aggregate usage statistics to Axemere (active connector count, approximate request volume, version). No execution content or identifiable data is included.

YAML key	Env var	Type	Default	Description
`enabled`	`MVGC_TELEMETRY_ENABLED`	bool	`true`	Enable anonymous usage telemetry. Set to `false` to opt out completely.
`interval`	`MVGC_TELEMETRY_INTERVAL`	duration	`1h`	How often to send telemetry reports.

`transparent_proxy` — MITM forward proxy

Configures the HTTPS MITM interception mode. Requires gateway.proxy_enabled: true (the default).

When managed_domains is non-empty, the gateway intercepts HTTPS CONNECT tunnels to listed domains, applies the full execution pipeline (policy, budget, attribution, records), then re-establishes the upstream TLS connection. All other domains are forwarded as opaque TCP tunnels.

Clients must trust the Axemere proxy CA certificate. Retrieve it from GET /v1/proxy/ca.crt on the gateway.

YAML key	Env var	Type	Default	Description
`managed_domains`	`MVGC_MANAGED_DOMAINS`	list	`[]`	Hostnames and wildcard patterns to intercept (e.g. `api.openai.com`, `*.anthropic.com`). Comma-separated via env var.
`passthrough_observed_domains`	`MVGC_PASSTHROUGH_OBSERVED_DOMAINS`	list	`[]`	Domains that use passthrough-observed mode instead of MITM. Use for cert-pinned hosts you cannot add to the trust store. Comma-separated via env var.
`passthrough_idle_timeout`	`MVGC_PASSTHROUGH_IDLE_TIMEOUT`	duration	`120s`	Fires an interim execution record when no bytes travel in either direction for this duration (passthrough-observed mode).
`passthrough_max_interval`	`MVGC_PASSTHROUGH_MAX_INTERVAL`	duration	`10m`	Fires an interim execution record unconditionally at this interval (passthrough-observed mode).
`default_workload_id`	(YAML only)	string	`""`	Workload ID for CONNECT tunnel attribution when no `provider_defaults` entry matches. Overrides `gateway.default_workload_id` for transparent-proxy traffic.
`provider_defaults`	(YAML only)	map	`{}`	Per-provider workload and project attribution for CONNECT tunnels. See example below.

`provider_defaults` example

transparent_proxy:
  managed_domains:
    - api.openai.com
    - api.anthropic.com

  provider_defaults:
    api.openai.com:
      workload_id: "wl_openai-prod"
      project_id:  "prj_backend-team"
    api.anthropic.com:
      workload_id: "wl_anthropic-prod"
      project_id:  "prj_data-science"

CA certificate management

The MITM CA key and certificate are stored in MVGC_DATA_DIR (default: ~/.config/mvgc-gateway/) as ca.key and ca.crt. They are auto-generated on first start. To use an existing CA:

Env var	Description
`MVGC_DATA_DIR`	Data directory for auto-generated CA files (default: `~/.config/mvgc-gateway/`).
`MVGC_PROXY_CA_KEY`	Path to an existing CA private key PEM. Disables auto-generation.
`MVGC_PROXY_CA_CERT`	Path to an existing CA certificate PEM. Disables auto-generation.
`MVGC_PROXY_CA_KEY_TYPE`	Key algorithm: `ecdsa` (P-256, default) or `rsa` (2048-bit).
`MVGC_PROXY_LEAF_CERT_TTL`	TTL for dynamically issued leaf certificates (default: `24h`).

`env` — environment variable injection

The env map injects key-value pairs into the process environment at startup. Entries are applied only when the variable is not already set; existing environment variables always win.

env:
  DATABASE_URL: "postgres://mvgc:secret@db:5432/mvgc?sslmode=require"
  OPENAI_API_KEY: "sk-..."

This is equivalent to setting those variables in the system environment. Use it to consolidate all gateway configuration in a single YAML file without needing a separate .env file or service manager EnvironmentFile.

Env-only settings

These settings have no YAML equivalent and can only be configured via environment variable.

Env var	Default	Description
`MVGC_CONFIG`	—	Path to the `mvgc.yaml` config file. Overrides all automatic search paths.
`MVGC_ENV_FILE`	`.env`	Path to a `.env` file to load before all other configuration.
`MVGC_CP_TOKEN`	`""`	Bearer token for Control Plane admin gRPC authentication. Set only when the CP runs with `MVGC_CP_ADMIN_TOKEN`. Self-Hosted Gateway only.
`MVGC_KEYS_SECRET_NAME`	`mvgc-gateway-keys`	Cloud secret name for the gateway key pair (used in cloud deployments).
`MVGC_HTTP_CONNECTOR_TRUSTED_HOSTS`	`""`	Comma-separated hostnames that bypass SSRF private-IP checks. Use for on-premise model servers.
`MVGC_CUSTOM_CONNECTORS_FILE`	`""`	Path to a custom connectors YAML file. Reloaded automatically on `SIGHUP`.
`MVGC_REDIS_ADDR`	`""`	Redis connection URL for distributed budget enforcement across multiple gateway instances (e.g. `redis://host:6379`). When empty, budget enforcement is gateway-local only.
`MVGC_ALERT_POLL_INTERVAL`	`60m`	How often the gateway polls for budget threshold alerts. Set to `0` to disable.
`RESEND_API_KEY`	`""`	Resend transactional email API key for email alert channels. When empty, email alerts are skipped with a warning.
`MVGC_PUBLIC_URL`	`""`	Externally reachable gateway URL (e.g. `https://gw.example.com`). Used to build unsubscribe links in email alerts.

Complete example

# mvgc.yaml — complete Self-Hosted Gateway example
# Load order: env var > this file > built-in defaults
# Secrets can remain as environment variables; they override file values.

gateway:
  listen_addr: ":7080"                  # bind all interfaces
  node_id:     "node-prod-01"
  # org_id: set via MVGC_ORG_ID env var
  # admin_token: set via MVGC_ADMIN_TOKEN env var
  proxy_enabled: true
  cors_origins:
    - "https://app.example.com"
  default_workload_id: "wl_default"
  credentials_dir: "/etc/mvgc/credentials"

database:
  # url: set via DATABASE_URL env var
  max_open_conns: 25
  max_idle_conns:  10

policies:
  dir:     "/etc/mvgc/policies"
  cache_ttl: "5m"

records:
  log_file:   "/var/log/mvgc/records.jsonl"
  queue_size: 2000
  workers:    8

security:
  key_dir: "/var/lib/mvgc/keys"

control_plane:
  addr: "us.cp.axemere.ai:9090"
  # bootstrap_token: set via MVGC_BOOTSTRAP_TOKEN env var (one-time, remove after first start)
  hash_submit_interval: "10s"
  key_refresh_interval: "5m"

connectors:
  timeout:         "30s"
  max_concurrent:  50
  allow_generic_http: false   # restrict to catalogued AI providers only

risk:
  rate_threshold: 3.0
  cost_threshold: 3.0
  window_size:    "5m"
  business_hours: "09:00-18:00,America/New_York"

approvals:
  enabled: true
  ttl:     "24h"

metrics:
  enabled: true

export:
  webhook_url:   "https://siem.example.com/ingest"
  # webhook_token: set via MVGC_EXPORT_WEBHOOK_TOKEN env var

discovery:
  enabled: false

telemetry:
  enabled:  true
  interval: "1h"

transparent_proxy:
  managed_domains:
    - api.openai.com
    - api.anthropic.com
    - generativelanguage.googleapis.com
  provider_defaults:
    api.openai.com:
      workload_id: "wl_openai"
    api.anthropic.com:
      workload_id: "wl_anthropic"

env:
  # Inject additional environment variables that this file makes available
  # to the gateway process. Existing env vars (set by the shell or service
  # manager) always win; these are applied only when the variable is unset.
  OPENAI_API_KEY: "sk-..."

Minimal Free Gateway example (no Control Plane):

gateway:
  listen_addr: "127.0.0.1:7080"
  node_id:     "node-dev"
  # admin_token: set via MVGC_ADMIN_TOKEN env var

database:
  # url: set via DATABASE_URL env var

transparent_proxy:
  managed_domains:
    - api.openai.com
    - api.anthropic.com

IT Setup Guide — installation and deployment
CLI Reference — mvgc user CLI (~/.config/mvgc/config.yaml)
Admin API Reference — admin REST API
Glossary

Gateway Configuration Reference (mvgc.yaml)

Table of Contents

Config file location

Precedence rules

.env file support

gateway — listener and identity

database — Postgres connection

policies — policy engine

records — execution logging

security — key management

control_plane — Control Plane connection

connectors — upstream HTTP

risk — anomaly detection

approvals — human-in-the-loop

metrics — Prometheus

export — SIEM integration

discovery — domain tracking

telemetry — anonymous usage reporting

transparent_proxy — MITM forward proxy

provider_defaults example