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:

Built-in defaults — Sensible values baked into the binary.
Config file — Loaded from the path given by --config.
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):

mezite.yaml — minimal (SQLite) yaml

cluster_name: my-cluster

ssh:
  enabled: true

For PostgreSQL, set the driver and connection fields:

mezite.yaml — minimal (PostgreSQL) yaml

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.

mezite.yaml — complete reference yaml

# ─── 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:
  session_ttl: 12h
  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

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

Cluster

Field	Type	Default	Env Var	Description
`cluster_name`	string	`mezite`	`MEZITE_CLUSTER_NAME`	Unique identifier for this cluster. Embedded in all certificates and used to namespace audit events. Must be a valid DNS label.

Logging

Field	Type	Default	Env Var	Description
`log.level`	string	`info`	`MEZITE_LOG_LEVEL`	Minimum log level. One of `debug`, `info`, `warn`, `error`.
`log.format`	string	`json`	`MEZITE_LOG_FORMAT`	Log serialization format. `json` for structured output, `text` for human-readable.

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.

Field	Type	Default	Env Var	Description
`database.driver`	string	`sqlite`	`MEZITE_DB_DRIVER`	Database backend: `sqlite` or `postgres`.
`database.url`	string	`""`	`MEZITE_DB_URL`	Connection URL. For SQLite: file path. For PostgreSQL: DSN. When empty, built from fields below (PG) or defaults to `<data_dir>/mezhub.db` (SQLite).
`database.host`	string	`localhost`	`MEZITE_DB_HOST`	PostgreSQL hostname or IP address.
`database.port`	integer	`5432`	`MEZITE_DB_PORT`	PostgreSQL port.
`database.user`	string	`mezite`	`MEZITE_DB_USER`	Database user (PostgreSQL only).
`database.password`	string	`""`	`MEZITE_DB_PASSWORD`	Database password (PostgreSQL only).
`database.name`	string	`mezite`	`MEZITE_DB_NAME`	Name of the PostgreSQL database.
`database.sslmode`	string	`require`	`MEZITE_DB_SSLMODE`	PostgreSQL TLS mode. Accepts: `disable`, `require`, `verify-ca`, `verify-full`.

SQLite (simplest — no external database) bash

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

PostgreSQL (production) bash

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.

Certificate lifetimes are controlled per role via the role's max_session_ttl (default 12h), not by a global config key.

Field	Type	Default	Env Var	Description
`auth.grpc_allow_http`	boolean	`false`	`MEZITE_GRPC_ALLOW_HTTP`	Allow plaintext h2c (HTTP/2 cleartext) on the gRPC listener. Use only behind a TLS-terminating load balancer or service mesh.
`ca_key_passphrase` (top-level)	string	`""`	`MEZITE_CA_KEY_PASSPHRASE`	Passphrase used to encrypt Certificate Authority private keys at rest in the database.

Proxy

Field	Type	Default	Env Var	Description
`proxy.public_addr`	string	`""`	`MEZITE_PROXY_PUBLIC_ADDR`	The public address that clients use to reach this proxy (e.g. `mezite.example.com:443`). Required for OIDC discovery and WebAuthn enrollment URLs.
`proxy.listen_addr`	string	`0.0.0.0:3080`	--	Bind address for the HTTPS listener.
`proxy.ssh_listen_addr`	string	`0.0.0.0:3023`	--	Bind address for the SSH listener.
`proxy.tunnel_listen_addr`	string	`0.0.0.0:3024`	--	Bind address for the reverse-tunnel listener.
`proxy.oidc_issuer_url`	string	`""`	`MEZITE_OIDC_ISSUER_URL`	Public issuer URL surfaced at `/.well-known/openid-configuration` and used in workload-identity JWT SVIDs. No trailing slash.
`proxy.trusted_ip_header`	string	`""`	--	HTTP header to read real client IP from (e.g. `Fly-Client-IP`, `X-Forwarded-For`). Config-file only — there is no dedicated env var for this field.

SSH

Field	Type	Default	Env Var	Description
`ssh.enabled`	boolean	`false`	--	Enable the built-in SSH service on this node.

Port Reference

Port	Protocol	Component	Description
`3025`	gRPC	Auth Service	Internal auth API. Should not be exposed publicly.
`3080`	HTTPS	Proxy Service	Web UI, REST API, OIDC callbacks.
`3023`	SSH	Proxy Service	SSH client connections via msh.
`3024`	gRPC	Proxy Service	Agent reverse-tunnel connections.
`5432`	PostgreSQL	Database	State store (only when using PostgreSQL backend).

