Server Environment Variables

Meshery Server loads its configuration from server/cmd/server-config.env and from process environment variables, which it reads through Viper (viper.AutomaticEnv()).

This page documents:

  • Environment variables that operators set for local, Docker, and Kubernetes deployments.
  • Runtime variables that Meshery reads from the platform when they are present.

It leaves out test-only variables, such as RUN_INTEGRATION_TESTS and PATH_TO_SQL_FILE, and internal keys that Meshery sets for itself during startup.

Core server configuration

VariableDefaultDescriptionExample
PORT8080HTTP listen port for Meshery Server. Local development targets commonly override this to 9081.PORT=9081 make server
LOG_LEVEL4Numeric log level loaded from server-config.env.LOG_LEVEL=5 make server
DEBUGfalseEnables debug behavior and forces debug-level logging even when LOG_LEVEL is lower.DEBUG=true make server-local
ADAPTER_URLSunsetSpace- or comma-separated list of Meshery Adapter endpoints to pre-register at startup.ADAPTER_URLS='localhost:10000 localhost:10001' make server-local
USER_DATA_FOLDER$HOME/.meshery/configDirectory used for Meshery Server state, including the SQLite database.USER_DATA_FOLDER=$HOME/.meshery-dev/config make server
KUBECONFIG_FOLDER$HOME/.kubeDirectory from which Meshery reads Kubernetes configuration files.KUBECONFIG_FOLDER=/home/appuser/.kube docker compose up meshery
KEYS_PATHunset (the Meshery Server image sets /app/server/permissions/keys.csv)Path to a CSV file of permission keys that Meshery seeds into its keys store at startup and after a database reset.KEYS_PATH=/home/appuser/.meshery/keys.csv make server
OTEL_CONFIGunsetInline YAML configuration for OpenTelemetry tracing. When unset, tracing is disabled.OTEL_CONFIG=$'service_name: meshery-server\nservice_version: 1.0.0\nendpoint: localhost:4317\ninsecure: true' make server-local

LOG_LEVEL values are 0=panic, 1=fatal, 2=error, 3=warn, 4=info, 5=debug, and 6=trace.

Provider and authentication configuration

VariableDefaultDescriptionExample
PROVIDERunsetHard-enforces a single provider at server boot. When set to a remote name, Local is not registered and cannot be selected. If the value does not resolve, the server refuses to start. Accepts Local (legacy alias None) or a registered remote name such as Meshery.PROVIDER=Meshery
PROVIDER_BASE_URLSCanonical remote-provider list from install/providers.envComma-separated list of remote provider base URLs that Meshery registers at startup.PROVIDER_BASE_URLS=https://cloud.meshery.io
MESHERY_SERVER_CALLBACK_URLhttp://<request-host>/api/user/tokenOverrides the OAuth callback URL used when Meshery is behind an ingress, reverse proxy, or load balancer. Its host is also the origin an absolute post-login deep-link ref must match.MESHERY_SERVER_CALLBACK_URL=https://playground.meshery.io/api/user/token
PROVIDER_CAPABILITIES_FILEPATHunsetLoads provider capabilities from a local JSON file instead of from the remote provider’s /capabilities endpoint. Useful for offline development and deterministic testing.PROVIDER_CAPABILITIES_FILEPATH=/path/to/capabilities.json
SKIP_DOWNLOAD_EXTENSIONSfalseSkips downloading or refreshing remote provider extension packages. Existing local packages can still be used.SKIP_DOWNLOAD_EXTENSIONS=true make server
PLAYGROUNDfalseEnables playground-specific behavior, including provider preselection flows and playground-oriented post-login redirects.PLAYGROUND=true PROVIDER=Meshery make server-local

The current built-in PROVIDER_BASE_URLS default is the list of active providers in install/providers.env, which is the single source of truth propagated to every install artifact by make providers-propagate:

https://cloud.meshery.io,https://perf.smp-spec.io,https://cloud.layer5.io,https://platform.tata-consulting.co.uk,https://collab.eti.cisco.com,https://kickstart.metabit.com,https://provider.od10.in

The Helm chart and the Docker Compose file ship this same list. If you pin PROVIDER to a Remote Provider, include that provider’s base URL in this list, or the server cannot resolve the provider at startup and refuses to start. The built-in Local provider (legacy alias None) needs no base URL.

Feature flags and runtime behavior

