Configuration Reference

Mezite is configured through a YAML file, typically located at /etc/mezite/mezite.yaml. Every setting can also be overridden via environment variables. This page documents every field, its type, default value, and the corresponding environment variable.

Config Loading Order

Settings are resolved in the following order, with later sources taking precedence:

1. Built-in defaults — Sensible values baked into the binary.
2. Config file — Loaded from the path given by --config.
3. Environment variables — Prefixed with MEZITE_, these override any value set in the config file.

Environment variables always win. This makes it easy to inject secrets (like database passwords and CA passphrases) without writing them to disk.

Minimal Config

The smallest useful configuration — just enough to start a combined-mode server with SQLite (the default):

cluster_name: my-cluster

ssh:
  enabled: true

For PostgreSQL, set the driver and connection fields:

cluster_name: my-cluster

database:
  driver: postgres
  host: localhost
  port: 5432
  user: mezite
  password: mezite
  name: mezite
  sslmode: disable

ssh:
  enabled: true

Full Example

Below is a complete mezite.yaml with every field and its default value. In practice you only need to specify values that differ from the defaults.

# ─── Cluster ─────────────────────────────────────────────
cluster_name: my-cluster

# ─── Logging ─────────────────────────────────────────────
log:
  level: info
  format: json

# ─── Database ────────────────────────────────────────────
database:
  driver: sqlite          # sqlite (default) or postgres
  host: localhost          # PostgreSQL only
  port: 5432               # PostgreSQL only
  user: mezite             # PostgreSQL only
  password: mezite         # PostgreSQL only
  name: mezite             # PostgreSQL only
  sslmode: require         # PostgreSQL only

# ─── Auth Service ────────────────────────────────────────
auth:
  grpc_allow_http: false

# Top-level: CA private key encryption passphrase
ca_key_passphrase: ""

# ─── Proxy Service ───────────────────────────────────────
proxy:
  public_addr: ""              # required for OIDC, WebAuthn, etc.
  listen_addr: 0.0.0.0:3080
  ssh_listen_addr: 0.0.0.0:3023
  tunnel_listen_addr: 0.0.0.0:3024
  apps_domain: ""              # parent domain for application access (empty = off)
  apps_oidc_connector: ""      # SSO connector that gates browser app access
  # apps_keypair:              # optional dedicated wildcard keypair for *.<apps_domain>
  #   cert_file: /etc/mezite/apps-wildcard.crt
  #   key_file: /etc/mezite/apps-wildcard.key

# ─── SSH Service ─────────────────────────────────────────
ssh:
  enabled: false

Cluster

Logging

Logging keys below apply to the mezhub server. The mezd agent emits its own structured logs at production defaults; it does not read MEZITE_LOG_LEVEL or MEZITE_LOG_FORMAT.

Database

Mezite supports SQLite and PostgreSQL backends. SQLite is the simplest option for self-hosted deployments (zero external dependencies). PostgreSQL 16+ is recommended for production and managed deployments.

export MEZITE_DB_DRIVER=sqlite
export MEZITE_DB_URL=/var/lib/mezite/mezhub.db

export MEZITE_DB_DRIVER=postgres
export MEZITE_DB_HOST=db.internal.example.com
export MEZITE_DB_PORT=5432
export MEZITE_DB_USER=mezite
export MEZITE_DB_PASSWORD='$(vault kv get -field=password secret/mezite/db)'
export MEZITE_DB_NAME=mezite
export MEZITE_DB_SSLMODE=verify-full

Auth

Local username/password authentication is always available out of the box; SSO connectors (OIDC, SAML, LDAP, GitHub OAuth) are configured at runtime with mezctl connectors create, not via this YAML file. See the SSO Guide for the connector schema.

First-issue SSH certificate TTL is set per call to IssueUserCerts. It defaults to 12h and is hard-capped at 24h regardless of any role or cluster setting. Per-role max_session_ttl is a separate knob that tightens cross-cluster certificate issuance further; it does not raise the 24h ceiling. The schema field auth.session_ttl is currently reserved — it appears for forward compatibility but is not read by any code path today.

Proxy

SSH

Recording

Controls where session recordings are written and how/when the agent uploads them. See the Session Recording guide for end-to-end behavior.

Audit Log Sinks

