Environment Configuration Reference

AlmaForge supports environment variables for daemon startup, CLI defaults, and session context. Use this page as the reference for supported ALMA_* variables.

This page is grouped by binary and use case:

• almad daemon startup and bootstrap
• alma client defaults (including admin subcommands)
• SSH session variables injected by almad

almad Server Variables

Use these variables to start almad from the environment.

Bootstrap

Variable	Type	Default	Description
ALMA_PROXY	string	none	Proxy address to connect to when joining through a proxy.
ALMA_AUTH_SERVER	string or string list	none	Auth server address for direct connection.
ALMA_CLIENT_ID	string	none	Resource name (metadata.name) of the provisioning Token on the cluster. Required for every join method. May be a literal value or a path to a file containing it.
ALMA_CLIENT_SECRET	string	none	Plaintext shared secret presented to the static join method. Hashed on the server with SHA-256 and compared against spec.static.secret. Empty for non-static join methods. May be a literal value or a path to a file containing it.
ALMA_JOIN_METHOD	enum	static with a secret	Join method. Supported values: static, aws, ec2, kubernetes, azure, gcp, github, gitlab, circleci, spacelift. static is derived only when ALMA_CLIENT_SECRET is set. Every other method has to name itself here.
ALMA_CA_PIN	string list	none	CA pins or paths to files containing one pin per line, used for a direct Auth join. Proxy joins use the Proxy's TLS certificate and ignore these pins.
ALMA_NODE_NAME	string	hostname	Node name to register.
ALMA_LABELS	comma-separated key=value list	none	Static node labels. Example: env=prod,team=infra.

Roles

Each service flag accepts true, false, or an unset value. Leave a flag unset when almad should decide from the runtime environment and the resources under /etc/almaforge/almad.d. Set it only when you want to force that service on or off.

Variable	Type	Default	Description
ALMA_AUTH_SERVICE	boolean	unset	Enable or disable the auth service.
ALMA_PROXY_SERVICE	boolean	unset	Enable or disable the proxy service.
ALMA_SSH_SERVICE	boolean	unset	Enable or disable the SSH node service.
ALMA_DATABASE_SERVICE	boolean	unset	Enable or disable the database service.
ALMA_APP_SERVICE	boolean	unset	Enable or disable the application service.
ALMA_KUBERNETES_SERVICE	boolean	unset	Enable or disable the Kubernetes service.
ALMA_JIRA_SERVICE	boolean	unset	Enable or disable the built-in Jira access-request plugin.
ALMA_SLACK_SERVICE	boolean	unset	Enable or disable the built-in Slack access-request plugin.
ALMA_PAGERDUTY_SERVICE	boolean	unset	Enable or disable the built-in PagerDuty plugin.
ALMA_TELEGRAM_SERVICE	boolean	unset	Enable or disable the built-in Telegram plugin.

Configuration

Variable	Type	Default	Description
ALMA_CONFIG_DIR	path	/etc/almaforge/almad.d	Path to the config directory or file. Equivalent to the --config-dir flag. Loaded on every start to apply typed resources (StorageConfig, roles, tokens, etc.).

Deployment

Variable	Type	Default	Description
ALMA_DEBUG	boolean	false	Enable verbose daemon logging.
ALMA_DATA_DIR	path	/var/lib/almaforge	Local state directory.
ALMA_LOG_LEVEL	enum	info	Log level. Supported values are debug, info, warn, and error.
ALMA_LOG_OUTPUT	string	stderr	Log destination. Use stderr, stdout, syslog, or a file path.
ALMA_LOG_FORMAT	enum	text	Log line format. Use text for human-readable output or json for one JSON object per line.

Storage

Each variable holds a single URI that the auth server parses into a typed StorageConfig instance. The URI grammar, including schemes, query keys, and fragment options, is documented in Storage backends → URI format.

Variable	Type	Default	Description
ALMA_STATE_URI	URI	sqlite:// under $ALMA_DATA_DIR/backend	Cluster state backend. Example: sqlite:///var/lib/almaforge/backend, postgres://user@host/db, dynamodb://table?region=us-east-1.
ALMA_AUDIT_URI	URI	file:// under $ALMA_DATA_DIR/log	Audit events sink. Example: dynamodb://events?region=us-east-1, postgres://user@host/audit, file:///var/log/almaforge/audit.
ALMA_RECORDINGS_URI	URI	file:// under $ALMA_DATA_DIR/records	Session recordings storage. Example: s3://bucket/prefix?region=us-east-1, gs://bucket/prefix, file:///var/lib/almaforge/records.