VariableDefaultDescriptionExample
DISABLE_OPERATORfalsePrevents Meshery Server from automatically deploying Meshery Operator into connected clusters.DISABLE_OPERATOR=true make server-without-operator
MESHSYNC_DEFAULT_DEPLOYMENT_MODEembeddedDefault MeshSync deployment mode for Kubernetes connections that do not already specify one. Accepted values are embedded and operator.MESHSYNC_DEFAULT_DEPLOYMENT_MODE=operator
MESHERY_MANAGED_BROKER_PORTFORWARDtrueWhether Meshery Server tunnels to an operator-mode connection’s Meshery Broker through the Kubernetes API when that connection’s cluster is not the one Meshery runs in. Set false to provide your own path to the Broker. See Managed port-forward.MESHERY_MANAGED_BROKER_PORTFORWARD=false
SKIP_DOWNLOAD_CONTENTfalseSkips downloading bundled seed content such as patterns and filters before loading local content.SKIP_DOWNLOAD_CONTENT=true make server
SKIP_COMP_GENfalseSkips background Kubernetes component generation during startup. Explicit API-triggered registration can still run.SKIP_COMP_GEN=true make server
POLICY_EVAL_TIMEOUT3mMaximum duration for a single relationship-policy evaluation. Uses Go duration syntax.POLICY_EVAL_TIMEOUT=5m make server
USE_GO_POLICY_ENGINEfalseUses the Go relationship-policy engine instead of the default Rego/OPA path. The local make server target sets this to true.USE_GO_POLICY_ENGINE=true make server

Build and runtime metadata

The build or deployment pipeline usually injects these variables; end users rarely set them.

VariableDefaultDescriptionExample
BUILDBuild-time value; runtime fallback Not SetMeshery Server version string used in server metadata, provider capability requests, and chart selection.BUILD=v1.0.0 make server
COMMITSHABuild-time value; runtime fallback Not SetGit commit SHA reported in server metadata.COMMITSHA=$(git rev-parse HEAD) make server
RELEASE_CHANNELBuild-time value; runtime fallback Not SetRelease channel reported by the server, such as stable or edge.RELEASE_CHANNEL=stable make server
INSTANCE_IDAuto-generated UUIDUnique Meshery instance identifier used in eventing, connection metadata, and system-owned resources. Must be a UUID; it takes precedence over an INSTANCE_ID in server-config.env. Any other value, including one that is only whitespace or the all-zero UUID, is ignored with a warning, and a new ID is generated. An empty value counts as unset: the ID from server-config.env is used, or a new one is generated without a warning.INSTANCE_ID=$(uuidgen) make server
OSmesheryValue forwarded to remote-provider capability requests so providers can tailor responses to the caller.OS=meshery make server

Platform-provided environment variables

Meshery Server reads these values from the hosting environment when they are present. Kubernetes injects KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT into every pod, and HOME comes from the process environment, so you rarely need to set any of them yourself.

VariableDefaultDescriptionExample
KUBERNETES_SERVICE_HOSTunsetKubernetes service host used to detect in-cluster execution and to build in-cluster Kubernetes contexts. It identifies the cluster Meshery Server runs in; a connection to any other cluster still gets the managed Broker port-forward.KUBERNETES_SERVICE_HOST=10.96.0.1
KUBERNETES_SERVICE_PORTunsetKubernetes service port paired with KUBERNETES_SERVICE_HOST for in-cluster execution.KUBERNETES_SERVICE_PORT=443
HOMEInherited from the process environmentHome directory used when Meshery resolves paths under .meshery/ for local registry/model content.HOME=/home/appuser

Common deployment examples

Local development

PORT=9081 \
DEBUG=true \
USE_GO_POLICY_ENGINE=true \
PROVIDER_BASE_URLS=http://localhost:9876 \
ADAPTER_URLS='localhost:10000 localhost:10001' \
make server-local

Docker deployment with a preselected remote provider

docker run -p 9081:8080 \
  -e PROVIDER=Meshery \
  -e PROVIDER_BASE_URLS=https://cloud.meshery.io \
  -e KUBECONFIG_FOLDER=/home/appuser/.kube \
  meshery/meshery:stable-latest

Kubernetes or ingress-backed deployment

MESHERY_SERVER_CALLBACK_URL=https://meshery.example.com/api/user/token \
PROVIDER=Meshery \
MESHSYNC_DEFAULT_DEPLOYMENT_MODE=operator