Agent Configuration

The mezd binary is configured entirely via environment variables.

Variable	Required	Description
`MEZITE_JOIN_TOKEN`	Yes (first run)	One-time join token. Only needed on first join.
`MEZITE_AUTH_ADDR`	Yes	Address of the Auth service (e.g. `mezite.example.com:3025`).
`MEZITE_PROXY_ADDR`	Yes	Address of the Proxy tunnel listener (e.g. `mezite.example.com:3024`).
`MEZITE_NODE_NAME`	No	Node name shown in `msh ls`. Defaults to hostname.
`MEZITE_NODE_LABELS`	No	Comma-separated key=value labels for RBAC matching (e.g. `env=prod,role=web`).
`MEZITE_DATA_DIR`	No	Data directory for identity and recordings. Default: `/var/lib/mezite`.
`MEZITE_RECORDING_MODE`	No	Recording mode: `node` (default — async upload after session) or `node-sync` (real-time streaming to the auth service). See Session Recording.
`MEZITE_TLS_WRAP`	No	Wrap tunnel connection in TLS. Required when connecting through a TLS-terminating load balancer. See Reverse Proxy.
`MEZITE_BPF_ENABLED`	No	Enable eBPF enhanced recording (Linux only, requires privileged mode). Captures command executions in addition to terminal I/O.
`MEZITE_PAM_SERVICE`	No	PAM service name for session hooks (Linux only).
`MEZITE_AUTH_H2C`	No	Run gRPC auth in h2c (HTTP/2 cleartext) mode. Use when a TLS-terminating load balancer sits in front (Fly.io, ALB, Istio/Linkerd service mesh). Also suitable for local development.

Agent startup example bash

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

Variable	Config Equivalent	Description
`MEZITE_CLUSTER_NAME`	`cluster_name`	Cluster name
`MEZITE_DB_DRIVER`	`database.driver`	Database backend (`sqlite` or `postgres`)
`MEZITE_DB_URL`	`database.url`	Connection URL (file path for SQLite, DSN for PostgreSQL)
`MEZITE_DB_HOST`	`database.host`	PostgreSQL host
`MEZITE_DB_PORT`	`database.port`	PostgreSQL port
`MEZITE_DB_USER`	`database.user`	PostgreSQL user
`MEZITE_DB_PASSWORD`	`database.password`	PostgreSQL password
`MEZITE_DB_NAME`	`database.name`	PostgreSQL database name
`MEZITE_DB_SSLMODE`	`database.sslmode`	PostgreSQL TLS mode
`MEZITE_LOG_LEVEL`	`log.level`	Log verbosity
`MEZITE_LOG_FORMAT`	`log.format`	Log format (json or text)
`MEZITE_CA_KEY_PASSPHRASE`	`ca_key_passphrase` (top-level)	CA private key encryption passphrase
`MEZITE_AUTH_H2C`	-	Run gRPC in h2c mode (required behind a TLS-terminating LB). Process-level env var read directly by `mezhub` at startup; not a config-file field.
`MEZITE_GRPC_ALLOW_HTTP`	`auth.grpc_allow_http`	Allow plaintext h2c on the gRPC listener (also enabled by `MEZITE_AUTH_H2C`).
`MEZITE_PROXY_PUBLIC_ADDR`	`proxy.public_addr`	Public proxy address for OIDC discovery and WebAuthn origin
`MEZITE_OIDC_ISSUER_URL`	`proxy.oidc_issuer_url`	Public issuer URL surfaced at `/.well-known/openid-configuration`. No trailing slash.
`MEZITE_AUDIT_HMAC_KEY`	`audit_hmac_key` (top-level)	Hex-encoded HMAC key for the audit-log tamper-detection chain.
`MEZITE_RECORDING_BACKEND`	`recording.backend`	Recording storage backend: `local` (default) or `s3`
`MEZITE_S3_BUCKET`	`recording.s3.bucket`	S3 bucket for recording storage
`MEZITE_S3_REGION`	`recording.s3.region`	S3 region (default: us-east-1)
`MEZITE_S3_ENDPOINT`	`recording.s3.endpoint`	Custom S3 endpoint (for MinIO or other S3-compatible stores)
`MEZITE_RECORDING_ENC_KEY`	`recording_enc_key` (top-level)	32-byte hex-encoded AES-256 key for recording encryption at rest

Example: SQLite with env vars (simplest self-hosted) bash

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

Example: PostgreSQL with env vars bash

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.

mezite.yaml — production yaml

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

auth:
  session_ttl: 8h

# 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.