Each env var replaces the typed StorageConfig document under --config-dir for that instance role. When a URI is not set, the corresponding file-defined instance is used. When neither is configured, ALMA_DATA_DIR determines the default path. For fan-out audit (multiple sinks) use typed StorageConfig documents under --config-dir. The env-var form is a single sink per role.

Listen and Advertise Addresses

ALMA_LISTEN is the shared TLS listener: one TLS port that serves every proxy protocol via SNI/ALPN (web UI/API, kube SNI, reverse tunnel, DB protocols, auth gRPC, proxy SSH gRPC, TCP apps). It is the only listener bound by default. Dedicated listeners can add an entry point or move a protocol to another port. See how dedicated ports change access.

ALMA_ADVERTISE is the canonical endpoint advertised to clients and agents. It is the URL that appears in SSO redirects, ACME challenges, web UI base, kube config server URL, agent reverse-tunnel reconnect, and SSH host certificate SANs. Per-protocol *_ADVERTISE overrides are only required when a specific protocol lives on a different hostname (split-LB or compliance-segmented setups). When a per-protocol advertise is unset, the protocol rides the shared TLS listener and the client uses ALMA_ADVERTISE as the connection target.

Each per-protocol listener is paired with its advertise counterpart immediately below it. Every per-protocol ALMA_*_LISTEN and ALMA_*_ADVERTISE for the proxy ingress has a matching --<name>-listen / --<name>-advertise CLI flag. The operator-only listeners ALMA_DIAG_LISTEN and ALMA_METRICS_LISTEN are listen-only and have no advertise counterpart since they are not advertised to clients.

