Kloud Workspace
Docker BadgeStars Badge

Configuration ​

Dotenv logo

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.

Type
string
Default
null
sh
WS_APT_ADDITIONAL_GPG_KEYS="name1:keys.example.com/key1.asc \
                            name2:keys.example.com/key2.gpg"
Read More →

WS_APT_ADDITIONAL_PACKAGES

Additional APT packages installed during startup.

Accepts a space-delimited package list.

Type
string
Default
null
sh
WS_APT_ADDITIONAL_PACKAGES="cmake nano"
Read More →

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 (bookworm) and component names (main, contrib, ...).

Type
string
Default
null
sh
WS_APT_ADDITIONAL_REPOS="deb http://one.test bookworm main; deb \
                         http://two.test bookworm main"
Read More →

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 true or * value to disable all repositories.
Type
string
Default
null
Since
v0.0.22
sh
WS_APT_DISABLE_REPOS="debian additional"
Read More →

WS_APT_UPDATE_CACHE

Forces apt-get update before any package action.
Type
boolean
Default
false
Since
v0.0.20
Read More →

Auth ​

WS_AUTH_DISABLE_SUDO

Disables password-less sudo.
Type
boolean
Default
false
Since
v0.0.20

WS_AUTH_PASSWORD

Plaintext password for web login.

Use only in ephemeral or local environments, never in shared or production deployments.

Type
string
Default
null
Since
v0.0.20
sh
WS_AUTH_PASSWORD="super_duper_secret"
Read More →

WS_AUTH_PASSWORD_HASHED

Argon2 hash used for web login.

Takes precedence over plaintext password when both are set.

Type
string
Default
null
Since
v0.0.20
sh
WS_AUTH_PASSWORD_HASHED="$argon2i$v=19$m=4096,t=3,p=1$...$..."
Read More →

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.

Type
string
Default
null
Since
v0.0.20
sh
WS_CA_ADDITIONAL_CERT_ENDPOINTS="https://corp.com/ca.pem \
                                 https://alt.com/root.crt"
Read More →

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.

Type
string
Default
null
Since
v0.0.22
sh
WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS="http://corp.com/ca.pem \
                                          https://untrusted.com/root.crt"
Read More →

Docker ​

WS_DOCKER_ENABLE_CLIENT

Enables Docker inside the container.
Type
boolean
Default
false
Since
v0.0.20
Read More →

Editor ​

WS_EDITOR_ADDITIONAL_VS_EXTENSIONS

Installs these Marketplace extension IDs at startup.

Accepts a space-delimited list of extensions.

Type
string
Default
null
Since
v0.0.20
sh
WS_EDITOR_ADDITIONAL_VS_EXTENSIONS="dbaeumer.vscode-eslint \
                                    esbenp.prettier-vscode"
Read More →

WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR

Installs .vsix file found in this directory.

Use this when you package proprietary or pre-downloaded extensions.

Type
string
Default
null
sh
WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR="/additional-extensions"
Read More →

WS_EDITOR_COMMENTS_DISABLE_FONT

Disables the custom font used for code comments.
Type
boolean
Default
false
Since
v0.0.20
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).

Type
string
Default
2px
Since
v0.0.21

Features ​

WS_FEATURES_ADDITIONAL_FEATURES

Installs additional feature at startup.

Accepts a space-delimited list of features.

Type
string
Default
null
Since
v0.0.20
sh
WS_FEATURES_ADDITIONAL_FEATURES="dotnet jupyter"
Read More →

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.

Type
string
Default
/usr/share/workspace/features
Since
v0.20.0
Read More →

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.

Type
boolean
Default
false
Since
v0.0.22
Read More →

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).

Type
string
Default
null
Since
v0.0.20
sh
WS_GIT_CLONE_REPO="https://github.com/example/repo.git"
Read More →

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).

Type
integer
Default
3600
Read More →

Helm ​

WS_HELM_PRELOAD_CACHE

Restores the Helm repo cache.
Type
boolean
Default
false
Since
v0.0.20
Read More →

Logging ​

WS_LOGGING_DIR

Base directory for all workspace logs.
Type
string
Default
/var/log/workspace
Since
v0.0.21

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}".

Type
boolean
Default
false
Since
v0.0.22

WS_LOGGING_MAIN_FILE

Combined log file for stdout and stderr.
Type
string
Default
workspace.log
Since
v0.0.21

Server ​

WS_SERVER_PORT

Port on which the web server listens.
Type
integer
Default
8080
Since
v0.0.20

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.

Type
string
Default
null
Since
v0.0.20
sh
WS_SERVER_PROXY_DOMAIN="ws.dev local.ws.dev"
Read More →

WS_SERVER_ROOT_DIR

Root directory for the workspace.

This should only be overridden in extreme cases.

Type
string
Default
/workspace
Since
v0.0.20

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 \n escapes).

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).

Type
string
Default
null
Since
v0.0.21
sh
WS_SERVER_SSL_CERT="/etc/workspace/ssl/server.crt"
Read More →

WS_SERVER_SSL_HOSTS

Space-delimited DNS names for self-signed certificate.
Type
string
Default
localhost
Since
v0.0.21
sh
WS_SERVER_SSL_HOSTS="ws.dev *.ws.dev"
Read More →

WS_SERVER_SSL_KEY

Path or inline PEM for the private key.
Type
string
Default
null
Since
v0.0.21
sh
WS_SERVER_SSL_KEY="/etc/workspace/ssl/server.key"
Read More →

