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
| Variable | Default | Description | Example |
|---|---|---|---|
PORT | 8080 | HTTP listen port for Meshery Server. Local development targets commonly override this to 9081. | PORT=9081 make server |
LOG_LEVEL | 4 | Numeric log level loaded from server-config.env. | LOG_LEVEL=5 make server |
DEBUG | false | Enables debug behavior and forces debug-level logging even when LOG_LEVEL is lower. | DEBUG=true make server-local |
ADAPTER_URLS | unset | Space- 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/config | Directory used for Meshery Server state, including the SQLite database. | USER_DATA_FOLDER=$HOME/.meshery-dev/config make server |
KUBECONFIG_FOLDER | $HOME/.kube | Directory from which Meshery reads Kubernetes configuration files. | KUBECONFIG_FOLDER=/home/appuser/.kube docker compose up meshery |
KEYS_PATH | unset (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_CONFIG | unset | Inline 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
| Variable | Default | Description | Example |
|---|---|---|---|
PROVIDER | unset | Hard-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_URLS | Canonical remote-provider list from install/providers.env | Comma-separated list of remote provider base URLs that Meshery registers at startup. | PROVIDER_BASE_URLS=https://cloud.meshery.io |
MESHERY_SERVER_CALLBACK_URL | http://<request-host>/api/user/token | Overrides 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_FILEPATH | unset | Loads 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_EXTENSIONS | false | Skips downloading or refreshing remote provider extension packages. Existing local packages can still be used. | SKIP_DOWNLOAD_EXTENSIONS=true make server |
PLAYGROUND | false | Enables 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
| Variable | Default | Description | Example |
|---|---|---|---|
DISABLE_OPERATOR | false | Prevents Meshery Server from automatically deploying Meshery Operator into connected clusters. | DISABLE_OPERATOR=true make server-without-operator |
MESHSYNC_DEFAULT_DEPLOYMENT_MODE | embedded | Default MeshSync deployment mode for Kubernetes connections that do not already specify one. Accepted values are embedded and operator. | MESHSYNC_DEFAULT_DEPLOYMENT_MODE=operator |
SKIP_DOWNLOAD_CONTENT | false | Skips downloading bundled seed content such as patterns and filters before loading local content. | SKIP_DOWNLOAD_CONTENT=true make server |
SKIP_COMP_GEN | false | Skips background Kubernetes component generation during startup. Explicit API-triggered registration can still run. | SKIP_COMP_GEN=true make server |
POLICY_EVAL_TIMEOUT | 3m | Maximum duration for a single relationship-policy evaluation. Uses Go duration syntax. | POLICY_EVAL_TIMEOUT=5m make server |
USE_GO_POLICY_ENGINE | false | Uses 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.
| Variable | Default | Description | Example |
|---|---|---|---|
BUILD | Build-time value; runtime fallback Not Set | Meshery Server version string used in server metadata, provider capability requests, and chart selection. | BUILD=v1.0.0 make server |
COMMITSHA | Build-time value; runtime fallback Not Set | Git commit SHA reported in server metadata. | COMMITSHA=$(git rev-parse HEAD) make server |
RELEASE_CHANNEL | Build-time value; runtime fallback Not Set | Release channel reported by the server, such as stable or edge. | RELEASE_CHANNEL=stable make server |
INSTANCE_ID | Auto-generated UUID | Unique Meshery instance identifier used in eventing, connection metadata, and system-owned resources. | INSTANCE_ID=$(uuidgen) make server |
OS | meshery | Value 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.
| Variable | Default | Description | Example |
|---|---|---|---|
KUBERNETES_SERVICE_HOST | unset | Kubernetes service host used to detect in-cluster execution and to build in-cluster Kubernetes contexts. | KUBERNETES_SERVICE_HOST=10.96.0.1 |
KUBERNETES_SERVICE_PORT | unset | Kubernetes service port paired with KUBERNETES_SERVICE_HOST for in-cluster execution. | KUBERNETES_SERVICE_PORT=443 |
HOME | Inherited from the process environment | Home 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