Variable	Type	Default	Description
ALMA_LISTEN	host:port	0.0.0.0:443	Shared TLS listener. Bound when the Proxy Service or Auth Service is enabled.
ALMA_ADVERTISE	string or host:port	unset	Canonical endpoint advertised for every protocol. Required when ACME, SSO, or any client-facing handshake needs to know the proxy's hostname.
ALMA_KUBE_LISTEN	host:port	unset	Optional dedicated kube SNI port. The kube SNI route on the shared TLS listener is on by default. Set this only to add a separate listener.
ALMA_KUBE_ADVERTISE	host:port	falls back to ALMA_ADVERTISE	Override for alma kube login config server URL.
ALMA_TUNNEL_LISTEN	host:port	unset	Optional dedicated reverse tunnel port.
ALMA_TUNNEL_ADVERTISE	host:port	falls back to ALMA_ADVERTISE	Override for agent reverse-tunnel reconnect URL.
ALMA_MYSQL_LISTEN	host:port	unset	Optional native MySQL wire-protocol port.
ALMA_MYSQL_ADVERTISE	host:port	falls back to ALMA_ADVERTISE	Override for MySQL client connection URL.
ALMA_POSTGRES_LISTEN	host:port	unset	Optional native Postgres wire-protocol port.
ALMA_POSTGRES_ADVERTISE	host:port	falls back to ALMA_ADVERTISE	Override for Postgres client connection URL.
ALMA_MONGO_LISTEN	host:port	unset	Optional native Mongo wire-protocol port.
ALMA_MONGO_ADVERTISE	host:port	falls back to ALMA_ADVERTISE	Override for Mongo client connection URL.
ALMA_SSH_LISTEN	host:port	unset	Optional dedicated proxy SSH port (alma ssh raw-SSH path). Configures the Proxy Service ingress, not the SSH Node service.
ALMA_SSH_ADVERTISE	host:port	falls back to ALMA_ADVERTISE	Override for the proxy's SSH ingress public address.
ALMA_PEER_LISTEN	host:port	unset	Proxy-to-proxy peering listener for HA proxy clusters.
ALMA_PEER_ADVERTISE	host:port	falls back to ALMA_ADVERTISE	Address this proxy advertises to peer proxies.
ALMA_DIAG_LISTEN	host:port	unset	Diagnostics endpoint: /healthz and /readyz, plus /debug/pprof/* under ALMA_DEBUG, and /metrics while ALMA_METRICS_LISTEN is unset. Operator-only. No advertise.
ALMA_METRICS_LISTEN	host:port	unset	Prometheus metrics endpoint (/metrics). Operator-only. No advertise.
ALMA_METRICS_TLS_CERT	path	none	TLS certificate the metrics listener presents.
ALMA_METRICS_TLS_KEY	path	none	TLS private key for ALMA_METRICS_TLS_CERT.
ALMA_METRICS_CLIENT_CA	path	none	CA that a scraper must present a certificate from.

The metrics endpoint serves mutual TLS or plaintext, with nothing in between, so set all three of these or none of them. Setting a subset fails startup rather than leaving the endpoint plaintext while a certificate is configured.

Load Balancer Integration

For deployments behind a L7 load balancer (ALB, GCP LB, NGINX, HAProxy) that terminates client connections and forwards them to AlmaForge:

Variable	Type	Default	Description
ALMA_REAL_IP_FROM	list	empty	Networks a client-supplied source address is believed from, as comma-separated CIDRs or bare IPv4 / IPv6 addresses. A bare address is taken as a single host and host bits are masked off. Empty means no client-supplied address is believed. Equivalent to nginx set_real_ip_from.
ALMA_REAL_IP_HEADER	enum	proxy_protocol	The one channel a trusted proxy may use to give the client address. Values: proxy_protocol, X-Forwarded-For, X-Real-IP, off. Only the named channel is read, so a client cannot reach the address through one the operator did not choose. The header values apply to the web listener only. X-Forwarded-For takes the last entry in the chain. Equivalent to nginx real_ip_header.
ALMA_PROXY_PROTOCOL	enum	unset	Whether a PROXY protocol header is required on the multiplex listener. Values: on, off. Unset allows a header without requiring one, on rejects a connection that does not carry exactly one, off rejects any connection that carries one. This controls whether a header is required, not whether its address is believed. See ALMA_REAL_IP_FROM and ALMA_REAL_IP_HEADER.

TLS and Certificates

Variable	Type	Default	Description
ALMA_TLS_CERT	path	none	Path to the TLS certificate file for the proxy.
ALMA_TLS_KEY	path	none	Path to the TLS private key for ALMA_TLS_CERT. Set both or neither. Half a pair fails at startup. Without a supplied pair or ACME, the Proxy uses a self-signed certificate.
ALMA_ACME_ENABLED	boolean	false	Enable ACME certificate provisioning. Requires ALMA_ADVERTISE to be set. Let's Encrypt issues the certificate against the hostname in ALMA_ADVERTISE.
ALMA_ACME_EMAIL	string	none	Email address used for ACME registration.
ALMA_ACME_URI	URL	Let's Encrypt production	ACME directory to use. Point it at a staging directory while testing so experiments do not consume the production rate limit, or at a private CA.
ALMA_TLS_RELOAD_INTERVAL	duration	unset	How often the proxy re-reads ALMA_TLS_CERT. Set it to pick up a renewal issued out of band without restarting. Unset loads the certificate once at startup.
ALMA_LICENSE_FILE	path	none	Path to the AlmaForge license file.
ALMA_KUBECONFIG	path	none	Path to a kubeconfig used for remote Kubernetes clusters.

Certificate Authority Keys

Where the Auth Service keeps the private keys of the cluster's certificate authorities. The default keeps them in software, on the Auth Service's own storage.

Name the driver explicitly. A driver whose settings are incomplete stops startup rather than falling back to software keys, so a cluster cannot quietly end up with software-backed CAs when an HSM was intended.

Variable	Type	Default	Description
ALMA_CA_KEYSTORE	enum	software	Keystore driver: software, pkcs11 or gcp_kms.
ALMA_PKCS11_MODULE	path	none	Path to the PKCS#11 module. Required for pkcs11.
ALMA_PKCS11_SLOT	integer	none	Slot number holding the token. Give this or ALMA_PKCS11_TOKEN_LABEL.
ALMA_PKCS11_TOKEN_LABEL	string	none	Label of the token to use. Give this or ALMA_PKCS11_SLOT.
ALMA_PKCS11_PIN	string or path	none	PIN for the token. An absolute path is read as a file holding the PIN, which keeps it out of the process environment.
ALMA_GCP_KMS_KEYRING	string	none	Fully qualified GCP KMS keyring name. Required for gcp_kms.
ALMA_GCP_KMS_PROTECTION_LEVEL	enum	SOFTWARE	GCP KMS protection level: HSM or SOFTWARE.

Tracing

Variable	Type	Default	Description
ALMA_TRACES_OTLP_URI	URL	none	OTLP endpoint traces are exported to. Naming an endpoint is what turns tracing on.
ALMA_TRACES_SAMPLING_RATE	number	1.0	Fraction of traces recorded, from 0.0 to 1.0. Requires ALMA_TRACES_OTLP_URI.

Service Matchers

ALMA_MATCH_LABELS is the env-var selector for centrally applied databases, applications, and Kubernetes clusters. One selector covers all three services in this almad process.

Variable	Type	Default	Description
ALMA_MATCH_LABELS	comma-separated key=value list	none	Resource label matcher applied to the database, application and Kubernetes services. Example: env=prod,region=us-east-1.

alma Client Variables

Use these variables to set client defaults for the alma CLI.

Variable	Type	Default	Description
ALMA_PROXY	string	none	Default proxy address.
ALMA_LOGIN	string	none	Default remote host login.
ALMA_CLUSTER	string	current cluster	Default cluster name.
ALMA_KUBE_CLUSTER	string	none	Default Kubernetes cluster name.
ALMA_IDENTITY_FILE	path	none	Identity file path.
BROWSER	string	unset	Standard browser-selection variable, not an ALMA_* variable. Set it to none to match --no-browser.
ALMA_ADD_KEYS_TO_AGENT	string	auto	Control how keys are added to the local SSH agent.
ALMA_MLOCK_MODE	string	auto	Process memory locking mode.
ALMA_DEBUG	boolean	false	Enable verbose CLI logging.
ALMA_KUBECONFIG	path	generated profile path	Override the kubeconfig path written by client-side Kubernetes proxy commands.

Admin Tooling Variables

These variables provide defaults for alma admin subcommands.

Variable	Type	Default	Description
ALMA_IDENTITY_FILE	path	none	Identity file path.
ALMA_EDITOR	string	VISUAL, then EDITOR, then vi	Preferred editor for alma edit.

SSH Session Variables

almad injects these variables into SSH sessions so user programs can identify the current AlmaForge context.

Variable	Type	Description
SSH_ALMA_USER	string	AlmaForge user name for the active session.
SSH_ALMA_CLUSTER_NAME	string	Name of the cluster the node belongs to.
SSH_ALMA_HOST_UUID	string	Unique ID of the node serving the session.
SSH_SESSION_ID	string	Session ID, once the session exists.
ALMA_SESSION	string	Session ID.

Examples

Start an Agent With Environment Variables Only

Terminal

export ALMA_PROXY=proxy.example.com:443export ALMA_CLIENT_ID=replace-me-nameexport ALMA_CLIENT_SECRET=replace-me-secretexport ALMA_SSH_SERVICE=trueexport ALMA_DATABASE_SERVICE=trueexport ALMA_MATCH_LABELS=env=prodexport ALMA_LABELS=env=prod,team=infra
almad start

The Proxy certificate must be trusted by the host. The database service selects centrally registered targets with env=prod. See database access.

Use systemd EnvironmentFile

/etc/systemd/system/almad.service.d/env.conf

[Service]
EnvironmentFile=/etc/almaforge/almad.env

/etc/almaforge/almad.env

ALMA_AUTH_SERVICE=true
ALMA_PROXY_SERVICE=true
ALMA_LISTEN=0.0.0.0:443
ALMA_ADVERTISE=alma.example.com:443
ALMA_STATE_URI=sqlite:///var/lib/almaforge/backend
ALMA_ACME_ENABLED=true
ALMA_ACME_EMAIL=admin@example.com

Terminal

sudo systemctl daemon-reloadsudo systemctl restart almad

Use Docker --env-file

Terminal

cat > almad.env <<'EOF'ALMA_PROXY=proxy.example.com:443ALMA_CLIENT_ID=replace-me-nameALMA_CLIENT_SECRET=replace-me-secretALMA_SSH_SERVICE=trueEOF
docker volume create almad-data
docker run -d --name almad \    --env-file ./almad.env \    --volume almad-data:/var/lib/almaforge \    quay.io/almaforge/almaforge:2026.1.26

The image runs almad start on its own, so the command needs no arguments. An agent publishes no port either: it reaches the Proxy through a tunnel it opens itself, which is why there is nothing to forward and no reason for host networking.

The volume carries the node's identity. Its host UUID is written under /var/lib/almaforge, so a container without one joins as a new node on every restart and leaves the old registration to expire on its own.

A containerized SSH service serves the container. Sessions land in the image's filesystem, not on the machine underneath, so run an agent for the resources it proxies rather than as a way to reach that host.