--- url: https://ws.kloudkit.com/settings/configuration.md description: >- Configure Kloud Workspace through environment variables, following a convention-over-configuration approach with sensible defaults. --- # Configuration ::: tip For VS Code editor settings *(JSON-based)*, see [Editor Settings](/editor/settings). ::: ![Dotenv logo](/icons/dotenv.svg){.doc-image} **Kloud Workspace** follows the *convention over configuration* principle, shipping with sensible defaults. Nearly every setting can be overridden with environment variables, giving you maximum flexibility. All configuration is supplied **exclusively** through environment variables. No JSON, YAML, or CLI flags required. This makes the workspace fully *stateless* and cloud-friendly. ::: tip `WS_` Prefix Convention Variables that are consumed **solely** by Kloud Workspace start with `WS__` followed by the name *(example: `WS_ZSH_PLUGINS`)*. When a variable is also consumed by an underlying tool, we keep its original name. Such variables can be reviewed in the [global variables](#global-variables) section. ::: ::: tip Boolean Values To enable a boolean environment variable, set it to a *truthy* value, either `1` or `true`. ::: ## Resolving Secret Values Secret-shaped variables resolve through a four-step chain so the same property works across Docker and Kubernetes without `_FILE` companions: The resolver returns the first match: 1. **Env literal:** `WS_X=value`. 2. **`file:` prefix:** `WS_X=file:/path` reads the file *(one trailing newline stripped, internal newlines preserved)*. 3. **Convention default:** mount a file at `/run/secrets/workspace//` and leave the variable unset. 4. **Schema default:** typically unset. ::: code-group ```sh [Env literal] docker run \ -e WS_AUTH_PASSWORD=super_duper_secret \ ghcr.io/kloudkit/workspace:v0.4.0 ``` ```sh [file: prefix] docker run \ -e WS_AUTH_PASSWORD=file:/run/secrets/workspace/auth/password \ -v ./password.txt:/run/secrets/workspace/auth/password:ro \ ghcr.io/kloudkit/workspace:v0.4.0 ``` ```yaml [Kubernetes] volumes: - name: workspace-secrets secret: secretName: workspace-secrets items: - key: password path: auth/password containers: - name: workspace volumeMounts: - name: workspace-secrets mountPath: /run/secrets/workspace readOnly: true ``` ::: ::: tip `ws-cli show env ` (e.g. `ws-cli show env server.port`) reports where the value came from: `env-set`, `env-file`, `secret-file-default`, or `yaml-default`. Query the dotted key — the matching `WS_*` variable (e.g. `WS_SERVER_PORT`) is what you `export` to set it. ::: ## APT ## Deprecated | Name | Replacement | Since | Removal | | --- | --- | :---: | :---: | | ~~*`WS_APT_UPDATE_REPOS`*~~ | [`WS_APT_UPDATE_CACHE`](#ws-apt-update-cache) | *v0.0.20* | *v0.1.0* | | ~~*`WS_AUTH_GITHUB_TOKEN_FILE`*~~ | [`WS_AUTH_GITHUB_TOKEN`](#ws-auth-github-token) | *v0.3.0* | *v0.3.0* | | ~~*`WS_AUTH_PASSWORD_FILE`*~~ | [`WS_AUTH_PASSWORD`](#ws-auth-password) | *v0.3.0* | *v0.3.0* | | ~~*`WS_AUTH_PASSWORD_HASHED_FILE`*~~ | [`WS_AUTH_PASSWORD_HASHED`](#ws-auth-password-hashed) | *v0.3.0* | *v0.3.0* | | ~~*`WS_CA_ADDITIONAL_CERT_ALLOW_INSECURE`*~~ | [`WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS`](#ws-ca-additional-cert-insecure-endpoints) | *v0.0.22* | *v0.1.0* | | ~~*`WS_CLONE_WORKSPACE_REPO`*~~ | [`WS_GIT_CLONE_REPO`](#ws-git-clone-repo) | *v0.0.20* | *v0.1.0* | | ~~*`WS_COMMENTS_DISABLE_FONT`*~~ | [`WS_EDITOR_COMMENTS_DISABLE_FONT`](#ws-editor-comments-disable-font) | *v0.0.20* | *v0.1.0* | | ~~*`WS_CONFIGURE_DOCKER`*~~ | [`WS_DOCKER_ENABLE_CLIENT`](#ws-docker-enable-client) | *v0.0.20* | *v0.1.0* | | ~~*`WS_CONFIGURE_HELM`*~~ | [`WS_HELM_PRELOAD_CACHE`](#ws-helm-preload-cache) | *v0.0.20* | *v0.1.0* | | ~~*`WS_DISABLE_SUDO`*~~ | [`WS_AUTH_DISABLE_SUDO`](#ws-auth-disable-sudo) | *v0.0.20* | *v0.1.0* | | ~~*`WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR`*~~ | *place .vsix files in `~/.ws/extensions/` instead* | *v0.2.0* | *v0.3.0* | | ~~*`WS_EXTRA_CA_CERT_ENDPOINTS`*~~ | [`WS_CA_ADDITIONAL_CERT_ENDPOINTS`](#ws-ca-additional-cert-endpoints) | *v0.0.20* | *v0.1.0* | | ~~*`WS_EXTRA_CA_CERT_INSECURE`*~~ | [`WS_CA_ADDITIONAL_CERT_ALLOW_INSECURE`](#ws-ca-additional-cert-allow-insecure) | *v0.0.20* | *v0.1.0* | | ~~*`WS_EXTRA_FEATURES`*~~ | [`WS_FEATURES_ADDITIONAL_FEATURES`](#ws-features-additional-features) | *v0.0.20* | *v0.1.0* | | ~~*`WS_EXTRA_VS_EXTENSIONS`*~~ | [`WS_EDITOR_ADDITIONAL_VS_EXTENSIONS`](#ws-editor-additional-vs-extensions) | *v0.0.20* | *v0.1.0* | | ~~*`WS_EXTRA_VS_EXTENSIONS_DIR`*~~ | [`WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR`](#ws-editor-additional-vs-extensions-dir) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PASSWORD`*~~ | [`WS_AUTH_PASSWORD`](#ws-auth-password) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PASSWORD_HASHED`*~~ | [`WS_AUTH_PASSWORD_HASHED`](#ws-auth-password-hashed) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PORT`*~~ | [`WS_SERVER_PORT`](#ws-server-port) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PROMPT_DISABLE_DOCKER`*~~ | [`WS_TERMINAL_PROMPT_HIDE_DOCKER_CONTEXT`](#ws-terminal-prompt-hide-docker-context) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PROMPT_DISABLE_HOSTNAME`*~~ | [`WS_TERMINAL_PROMPT_HIDE_HOSTNAME`](#ws-terminal-prompt-hide-hostname) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PROMPT_DISABLE_KUBERNETES`*~~ | [`WS_TERMINAL_PROMPT_HIDE_KUBERNETES_CONTEXT`](#ws-terminal-prompt-hide-kubernetes-context) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PROMPT_DISABLE_NODEJS`*~~ | [`WS_TERMINAL_PROMPT_HIDE_NODEJS_VERSION`](#ws-terminal-prompt-hide-nodejs-version) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PROMPT_DISABLE_PYTHON`*~~ | [`WS_TERMINAL_PROMPT_HIDE_PYTHON_VERSION`](#ws-terminal-prompt-hide-python-version) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PROMPT_DISABLE_USER`*~~ | [`WS_TERMINAL_PROMPT_HIDE_USER`](#ws-terminal-prompt-hide-user) | *v0.0.20* | *v0.1.0* | | ~~*`WS_PROXY_DOMAIN`*~~ | [`WS_SERVER_PROXY_DOMAIN`](#ws-server-proxy-domain) | *v0.0.20* | *v0.1.0* | | ~~*`WS_ROOT`*~~ | [`WS_SERVER_ROOT`](#ws-server-root) | *v0.0.20* | *v0.1.0* | | ~~*`WS_SECRETS_MASTER_KEY_FILE`*~~ | [`WS_SECRETS_MASTER_KEY`](#ws-secrets-master-key) | *v0.3.0* | *v0.3.0* | | ~~*`WS_SECRETS_VAULT`*~~ | \*The secrets vault has been removed. Declare secrets in the seed manifest at `/.seed.yaml` (the `secrets:` map and `secret: true` entries); see /tools/seed. * | *v0.3.0* | *v0.3.0* | | ~~*`WS_ZSH_EXTRA_PLUGINS`*~~ | [`WS_ZSH_ADDITIONAL_PLUGINS`](#ws-zsh-additional-plugins) | *v0.0.20* | *v0.1.0* | ## Global Variables | ENV | Description | Read More | | --------------------- | -------------------------------------------- | --------- | | `EDITOR` | Default terminal editor *(default: `code`)* | | | `GIT_COMMITTER_NAME` | Name to be used in `~/.gitconfig` | [→][git] | | `GIT_COMMITTER_EMAIL` | Email to be used in `~/.gitconfig` | [→][git] | | `PAGER` | Default terminal pager *(default: `less`)* | | | `TZ` | Define the timezone | | [git]: /tools/git