Audit events are always written to the cluster database. In addition, events can be mirrored to one or more external sinks for SIEM, alerting, or long-term archive. See the Audit Logging guide.

The export sink is the supported route to long-term audit archive.

KMS-Backed CA Keys

By default, CA signing keys live in the cluster database, AES-256-GCM encrypted with the key derived from MEZITE_CA_KEY_PASSPHRASE. For higher assurance — and for managed deployments — the cluster can be configured so that every CA signing operation calls AWS KMS instead, with the raw private key material never leaving the KMS HSM boundary.

Managed Mode

Set on cloud-managed tenants. When on, the cluster fails to start unless kms.enabled is also true — managed tenants are required to sign with KMS-backed keys so the platform operator can revoke a tenant out-of-band. Leave this off for self-hosted deployments.

Client Tools

The client version this cluster expects, published on the unauthenticated GET /v1/webapi/ping endpoint. msh reads it at login and reports when the binary in the user's hand is behind — see Client version compatibility. It is advisory: the cluster does not refuse older clients, and nothing is ever installed or changed on a user's machine.

client_tools:
  mode: enabled
  target_version: 0.2.24   # or "auto" to track this server's version
  min_version: 0.2.20

A version that is neither auto nor a MAJOR.MINOR.PATCH version is rejected at start-up rather than at the first client request, so a typo surfaces immediately. So is a min_version above an explicit target_version, which would tell clients to install a version the same policy then refuses to support.

Moderation and Access Requests

Workload Identity (mezd identity)

The mezd identity daemon runs on a workload node, exposes a Unix socket that local workloads can call to fetch short-lived X.509/JWT SPIFFE SVIDs, and renews those SVIDs on a timer. These knobs are read by mezd identity only, not by mezhub.

Bootstrap and Operations

Port Reference

Agent Configuration

The mezd binary is configured entirely via environment variables.

MEZITE_JOIN_TOKEN=d4f8a2e1-7b3c-4d9e-a5f6-1234567890ab \
MEZITE_AUTH_ADDR=mezite.example.com:3025 \
MEZITE_PROXY_ADDR=mezite.example.com:3024 \
MEZITE_NODE_NAME=web-server-01 \
MEZITE_NODE_LABELS="env=production,role=webserver" \
mezd start

Environment Variables

MEZITE_CLUSTER_NAME=production \
MEZITE_DB_DRIVER=sqlite \
MEZITE_DB_URL=/var/lib/mezite/mezhub.db \
MEZITE_LOG_LEVEL=info \
MEZITE_CA_KEY_PASSPHRASE='another-secret' \
mezhub

MEZITE_CLUSTER_NAME=production \
MEZITE_DB_HOST=db.internal.example.com \
MEZITE_DB_PORT=5432 \
MEZITE_DB_USER=mezite \
MEZITE_DB_PASSWORD='hunter2' \
MEZITE_DB_NAME=mezite \
MEZITE_DB_SSLMODE=verify-full \
MEZITE_LOG_LEVEL=info \
MEZITE_LOG_FORMAT=json \
MEZITE_CA_KEY_PASSPHRASE='another-secret' \
mezhub

Production Config

SSO connectors are not configured in mezite.yaml — create them at runtime with mezctl connectors create once the hub is up. See the SSO Guide.

cluster_name: production

log:
  level: info
  format: json

database:
  driver: postgres
  host: db.internal.example.com
  port: 5432
  user: mezite
  # password set via MEZITE_DB_PASSWORD
  name: mezite
  sslmode: verify-full

# ca_key_passphrase set via MEZITE_CA_KEY_PASSPHRASE

proxy:
  public_addr: mezite.example.com:443
  listen_addr: 0.0.0.0:3080
  ssh_listen_addr: 0.0.0.0:3023
  tunnel_listen_addr: 0.0.0.0:3024
  oidc_issuer_url: https://mezite.example.com

ssh:
  enabled: false  # dedicated proxy node, not an SSH target

Next Steps

• Quickstart — Apply this configuration in a working setup.
• Architecture — Understand how auth, proxy, and agent components interact.
• SSH Access Guide — Deep dive into SSH certificate authentication and session recording.
• SSO Guide — Configure OIDC or SAML authentication.
• Application Access — Publish internal web and TCP apps using the proxy.apps_* settings above.