Environment variables

Environment variables the Go daemon and CLI actually read. Precedence: env var > config file > default.

Two read paths exist:

• Direct reads — os.Getenv/os.LookupEnv at specific call sites (most rows below).
• Koanf env mapping — the config loader additionally maps SHC_* vars onto dotted config keys (SHC_FOO_BAR → foo.bar), with an explicit override table for keys whose names contain underscores (envOverrideMap, core/config/config.go): SHC_KEYCLOAK_REALM → keycloak.realm, SHC_KEYCLOAK_CLIENT_ID → keycloak.client_id, SHC_KEYCLOAK_CLIENT_SECRET → keycloak.client_secret, SHC_INTERNAL_API_BIND → internal_api.bind (plus SHC_LOG_LEVEL/SHC_LOG_FORMAT below). A grep for os.Getenv alone misses these.

Variable	Purpose	Default
SHC_BASE_DIR	Base directory (root of all SHC paths)	auto
SHC_STATE_HOME	State directory	XDG default
SHC_CACHE_HOME	Cache directory	XDG default
SHC_RUNTIME_DIR	Runtime directory	XDG default
SHC_LOGS_DIR	Logs directory	XDG default
SHC_TMP_DIR	Temp directory	auto
SHC_DATABASE_PATH	Database path	auto
SHC_SOCKET_PATH	Unix socket path	auto
SHC_PID_PATH	PID file path	auto

Default resolution context for CLI commands.

Variable	Purpose	Default
SHC_TENANT	Default tenant	default
SHC_ENVIRONMENT	Default environment	default
SHC_STACK	Default stack	—

Variable	Purpose
SHC_HOST	Public host of this SHC install; keycloak/OTEL URLs derive from it.
SHC_PORT	Public listener port.
SHC_URL	Server URL the CLI client connects to.
SHC_ADVERTISE_ADDR	Address this node advertises to cluster peers.
SHC_INTERNAL_TOKEN	Shared token for the internal (peer/LAN) API listener.
SHC_UDS_GROUP	Unix-domain-socket owning group (who may talk to the daemon locally).
SHC_RQLITE_BIND_ADDR	IPv4 the raft engine (rqlited) binds and advertises (cluster mode).
SHC_RQLITE_HTTP_ADDR	rqlited HTTP API bind address override (cluster mode).
SHC_RQLITE_RAFT_ADDR	rqlited raft bind address override (cluster mode).
SHC_RQLITED_BIN	Path to the rqlited binary (else PATH, then the packaged path).
SHC_NODE_PUBLIC_ADDRESS	Operator override for this node’s detected public address (recorded on the node row; wins over cloud-metadata detection).
SHC_INTERNAL_API_BIND	Koanf mapping for internal_api.bind — the internal (peer/LAN) API listener address.

Variable	Purpose	Default
SHC_DEV	Dev mode when 1 (also SHC_MODE=dev).	off
SHC_MODE	dev enables dev mode.	—
SHC_LOG_LEVEL	Log level (debug/info/warn/error).	info
SHC_LOG_FORMAT	Log format (e.g. json, text).	auto
SHC_OUTPUT	CLI output format (tty, json, …).	tty
SHC_FIELDS / SHC_FILTER / SHC_EXCLUDE	CLI output field shaping / row filtering.	—
SHC_DEBUG	CLI debug mode (same as --debug/-d).	off
SHC_VERBOSE	CLI verbose output (same as --verbose/-v).	off

All vault-resolvable; these seed the value when set directly.

Variable	Config equivalent	Purpose
SHC_VAULT_PASSWORD	—	Unlock the local vault at startup.
SHC_BACKUP_REPO	backup.repo	Restic repository.
SHC_BACKUP_PASSWORD	backup.password	Restic repository password.
SHC_KEYCLOAK_REALM	keycloak.realm	Keycloak realm override (koanf mapping).
SHC_KEYCLOAK_CLIENT_ID	keycloak.client_id	Keycloak admin client id (koanf mapping).
SHC_KEYCLOAK_CLIENT_SECRET	keycloak.client_secret	Keycloak admin client secret (koanf mapping).
SHC_CLIENT_ID	—	CLI-only: confidential client id for shc auth --client-credentials (with SHC_CLIENT_SECRET). Not a config override — use SHC_KEYCLOAK_CLIENT_ID for that.
SHC_CLIENT_SECRET	—	CLI-only: confidential client secret for the --client-credentials grant.

Variable	Purpose
SHC_MODULES	Override the set of system apps deployed at init (empty = none).
SHC_BUNDLED_APPS_DIRS	Extra directories scanned for bundled app definitions.
SHC_NODE_LOCATION	Free-form location label for this node.
SHC_COMPOSE_NO_WAIT / SHC_STACK_NO_WAIT	Skip --wait convergence on compose/stack ops.
SHC_INSTALL_POLL_MS	Install progress poll interval (ms).
SHC_HOSTRUN	always / never — override the host-run probe for storage host commands (tests, unusual hosts).

SHC_HUD_TOKEN, SHC_HUD_BEARER, SHC_HUD_EXEC, SHC_HUD_DEBUG configure the terminal HUD’s auth and debug behavior.

SHC_TEST_DB_URL, SHC_TEST_LIB, SHC_TEST_TMP_ROOT, SHC_SYSTEM_RUN (hermetic override for the system runtime dir), SHC_COMPLETION_DEBUG, SHC_COMPLETION_TIMEOUT are used by the test/dev harness and shell completion.

SHC respects the XDG Base Directory Specification for non-root path defaults:

• XDG_CONFIG_HOME (default: ~/.config) — config file directory
• XDG_DATA_HOME (default: ~/.local/share) — state directory
• XDG_CACHE_HOME (default: ~/.cache) — cache directory
• XDG_RUNTIME_DIR (no default) — runtime directory

---

• File Locations
• Config Files
• Config keys