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

auth:
  local_auth_enabled: true

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

auth:
  local_auth_enabled: true

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:
  local_auth_enabled: true
  session_ttl: 12h
  ca_key_passphrase: ""

# ─── Proxy Service ───────────────────────────────────────
proxy:
  public_addr: localhost:3080
  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

Field	Type	Default	Env Var	Description
`auth.local_auth_enabled`	boolean	`true`	--	Enable username/password authentication. Set to `false` in production if you require all users to authenticate via SSO.
`auth.session_ttl`	duration	`12h`	--	Maximum lifetime for user certificates issued at login.
`auth.ca_key_passphrase`	string	`""`	`MEZITE_CA_KEY_PASSPHRASE`	Passphrase used to encrypt Certificate Authority private keys at rest in the database.
`auth.oidc.issuer_url`	string	`""`	--	OIDC provider issuer URL. When set, enables OIDC-based SSO login.
`auth.oidc.client_id`	string	`""`	--	OAuth 2.0 client ID registered with the OIDC provider.
`auth.oidc.client_secret`	string	`""`	--	OAuth 2.0 client secret.
`auth.oidc.redirect_url`	string	`""`	--	Callback URL the OIDC provider redirects to after authentication.

Proxy

Field	Type	Default	Env Var	Description
`proxy.public_addr`	string	`localhost:3080`	--	The address that clients use to reach this proxy.
`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.

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-sync` (real-time streaming) or `node` (async upload after session). The cluster default is `node-sync`. 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`	`auth.ca_key_passphrase`	CA private key encryption passphrase
`MEZITE_AUTH_H2C`	-	Run gRPC in h2c mode (required behind a TLS-terminating LB)
`MEZITE_GRPC_ALLOW_HTTP`	`auth.grpc_allow_http`	Enable h2c mode for gRPC without full insecure mode
`MEZITE_TRUSTED_IP_HEADER`	`proxy.trusted_ip_header`	HTTP header to read real client IP from (e.g. X-Forwarded-For)
`MEZITE_RECORDING_BACKEND`	`recording.backend`	Recording storage backend: `local` (default) or `s3`
`MEZITE_S3_BUCKET`	-	S3 bucket for recording storage
`MEZITE_S3_REGION`	-	S3 region (default: us-east-1)
`MEZITE_S3_ENDPOINT`	-	Custom S3 endpoint (for MinIO or other S3-compatible stores)
`MEZITE_RECORDING_ENC_KEY`	-	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

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:
  local_auth_enabled: false  # SSO only
  session_ttl: 8h
  # ca_key_passphrase set via MEZITE_CA_KEY_PASSPHRASE
  oidc:
    issuer_url: https://accounts.google.com
    client_id: your-client-id
    # client_secret set via environment
    redirect_url: https://mezite.example.com:443/v1/oidc/callback

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

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.