Startup ​

WS_STARTUP_FAIL_ON_ERROR

Fail fast if any startup script exits non-zero.
Type
boolean
Default
false
Since
v0.0.21

Terminal ​

WS_TERMINAL_PROMPT_HIDE_DOCKER_CONTEXT

Hides Docker context info in the prompt.
Type
boolean
Default
false
Since
v0.0.20
Read More →

WS_TERMINAL_PROMPT_HIDE_HOSTNAME

Hides the container hostname in the prompt.
Type
boolean
Default
false
Since
v0.0.20
Read More →

WS_TERMINAL_PROMPT_HIDE_KUBERNETES_CONTEXT

Hides current Kubernetes context in the prompt.
Type
boolean
Default
false
Since
v0.0.20
Read More →

WS_TERMINAL_PROMPT_HIDE_NODEJS_VERSION

Hides active Node.js version in the prompt.
Type
boolean
Default
false
Since
v0.0.20
Read More →

WS_TERMINAL_PROMPT_HIDE_PYTHON_VERSION

Hides active Python version in the prompt.
Type
boolean
Default
false
Since
v0.0.20
Read More →

WS_TERMINAL_PROMPT_HIDE_USER

Hides the current user in the prompt.
Type
boolean
Default
false
Since
v0.0.20
Read More →

Zsh ​

WS_ZSH_ADDITIONAL_PLUGINS

Loads additional oh-my-zsh plugins.
Type
string
Default
null
Since
v0.0.20
sh
WS_ZSH_ADDITIONAL_PLUGINS="php"

WS_ZSH_PLUGINS

Enables built-in oh-my-zsh plugins.
Type
string
Default
1password docker encode64 git golang helm kubectl npm python pip ssh-agent yarn zsh-autosuggestions zsh-fzf-history-search
sh
WS_ZSH_PLUGINS="kubectl npm python pip"

Deprecated ​

NameReplacementSinceRemoval
WS_APT_UPDATE_REPOSWS_APT_UPDATE_CACHEv0.0.20v0.1.0
WS_CA_ADDITIONAL_CERT_ALLOW_INSECUREWS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTSv0.0.22v0.1.0
WS_CLONE_WORKSPACE_REPOWS_GIT_CLONE_REPOv0.0.20v0.1.0
WS_COMMENTS_DISABLE_FONTWS_EDITOR_COMMENTS_DISABLE_FONTv0.0.20v0.1.0
WS_CONFIGURE_DOCKERWS_DOCKER_ENABLE_CLIENTv0.0.20v0.1.0
WS_CONFIGURE_HELMWS_HELM_PRELOAD_CACHEv0.0.20v0.1.0
WS_DISABLE_SUDOWS_AUTH_DISABLE_SUDOv0.0.20v0.1.0
WS_EXTRA_CA_CERT_ENDPOINTSWS_CA_ADDITIONAL_CERT_ENDPOINTSv0.0.20v0.1.0
WS_EXTRA_CA_CERT_INSECUREWS_CA_ADDITIONAL_CERT_ALLOW_INSECUREv0.0.20v0.1.0
WS_EXTRA_FEATURESWS_FEATURES_ADDITIONAL_FEATURESv0.0.20v0.1.0
WS_EXTRA_VS_EXTENSIONSWS_EDITOR_ADDITIONAL_VS_EXTENSIONSv0.0.20v0.1.0
WS_EXTRA_VS_EXTENSIONS_DIRWS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIRv0.0.20v0.1.0
WS_PASSWORDWS_AUTH_PASSWORDv0.0.20v0.1.0
WS_PASSWORD_HASHEDWS_AUTH_PASSWORD_HASHEDv0.0.20v0.1.0
WS_PORTWS_SERVER_PORTv0.0.20v0.1.0
WS_PROMPT_DISABLE_DOCKERWS_TERMINAL_PROMPT_HIDE_DOCKER_CONTEXTv0.0.20v0.1.0
WS_PROMPT_DISABLE_HOSTNAMEWS_TERMINAL_PROMPT_HIDE_HOSTNAMEv0.0.20v0.1.0
WS_PROMPT_DISABLE_KUBERNETESWS_TERMINAL_PROMPT_HIDE_KUBERNETES_CONTEXTv0.0.20v0.1.0
WS_PROMPT_DISABLE_NODEJSWS_TERMINAL_PROMPT_HIDE_NODEJS_VERSIONv0.0.20v0.1.0
WS_PROMPT_DISABLE_PYTHONWS_TERMINAL_PROMPT_HIDE_PYTHON_VERSIONv0.0.20v0.1.0
WS_PROMPT_DISABLE_USERWS_TERMINAL_PROMPT_HIDE_USERv0.0.20v0.1.0
WS_PROXY_DOMAINWS_SERVER_PROXY_DOMAINv0.0.20v0.1.0
WS_ROOTWS_SERVER_ROOTv0.0.20v0.1.0
WS_ZSH_EXTRA_PLUGINSWS_ZSH_ADDITIONAL_PLUGINSv0.0.20v0.1.0

Global Variables ​

ENVDescriptionRead More
EDITORDefault terminal editor (default: code)
GIT_COMMITTER_NAMEName to be used in ~/.gitconfig→
GIT_COMMITTER_EMAILEmail to be used in ~/.gitconfig→
PAGERDefault terminal pager (default: less)
TZDefine the timezone

Released under the MIT License

Copyright © 2025 KloudKIT