Kloud Workspace
Stars 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_DEBIAN_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
  • Example:
    env
    WS_APT_ADDITIONAL_DEBIAN_REPOS="deb http://one.test bookworm main; \
                                deb http://two.test bookworm main"
Read More →

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
  • Example:
    env
    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
  • Example:
    env
    WS_APT_ADDITIONAL_PACKAGES="cmake nano"
Read More →

WS_APT_DISABLE_ADDITIONAL_REPO

Disables the additional third-party repository.

When true, /etc/apt/sources.list.d/additional.sources is completely disabled.

  • Type: boolean
Read More →

WS_APT_DISABLE_DEBIAN_REPO

Disables the default Debian repository.

When true, /etc/apt/sources.list.d/debian.sources is completely disabled. This is useful when you rely exclusively on a private mirror.

  • Type: boolean
Read More →

WS_APT_UPDATE_CACHESince 0.0.20

Forces apt-get update before any package action.
  • Type: boolean
Read More →

Auth ​

WS_AUTH_DISABLE_SUDOSince 0.0.20

Disables password-less sudo.
  • Type: boolean

WS_AUTH_PASSWORDSince 0.0.20

Plaintext password for web login.

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

  • Type: string
  • Example:
    env
    WS_AUTH_PASSWORD="super_duper_secret"
Read More →

WS_AUTH_PASSWORD_HASHEDSince 0.0.20

Argon2 hash used for web login.

Takes precedence over plaintext password when both are set.

  • Type: string
  • Example:
    env
    WS_AUTH_PASSWORD_HASHED="$argon2i$v=19$m=4096,t=3,p=1$...$..."
Read More →

Enterprise CA ​

WS_CA_ADDITIONAL_CERT_ALLOW_INSECURESince 0.0.20

Allows insecure (non-TLS) connections to certificates.

Set only in fully trusted network environments such as CI where HTTPS termination is impossible.

  • Type: boolean
Read More →

WS_CA_ADDITIONAL_CERT_ENDPOINTSSince 0.0.20

URLs of additional CA certificates to trust.

Accepts a space-delimited URL list pointing to a PEM-encoded certificate.

  • Type: string
  • Example:
    env
    WS_CA_ADDITIONAL_CERT_ENDPOINTS="http://corp.com/ca.pem \
                                 http://alt.com/root.crt"
Read More →

Docker ​

WS_DOCKER_ENABLE_CLIENTSince 0.0.20

Enables Docker inside the container.
  • Type: boolean
Read More →

Editor ​

WS_EDITOR_ADDITIONAL_VS_EXTENSIONSSince 0.0.20

Installs these Marketplace extension IDs at startup.

Accepts a space-delimited list of extensions.

  • Type: string
  • Example:
    env
    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
  • Example:
    env
    WS_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIR="/additional-extensions"
Read More →

WS_EDITOR_COMMENTS_DISABLE_FONTSince 0.0.20

Disables the custom font used for code comments.
  • Type: boolean
Read More →

WS_EDITOR_SCROLLBAR_SIZESince 0.0.21

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

Features ​

WS_FEATURES_ADDITIONAL_FEATURESSince 0.0.20

Installs additional feature at startup.

Accepts a space-delimited list of features.

  • Type: string
  • Example:
    env
    WS_FEATURES_ADDITIONAL_FEATURES="dotnet jupyter"
Read More →

WS_FEATURES_DIRSince 0.20.0

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
Read More →

Git ​

WS_GIT_CLONE_REPOSince 0.0.20

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
  • Example:
    env
    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).

  • Type: integer
  • Default: 3600

Helm ​

WS_HELM_PRELOAD_CACHESince 0.0.20

Restores the Helm repo cache.
  • Type: boolean

Server ​

WS_SERVER_PORTSince 0.0.20

Port on which the web server listens.
  • Type: integer
  • Default: 8080

WS_SERVER_PROXY_DOMAINSince 0.0.20

Domain suffix used to expose server's forwarded ports.
  • Type: string
  • Example:
    env
    WS_SERVER_PROXY_DOMAIN="ws.dev"
Read More →

WS_SERVER_ROOT_DIRSince 0.0.20

Root directory for the workspace.

This should only be overridden in extreme cases.

  • Type: string
  • Default: /workspace

WS_SERVER_SSL_CERTSince 0.0.21

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
  • Example:
    env
    WS_SERVER_SSL_CERT="/etc/workspace/ssl/server.crt"
Read More →

WS_SERVER_SSL_HOSTSSince 0.0.21

Space delimited DNS names for self-signed certificate.
  • Type: string
  • Default: localhost
  • Example:
    env
    WS_SERVER_SSL_HOSTS="ws.dev *.ws.dev"
Read More →

WS_SERVER_SSL_KEYSince 0.0.21

Path or inline PEM for the private key.
  • Type: string
  • Example:
    env
    WS_SERVER_SSL_KEY="/etc/workspace/ssl/server.key"
Read More →

Terminal ​

WS_TERMINAL_PROMPT_HIDE_DOCKER_CONTEXTSince 0.0.20

Hides Docker context info in the prompt.
  • Type: boolean

WS_TERMINAL_PROMPT_HIDE_HOSTNAMESince 0.0.20

Hides the container hostname in the prompt.
  • Type: boolean

WS_TERMINAL_PROMPT_HIDE_KUBERNETES_CONTEXTSince 0.0.20

Hides current Kubernetes context in the prompt.
  • Type: boolean

WS_TERMINAL_PROMPT_HIDE_NODEJS_VERSIONSince 0.0.20

Hides active Node.js version in the prompt.
  • Type: boolean

WS_TERMINAL_PROMPT_HIDE_PYTHON_VERSIONSince 0.0.20

Hides active Python version in the prompt.
  • Type: boolean

WS_TERMINAL_PROMPT_HIDE_USERSince 0.0.20

Hides the current user in the prompt.
  • Type: boolean

Zsh ​

WS_ZSH_ADDITIONAL_PLUGINSSince 0.0.20

Loads additional oh-my-zsh plugins.
  • Type: string
  • Example:
    env
    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
  • Example:
    env
    WS_ZSH_PLUGINS="kubectl npm python pip"

Deprecated ​

NameReplacementSinceRemoval
WS_APT_UPDATE_REPOSWS_APT_UPDATE_CACHEv0.0.20v0.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