Configuration ​
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.
WS_<GROUP> Prefix Convention
Variables that are consumed solely by Kloud Workspace start with WS_<GROUP>_ 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 section.
Boolean Values
To enable a boolean environment variable, set it to a truthy value, either 1 or true.
APT ​
WS_APT_ADDITIONAL_GPG_KEYS
List of trusted GPG pairs.
Accepts a space-delimited list of name:url pairs installed to
/etc/apt/keyrings.
The key file is downloaded and saved as /etc/apt/keyrings/<name>.gpg.
If you list more than one URL, separate them with spaces.
WS_APT_ADDITIONAL_GPG_KEYS="name1:keys.example.com/key1.asc \
name2:keys.example.com/key2.gpg"
WS_APT_ADDITIONAL_INSECURE_GPG_KEYS
List of trusted GPG pairs (HTTP or insecure HTTPS).
Accepts a space-delimited list of name:url pairs installed to
/etc/apt/keyrings.
Supports both HTTP and HTTPS URLs. For HTTPS URLs, certificate validation is bypassed using insecure connections.
The key file is downloaded and saved as /etc/apt/keyrings/<name>.gpg.
If you list more than one URL, separate them with spaces.
Use only in fully trusted network environments.
WS_APT_ADDITIONAL_INSECURE_GPG_KEYS=" \
name1:http://keys.example.com/key1.asc \
name2:https://untrusted.com/key2.gpg"
WS_APT_ADDITIONAL_PACKAGES
Additional APT packages installed during startup.
Accepts a space-delimited package list.
WS_APT_ADDITIONAL_PACKAGES="cmake nano"
WS_APT_ADDITIONAL_REPOS
Appends additional repository lines to /etc/apt/sources.list.Accepts a semicolon-delimited list of full deb entries.
Each entry is copied as is, you're responsible for correct suite
(trixie) and component names (main, contrib, ...).
WS_APT_ADDITIONAL_REPOS="deb http://one.test trixie main; deb \
http://two.test trixie main"
WS_APT_DISABLE_REPOS
Disables specified APT repositories or all repositories.
This is useful when you rely exclusively on a private mirror.
Accepts either:
- A space-delimited list of repository names (
debian,additional,trixie). - A boolean
trueor*value to disable all repositories.
WS_APT_DISABLE_REPOS="debian additional"
WS_APT_UPDATE_CACHE
Forces apt-get update before any package action.Read More →Auth ​
WS_AUTH_DISABLE_SUDO
Disables password-less sudo.WS_AUTH_PASSWORD
Plaintext password for web login.
Use only in ephemeral or local environments, never in shared or production deployments.
WS_AUTH_PASSWORD="super_duper_secret"
WS_AUTH_PASSWORD_HASHED
Argon2 hash used for web login.
Takes precedence over plaintext password when both are set.
WS_AUTH_PASSWORD_HASHED="$argon2i$v=19$m=4096,t=3,p=1$...$..."
Enterprise CA ​
WS_CA_ADDITIONAL_CERT_ENDPOINTS
URLs of additional CA certificates to trust (HTTPS only).
Accepts a space-delimited URL list pointing to a PEM-encoded certificate. Only HTTPS URLs are supported for secure certificate retrieval.
WS_CA_ADDITIONAL_CERT_ENDPOINTS="https://corp.com/ca.pem \
https://alt.com/root.crt"
WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS
URLs of additional CA certificates to trust (HTTP or insecure HTTPS).
Accepts a space-delimited URL list pointing to a PEM-encoded certificate. Supports both HTTP and HTTPS URLs. For HTTPS URLs, certificate validation is bypassed using insecure connections.
Use only in fully trusted network environments.
WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS="http://corp.com/ca.pem \
https://untrusted.com/root.crt"
Docker ​
WS_DOCKER_ENABLE_CLIENT
Enables Docker inside the container.Read More →
Editor ​
WS_EDITOR_ADDITIONAL_VS_EXTENSIONS
Installs these Marketplace extension IDs at startup.
Accepts a space-delimited list of extensions.
WS_EDITOR_ADDITIONAL_VS_EXTENSIONS="dbaeumer.vscode-eslint \
esbenp.prettier-vscode"
WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR
Installs .vsix file found in this directory.Use this when you package proprietary or pre-downloaded extensions.
WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR="/additional-extensions"
WS_EDITOR_COMMENTS_DISABLE_FONT
Disables the custom font used for code comments.Read More →
WS_EDITOR_SCROLLBAR_SIZE
Editor's scrollbar size.
You may pass either a bare number (6, becomes 6px) or
the full CSS value with the px suffix (i.e. 6px).
WS_EDITOR_SETTINGS_MERGE
JSON object to deep merge into VSCode settings.json.Values are merged recursively, existing settings not specified are preserved.
For large configs, use WS_EDITOR_SETTINGS_MERGE_FILE.
WS_EDITOR_SETTINGS_MERGE="{"editor.fontSize": 16, "[python]": \
{"editor.tabSize": 4}}"
WS_EDITOR_SETTINGS_MERGE_FILE
Path to a JSON file to deep merge into VSCode settings.json.Alternative to WS_EDITOR_SETTINGS_MERGE for larger configurations.
WS_EDITOR_SETTINGS_MERGE_FILE="/workspace/.settings-override.json"
WS_EDITOR_SETTINGS_OVERRIDE
JSON object to completely replace VSCode settings.json.
WARNING: Removes all default workspace settings.
Use WS_EDITOR_SETTINGS_MERGE for partial updates.
WS_EDITOR_SETTINGS_OVERRIDE="{"editor.fontSize": 16}"
WS_EDITOR_SETTINGS_OVERRIDE_FILE
Path to a JSON file to completely replace VSCode settings.json.Alternative to WS_EDITOR_SETTINGS_OVERRIDE for larger configurations.
WS_EDITOR_SETTINGS_OVERRIDE_FILE="/workspace/.settings.json"
Features ​
WS_FEATURES_ADDITIONAL_FEATURES
Installs additional feature at startup.
Accepts a space-delimited list of features.
WS_FEATURES_ADDITIONAL_FEATURES="dotnet jupyter"
WS_FEATURES_CLOUDFLARED_OPTS
Options for the cloudflared feature installer.
Accepts a semicolon-delimited list of key=value pairs.
Available options:
repo: APT repository base URL (default:https://pkg.cloudflare.com/cloudflared).gpg: Path to GPG key file (default:/etc/apt/keyrings/cloudflare.gpg).release: APT release/suite name (default:any).components: APT repository components (default:main).trusted: Skip GPG verification (default:false).
NOTE
GPG keys should be pre-installed using WS_APT_ADDITIONAL_GPG_KEYS.
WS_FEATURES_CLOUDFLARED_OPTS=" \
repo=https://apt.internal/cloudflare"
WS_FEATURES_DIR
Directory path where additional features are located.
Specify the full path to the directory containing the features to be loaded or referenced at startup.
WS_FEATURES_DOTNET_OPTS
Options for the .NET feature installer.
Accepts a semicolon-delimited list of key=value pairs.
Available options:
repo: APT repository base URL (default:https://packages.microsoft.com/debian/12/prod).gpg: Path to GPG key file (default:/etc/apt/keyrings/microsoft.gpg).release: APT release/suite name (default:bookworm).components: APT repository components (default:main).trusted: Skip GPG verification (default:false).
NOTE
GPG keys should be pre-installed using WS_APT_ADDITIONAL_GPG_KEYS.
WS_FEATURES_DOTNET_OPTS="repo=https://apt.internal/microsoft"
WS_FEATURES_GCLOUD_OPTS
Options for the gcloud CLI feature installer.
Accepts a semicolon-delimited list of key=value pairs.
Available options:
repo: APT repository base URL (default:https://packages.cloud.google.com/apt).gpg: Path to GPG key file (default:/etc/apt/keyrings/google.gpg).release: APT release/suite name (default:cloud-sdk).components: APT repository components (default:main).trusted: Skip GPG verification (default:false).
NOTE
GPG keys should be pre-installed using WS_APT_ADDITIONAL_GPG_KEYS.
WS_FEATURES_GCLOUD_OPTS="repo=https://apt.internal/gcloud"
WS_FEATURES_GH_OPTS
Options for the GitHub CLI feature installer.
Accepts a semicolon-delimited list of key=value pairs.
Available options:
repo: APT repository base URL (default:https://cli.github.com/packages).gpg: Path to GPG key file (default:/etc/apt/keyrings/github.gpg).release: APT release/suite name (default:stable).components: APT repository components (default:main).trusted: Skip GPG verification (default:false).
NOTE
GPG keys should be pre-installed using WS_APT_ADDITIONAL_GPG_KEYS.
WS_FEATURES_GH_OPTS="repo=https://apt.internal/github"
WS_FEATURES_JF_OPTS
Options for the JFrog CLI feature installer.
Accepts a semicolon-delimited list of key=value pairs.
Available options:
repo: APT repository base URL (default:https://releases.jfrog.io/artifactory/jfrog-debs).gpg: Path to GPG key file (default:/etc/apt/keyrings/jfrog.gpg).release: APT release/suite name (default:focal).components: APT repository components (default:contrib).trusted: Skip GPG verification (default:false).
NOTE
GPG keys should be pre-installed using WS_APT_ADDITIONAL_GPG_KEYS.
WS_FEATURES_JF_OPTS="repo=https://apt.internal/jfrog"
WS_FEATURES_PHP_OPTS
Options for the PHP feature installer.
Accepts a semicolon-delimited list of key=value pairs.
Available options:
repo: APT repository base URL (default:https://packages.sury.org/php).gpg: Path to GPG key file (default:/etc/apt/keyrings/php.gpg).release: APT release/suite name (default:trixie).components: APT repository components (default:main).trusted: Skip GPG verification (default:false).
NOTE
GPG keys should be pre-installed using WS_APT_ADDITIONAL_GPG_KEYS.
WS_FEATURES_PHP_OPTS="repo=https://apt.internal/php"
WS_FEATURES_TERRAFORM_OPTS
Options for the Terraform feature installer.
Accepts a semicolon-delimited list of key=value pairs.
Available options:
repo: APT repository base URL (default:https://apt.releases.hashicorp.com).gpg: Path to GPG key file (default:/etc/apt/keyrings/hashicorp.gpg).release: APT release/suite name (default:trixie).components: APT repository components (default:main).trusted: Skip GPG verification (default:false).
NOTE
GPG keys should be pre-installed using WS_APT_ADDITIONAL_GPG_KEYS.
WS_FEATURES_TERRAFORM_OPTS="repo=https://apt.internal/hashicorp"
Git ​
WS_GIT_CLEAR_NOTEBOOK_OUTPUT
Clears outputs from Jupyter notebooks during git operations.
When true, the git filter removes execution outputs and execution
counts from .ipynb files when they are staged for commit.
This helps keep repository history clean by excluding dynamic
output data.
WS_GIT_CLONE_REPO
Clones this repository into ${WS_SERVER_ROOT} at startup.The clone happens only if the target directory is empty. Supports HTTPS and SSH URLs (requires configured SSH keys).
WS_GIT_CLONE_REPO="https://github.com/example/repo.git"
WS_GIT_CREDENTIAL_CACHE_TIMEOUT
Lifetime (seconds) of cached Git credentials.
Providing a value of -1 will sech the cache timeout to 1
year (31536000 seconds).
Helm ​
WS_HELM_PRELOAD_CACHE
Restores the Helm repo cache.Read More →
Logging ​
WS_LOGGING_DIR
Base directory for all workspace logs.
WS_LOGGING_DISABLE_CONSOLE_OUTPUT
Disable console logging.
When true, console logging will not be redirected to
stdout/stderr, however, logs will still be stored on disk at
"${WS_LOGGING_DIR}/${WS_LOGGING_MAIN_FILE}".
WS_LOGGING_MAIN_FILE
Combined log file forstdoutandstderr.
Metrics ​
WS_METRICS_COLLECTORS
Comma-separated list of metric collectors to enable.
Accepts a comma-delimited list of collectors with dot-notation for granularity.
Available collectors:
| Collector | Description |
|---|---|
workspace |
All workspace metrics |
workspace.info |
Workspace build info |
workspace.session |
Session timestamp and uptime |
workspace.extensions |
Installed extensions count |
container |
All container metrics |
container.cpu |
CPU usage metrics |
container.memory |
Memory usage metrics |
container.fs |
Filesystem usage metrics |
container.fd |
File descriptor metrics |
container.pids |
Process metrics |
pressure |
All pressure metrics |
pressure.cpu |
CPU pressure metrics |
pressure.memory |
Memory pressure metrics |
pressure.io |
IO pressure metrics |
network |
Network metrics |
sockets |
Socket metrics |
io |
IO metrics |
gpu |
GPU metrics (requires nvidia-smi) |
When unset or *, all collectors are enabled (gpu, if available).
WS_METRICS_COLLECTORS="workspace,container.cpu,gpu"
WS_METRICS_ENABLE
Enables the Prometheus metrics exporter.
When true, starts a metrics server that exposes Prometheus-compatible
metrics at / on the configured port.
Metrics include workspace info, session data, extensions count, and container resource usage (CPU, memory, disk, file descriptors).
WS_METRICS_PORT
Port on which the metrics endpoint listens.
The metrics server exposes a / endpoint on this port.
Default port 9100 follows the node_exporter convention.
Secrets ​
WS_SECRETS_MASTER_KEY
Master encryption key for secrets vault.
Used to encrypt and decrypt secrets in the vault. Can be provided as:
- A base64-encoded string.
- A plaintext string.
Master key lookup precedence:
- CLI
--masterflag (if provided). WS_SECRETS_MASTER_KEY(this variable).WS_SECRETS_MASTER_KEY_FILE./etc/workspace/master.key(default path).
WS_SECRETS_MASTER_KEY="dGhpcyBpcyBhIHNlY3JldCBrZXkgZXhhbXBsZQ=="
WS_SECRETS_MASTER_KEY_FILE
Path to file containing the master encryption key.
Used to encrypt and decrypt secrets in the vault. Can be provided as:
- A base64-encoded string.
- A plaintext string.
*Master key lookup precedence:
- CLI
--masterflag (if provided). WS_SECRETS_MASTER_KEY.WS_SECRETS_MASTER_KEY_FILE(this variable)./etc/workspace/master.key(default path).
WS_SECRETS_MASTER_KEY_FILE="/etc/workspace/custom-master.key"
WS_SECRETS_VAULT
Path to the secrets vault file.
A YAML file containing encrypted secrets that can be decrypted and deployed to various destinations during startup.
WS_SECRETS_VAULT="/workspace/.vault.yaml"
Server ​
WS_SERVER_PORT
Port on which the web server listens.
WS_SERVER_PROXY_DOMAIN
Domain suffix used to expose server's forwarded ports.
Accepts either a single domain suffix or multiple space-delimited suffixes. > Multiple domain support was added in v0.0.22.
WS_SERVER_PROXY_DOMAIN="ws.dev local.ws.dev"
WS_SERVER_ROOT_DIR
Root directory for the workspace.
This should only be overridden in extreme cases.
WS_SERVER_SSL_CERT
Path or inline PEM for the server certificate.
Accepts either:
- A full path to the mounted PEM-encoded certificate
- Literal certificate body starting with
-----BEGIN CERTIFICATE-----(newline characters may be provided as\nescapes).
When this is unset but WS_SERVER_SSL_KEY is provided, the
key is reused to mint a self-signed certificate for
WS_SERVER_SSL_HOSTS (or localhost).
WS_SERVER_SSL_CERT="/etc/workspace/ssl/server.crt"
WS_SERVER_SSL_HOSTS
Space-delimited DNS names for self-signed certificate.
WS_SERVER_SSL_HOSTS="ws.dev *.ws.dev"
WS_SERVER_SSL_KEY
Path or inline PEM for the private key.
WS_SERVER_SSL_KEY="/etc/workspace/ssl/server.key"
Startup ​
WS_STARTUP_FAIL_ON_ERROR
Fail fast if any startup script exits non-zero.
Terminal ​
WS_TERMINAL_PROMPT_HIDE_DOCKER_CONTEXT
Hides Docker context info in the prompt.Read More →
WS_TERMINAL_PROMPT_HIDE_HOSTNAME
Hides the container hostname in the prompt.Read More →
WS_TERMINAL_PROMPT_HIDE_KUBERNETES_CONTEXT
Hides current Kubernetes context in the prompt.Read More →
WS_TERMINAL_PROMPT_HIDE_NODEJS_VERSION
Hides active Node.js version in the prompt.Read More →
WS_TERMINAL_PROMPT_HIDE_PYTHON_VERSION
Hides active Python version in the prompt.Read More →
WS_TERMINAL_PROMPT_HIDE_USER
Hides the current user in the prompt.Read More →
Zsh ​
WS_ZSH_ADDITIONAL_PLUGINS
Loads additional oh-my-zsh plugins.WS_ZSH_ADDITIONAL_PLUGINS="php"
WS_ZSH_PLUGINS
Enables built-in oh-my-zsh plugins.WS_ZSH_PLUGINS="kubectl npm python pip"
Deprecated ​
| Name | Replacement | Since | Removal |
|---|---|---|---|
WS_APT_UPDATE_REPOS | WS_APT_UPDATE_CACHE | v0.0.20 | v0.1.0 |
WS_CA_ADDITIONAL_CERT_ALLOW_INSECURE | WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS | v0.0.22 | v0.1.0 |
WS_CLONE_WORKSPACE_REPO | WS_GIT_CLONE_REPO | v0.0.20 | v0.1.0 |
WS_COMMENTS_DISABLE_FONT | WS_EDITOR_COMMENTS_DISABLE_FONT | v0.0.20 | v0.1.0 |
WS_CONFIGURE_DOCKER | WS_DOCKER_ENABLE_CLIENT | v0.0.20 | v0.1.0 |
WS_CONFIGURE_HELM | WS_HELM_PRELOAD_CACHE | v0.0.20 | v0.1.0 |
WS_DISABLE_SUDO | WS_AUTH_DISABLE_SUDO | v0.0.20 | v0.1.0 |
WS_EXTRA_CA_CERT_ENDPOINTS | WS_CA_ADDITIONAL_CERT_ENDPOINTS | v0.0.20 | v0.1.0 |
WS_EXTRA_CA_CERT_INSECURE | WS_CA_ADDITIONAL_CERT_ALLOW_INSECURE | v0.0.20 | v0.1.0 |
WS_EXTRA_FEATURES | WS_FEATURES_ADDITIONAL_FEATURES | v0.0.20 | v0.1.0 |
WS_EXTRA_VS_EXTENSIONS | WS_EDITOR_ADDITIONAL_VS_EXTENSIONS | v0.0.20 | v0.1.0 |
WS_EXTRA_VS_EXTENSIONS_DIR | WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR | v0.0.20 | v0.1.0 |
WS_PASSWORD | WS_AUTH_PASSWORD | v0.0.20 | v0.1.0 |
WS_PASSWORD_HASHED | WS_AUTH_PASSWORD_HASHED | v0.0.20 | v0.1.0 |
WS_PORT | WS_SERVER_PORT | v0.0.20 | v0.1.0 |
WS_PROMPT_DISABLE_DOCKER | WS_TERMINAL_PROMPT_HIDE_DOCKER_CONTEXT | v0.0.20 | v0.1.0 |
WS_PROMPT_DISABLE_HOSTNAME | WS_TERMINAL_PROMPT_HIDE_HOSTNAME | v0.0.20 | v0.1.0 |
WS_PROMPT_DISABLE_KUBERNETES | WS_TERMINAL_PROMPT_HIDE_KUBERNETES_CONTEXT | v0.0.20 | v0.1.0 |
WS_PROMPT_DISABLE_NODEJS | WS_TERMINAL_PROMPT_HIDE_NODEJS_VERSION | v0.0.20 | v0.1.0 |
WS_PROMPT_DISABLE_PYTHON | WS_TERMINAL_PROMPT_HIDE_PYTHON_VERSION | v0.0.20 | v0.1.0 |
WS_PROMPT_DISABLE_USER | WS_TERMINAL_PROMPT_HIDE_USER | v0.0.20 | v0.1.0 |
WS_PROXY_DOMAIN | WS_SERVER_PROXY_DOMAIN | v0.0.20 | v0.1.0 |
WS_ROOT | WS_SERVER_ROOT | v0.0.20 | v0.1.0 |
WS_ZSH_EXTRA_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_COMMITTER_EMAIL | Email to be used in ~/.gitconfig | → |
PAGER | Default terminal pager (default: less) | |
TZ | Define the timezone |