Skip to content

Configuration ​

💡 TIP

For VS Code editor settings (JSON-based), see Editor Settings.

Dotenv logo

Kloud Workspace ships with sensible defaults, and nearly every setting can be overridden with an environment variable.

Settings are environment variables. Secrets can also come from mounted files, and drop-in directories under ~/.ws add startup scripts, certificates, extensions and seed files.

Set Variables ​

Pass variables to the container with -e:

sh
docker run \
  -e WS_METRICS_ENABLE=true \
  -e TZ=Europe/London \
  ghcr.io/kloudkit/workspace:v0.6.0

To keep them in a file, write one NAME=value per line, such as this workspace.env:

ini
WS_METRICS_ENABLE=true
TZ=Europe/London

Then pass the file with --env-file:

sh
docker run --env-file workspace.env ghcr.io/kloudkit/workspace:v0.6.0

Docker skips lines that start with # and keeps quotes as part of the value, so leave values unquoted.

WS_<GROUP> Prefix Convention

Variables that are consumed solely by Kloud Workspace start with WS_<GROUP>_ followed by the name (example: WS_ZSH_PLUGINS).

A variable that an underlying tool also reads keeps that tool's original name. Those are listed under Global Variables.

Boolean Values

To enable a boolean environment variable, set it to a truthy value, either 1 or true.

Resolving Secret Values ​

These variables hold secrets, so each one can also be read from a file, and the same setting works across Docker and Kubernetes without _FILE companion variables:

  • WS_AUTH_PASSWORD: Plaintext password for web login.
  • WS_AUTH_PASSWORD_HASHED: Argon2 hash used for web login.
  • WS_AUTH_GITHUB_TOKEN: GitHub personal access token for the workspace and gh.
  • WS_AUTH_OIDC_CLIENT_SECRET: OIDC client secret. Required when WS_AUTH_MODE=oidc.
  • WS_AUTH_OIDC_COOKIE_SECRET: Secret that seals the OIDC session cookie.
  • WS_CLOUDFLARED_TUNNEL_TOKEN: Cloudflare tunnel connector token.
  • WS_SECRETS_MASTER_KEY: Master encryption key for seed secrets.
  • WS_SERVER_SSL_CERT: Inline PEM or file: path for the server certificate.
  • WS_SERVER_SSL_KEY: Inline PEM or file: path for the private key.

Each value comes from the first of these that applies:

  1. Literal value: WS_X=value.
  2. file: prefix: WS_X=file:/path reads the file (the editor trims surrounding whitespace; ws-cli strips one trailing newline).
  3. Mounted file: mount a file at /run/secrets/workspace/<group>/<property> and leave the variable unset.
  4. Default: typically unset.
sh
docker run \
  -e WS_AUTH_PASSWORD=super_duper_secret \
  ghcr.io/kloudkit/workspace:v0.6.0
sh
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.6.0
yaml
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

To see where a value came from, run ws-cli show env with its dotted key, such as ws-cli show env server.port for WS_SERVER_PORT. The source reads process (the environment), file (a file: path), mount(the /run/secrets/workspace convention), alias (a deprecated name) or declared(the default). Set the matching WS_* variable, not the dotted key, to change it. In an editor terminal, secrets passed as plain environment values are already removed, so they show as unset.

AI ​

WS_AI_MCP_ALLOW_WRITE

Enables the MCP tools that act on the workspace.

When true, ws-cli serve mcp also serves the tools that change the workspace (open a file in the editor, apply a template).

When unset, only the read-only tools are served.

Type
boolean
Default
false
Since
vnext

WS_AI_MCP_TOOLS

Comma-separated list of MCP tools to serve.

Accepts a comma-delimited list of tool groups and tool names (show_env).

Available groups:

Group Description
editor Editor diagnostics, open tabs and selection
feature Available features and the feature store
info Version, uptime, metrics and extensions
logs Workspace logs
port Listening ports and which are public
seed Seed destinations
show Settings, IP addresses and locations
template Configuration templates

When unset or *, all tools are served. An entry that names no group or tool is ignored, and the tools that act on the workspace also need WS_AI_MCP_ALLOW_WRITE.

Type
string
Default
*
Delimiter
comma
Since
vnext
sh
WS_AI_MCP_TOOLS="info,show_env,editor"

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
Delimiter
space
sh
WS_APT_ADDITIONAL_GPG_KEYS="name1:keys.example.com/key1.asc \
                            name2:keys.example.com/key2.gpg"
Read More →

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.

Type
string
Default
null
Delimiter
space
Since
v0.1.0
sh
WS_APT_ADDITIONAL_INSECURE_GPG_KEYS=" \
                                     name1:http://keys.example.com/key1.asc \
                                     name2:https://untrusted.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
Delimiter
space
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 (trixie) and component names (main, contrib, ...).

Type
string
Default
null
Delimiter
semicolon
sh
WS_APT_ADDITIONAL_REPOS="deb http://one.test trixie main; deb \
                         http://two.test trixie 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).
  • A boolean true or * value to disable all repositories.
Type
string
Default
null
Delimiter
space
Since
v0.0.22
sh
WS_APT_DISABLE_REPOS="debian additional"
Read More →

WS_APT_DISABLE_RESTRICTIONS

Disables specified APT install restrictions or all restrictions.

The workspace ships with a set of preference files that block GUI/desktop and other packages that have no use inside a headless container (x11, desktop, mail, printing, daemons, cni, obsolete).

Accepts either:

  • A space-delimited list of restriction names.
  • A boolean true or * value to disable all restrictions.
Type
string
Default
null
Delimiter
space
Since
v0.3.0
sh
WS_APT_DISABLE_RESTRICTIONS="x11 mail"
Read More →

WS_APT_OVERRIDE_RESTRICTIONS

Temporarily lifts all APT install restrictions for additional_packages.

Distinct from disable_restrictions, which permanently lifts restrictions at startup. This flag applies only to the additional_packages install step: every active /etc/apt/preferences.d/99-deny-* pin is renamed to .disabled immediately before the install and restored when it completes (including on failure).

Set to true when an entry in additional_packages is blocked by a shipped restriction and a permanent lift is undesirable.

Type
boolean
Default
false
Since
v0.3.0
sh
WS_APT_OVERRIDE_RESTRICTIONS="true"
Read More →

WS_APT_UPDATE_CACHE

Runs apt-get update when a new container starts, before WS_APT_ADDITIONAL_PACKAGES installs.
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.2

WS_AUTH_GITHUB_TOKEN

GitHub personal access token for the workspace and gh.

Authenticates the workspace's GitHub provider and, when the opt-in gh feature is installed, runs gh auth login --with-token. Terminal git HTTPS auth is not wired, use SSH or a credential helper.

Resolution chain:

  1. Env literal: WS_AUTH_GITHUB_TOKEN=ghp_....
  2. file: env value: WS_AUTH_GITHUB_TOKEN=file:/path/to/token.
  3. Convention default: file mounted at /run/secrets/workspace/auth/github_token.
  4. Schema default (unset).
Type
string
Default
null
Since
v0.3.0
sh
WS_AUTH_GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Read More →

WS_AUTH_MODE

Web authentication mode, either password or oidc.
  • password (default): the editor's built-in password login via WS_AUTH_PASSWORD / WS_AUTH_PASSWORD_HASHED.
  • oidc: the editor signs users in with OpenID Connect on WS_SERVER_PORT. Requires WS_AUTH_OIDC_ISSUER, WS_AUTH_OIDC_CLIENT_ID, WS_AUTH_OIDC_CLIENT_SECRET and WS_AUTH_OIDC_ALLOWED_EMAILS, and refuses to start without them or alongside a password.

Any other value is treated as password.

Type
string
Default
password
Since
v0.4.0
sh
WS_AUTH_MODE="oidc"
Read More →

WS_AUTH_OIDC_ALLOWED_EMAILS

Emails allowed to sign in with OIDC.

A space-delimited list of addresses and *@domain entries, matched case-insensitively against the IdP's email claim. Required when WS_AUTH_MODE=oidc; any other entry refuses start.

Type
string
Default
null
Delimiter
space
Since
v0.4.0
sh
WS_AUTH_OIDC_ALLOWED_EMAILS="alice@corp.com *@team.corp.com"
Read More →

WS_AUTH_OIDC_CLIENT_ID

OIDC client ID. Required when WS_AUTH_MODE=oidc.
Type
string
Default
null
Since
v0.4.0
sh
WS_AUTH_OIDC_CLIENT_ID="workspace"
Read More →

WS_AUTH_OIDC_CLIENT_SECRET

OIDC client secret. Required when WS_AUTH_MODE=oidc.

Register the workspace with the IdP as a confidential client and supply its secret here, per deployment.

Resolution chain:

  1. Env literal: WS_AUTH_OIDC_CLIENT_SECRET=....
  2. file: env value: WS_AUTH_OIDC_CLIENT_SECRET=file:/path/to/secret.
  3. Convention default: file mounted at /run/secrets/workspace/auth/oidc_client_secret.
  4. Schema default (unset).
Type
string
Default
null
Since
v0.4.0
Read More →
Secret that seals the OIDC session cookie.

At least 16 bytes. When unset it is generated once under ~/.ws/state, so sessions survive restarts and redeploys that keep that volume; set a shared value for several replicas. Only used when WS_AUTH_MODE=oidc.

Resolution chain:

  1. Env literal: WS_AUTH_OIDC_COOKIE_SECRET=....
  2. file: env value: WS_AUTH_OIDC_COOKIE_SECRET=file:/path/to/secret.
  3. Convention default: file mounted at /run/secrets/workspace/auth/oidc_cookie_secret.
  4. Generated and persisted (unset).
Type
string
Default
null
Since
v0.4.0
Read More →

WS_AUTH_OIDC_ISSUER

OIDC issuer URL. Required when WS_AUTH_MODE=oidc.

The OpenID Connect issuer (discovery base URL). For Active Directory, point at an OIDC-fronting issuer (Entra ID, Keycloak, dex) rather than raw LDAP.

Type
string
Default
null
Since
v0.4.0
sh
WS_AUTH_OIDC_ISSUER="https://idp.example.com"
Read More →

WS_AUTH_OIDC_REDIRECT_URL

OIDC callback URLs, one per domain.

A space-delimited list of https://<host>/oauth2/callback URLs. Each sign-in uses the entry on its host, else one in the same proxy domain, else a lone entry; unset, the callback is derived from the request host. Only used when WS_AUTH_MODE=oidc.

Type
string
Default
null
Delimiter
space
Since
v0.4.0
sh
WS_AUTH_OIDC_REDIRECT_URL="https://ws.example.com/oauth2/callback \
                           https://ws.other.dev/oauth2/callback"
Read More →

WS_AUTH_OIDC_SCOPES

OAuth scopes requested at login.

A space-delimited scope list requested from the IdP; openid is added when missing. Only used when WS_AUTH_MODE=oidc.

Type
string
Default
openid email profile
Delimiter
space
Since
v0.4.0
sh
WS_AUTH_OIDC_SCOPES="openid email profile"
Read More →

WS_AUTH_PASSWORD

Plaintext password for web login.

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

Resolution chain:

  1. Env literal: WS_AUTH_PASSWORD=mySecret.
  2. file: env value: WS_AUTH_PASSWORD=file:/path/to/password.
  3. Convention default: file mounted at /run/secrets/workspace/auth/password.
  4. Schema default (unset).

WS_AUTH_PASSWORD_HASHED takes precedence over this when both resolve to a non-empty value.

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.

Resolution chain:

  1. Env literal: WS_AUTH_PASSWORD_HASHED=<argon2-hash>.
  2. file: env value: WS_AUTH_PASSWORD_HASHED=file:/path/to/hash.
  3. Convention default: file mounted at /run/secrets/workspace/auth/password_hashed.
  4. Schema default (unset).
Type
string
Default
null
Since
v0.0.20
sh
WS_AUTH_PASSWORD_HASHED="$argon2i$v=19$m=4096,t=3,p=1$...$..."
Read More →

WS_AUTH_SESSION_MAX_TTL

Longest a password session lasts (seconds) from sign-in, however active.

A password session renews while in use, so without a cap a copied session cookie that stays in use never expires. Past this many seconds after sign-in the password is asked for again. A missing or malformed value falls back to the default.

Type
integer
Default
604800
Since
vnext
Read More →

WS_AUTH_SESSION_TTL

Lifetime (seconds) of an authenticated web session.

A password session renews on each authenticated request, so an actively-used session never drops, up to WS_AUTH_SESSION_MAX_TTL after sign-in. An OIDC session ends this long after sign-in and signs in again silently while the IdP session lasts. A missing or malformed value falls back to the default.

Type
integer
Default
86400
Since
v0.5.0
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
Delimiter
space
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
Delimiter
space
Since
v0.0.22
sh
WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS="http://corp.com/ca.pem \
                                          https://untrusted.com/root.crt"
Read More →

Claude ​

WS_CLAUDE_STATUSLINE_DISABLE

Disables the Claude Code statusline.
Type
boolean
Default
false
Since
v0.2.0
Read More →

WS_CLAUDE_STATUSLINE_HIDE_CONTEXT_BAR

Hides the context usage bar in the Claude statusline.
Type
boolean
Default
false
Since
v0.2.0
Read More →

WS_CLAUDE_STATUSLINE_HIDE_GIT

Hides git branch and status in the Claude statusline.
Type
boolean
Default
false
Since
v0.2.0
Read More →

WS_CLAUDE_STATUSLINE_HIDE_LINES_CHANGED

Hides lines added/removed in the Claude statusline.
Type
boolean
Default
false
Since
v0.2.0
Read More →

WS_CLAUDE_STATUSLINE_HIDE_MODEL

Hides the model name in the Claude statusline.
Type
boolean
Default
false
Since
v0.2.0
Read More →

WS_CLAUDE_STATUSLINE_SCRIPT

Path to the statusline script.
Type
path
Default
/etc/claude-code/statusline.zsh
Since
v0.2.0
Read More →

WS_CLAUDE_STATUSLINE_SHELL

Shell used to execute the statusline script.
Type
string
Default
zsh
Since
v0.2.0
Read More →

Cloudflared ​

WS_CLOUDFLARED_TUNNEL_TOKEN

Cloudflare tunnel connector token.

Connector credential for a remotely-managed (dashboard or API created) Cloudflare named tunnel. When set, and the opt-in cloudflared feature is installed, the tunnel starts automatically under s6 supervision (cloudflared tunnel --no-autoupdate run) and restarts on death. When unset, the tunnel stays dormant. Never baked or shared, provide it per deployment via the resolution chain below.

Resolution chain:

  1. Env literal: WS_CLOUDFLARED_TUNNEL_TOKEN=....
  2. file: env value: WS_CLOUDFLARED_TUNNEL_TOKEN=file:/path/to/token.
  3. Convention default: file mounted at /run/secrets/workspace/cloudflared/tunnel_token.
  4. Schema default (unset).
Type
string
Default
null
Since
v0.4.0
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
Delimiter
space
Since
v0.0.20
sh
WS_EDITOR_ADDITIONAL_VS_EXTENSIONS="dbaeumer.vscode-eslint \
                                    esbenp.prettier-vscode"
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_DISABLE_FILE_DOWNLOADS

Disables downloading files from the editor to the browser.

Hides the Explorer's Download… action and refuses ws editor download. It does not stop the editor from serving workspace files to the browser, so it is not a data-loss control.

Type
boolean
Default
false
Since
v0.5.0

WS_EDITOR_DISABLE_FILE_UPLOADS

Disables uploading files from the browser into the editor.
Type
boolean
Default
false
Since
v0.5.0

WS_EDITOR_LOGOUT_URL

Overrides the URL the in-IDE sign-out action navigates to.

The editor shows a Sign out action (Command Palette and Home menu) only when a logout URL is known. It is derived automatically and needs no configuration:

  • WS_AUTH_MODE=oidc: /logout, which also ends the IdP session when the IdP advertises an end_session_endpoint.
  • WS_AUTH_MODE=password: /logout, but only when a password is actually configured, an auth-less workspace shows no sign-out action rather than a dead one.

Set this to override the derived value. A relative path is resolved by the browser against the current origin, so it keeps working behind a proxy domain or base path; an absolute URL is used verbatim.

Type
string
Default
null
Since
v0.5.0
sh
WS_EDITOR_LOGOUT_URL="/logout"
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

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.

Type
string
Default
null
Since
v0.1.2
sh
WS_EDITOR_SETTINGS_MERGE="{"editor.fontSize": 16, "[python]": \
                          {"editor.tabSize": 4}}"
Read More →

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.

Type
path
Default
null
Since
v0.1.2
sh
WS_EDITOR_SETTINGS_MERGE_FILE="/workspace/.settings-override.json"
Read More →

WS_EDITOR_SETTINGS_OVERRIDE

JSON object to completely replace VSCode settings.json.

WARNING: Removes all of Kloud Workspace's default user settings, including the theme and fonts.

Use WS_EDITOR_SETTINGS_MERGE for partial updates.

Type
string
Default
null
Since
v0.1.2
sh
WS_EDITOR_SETTINGS_OVERRIDE="{"editor.fontSize": 16}"
Read More →

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.

Type
path
Default
null
Since
v0.1.2
sh
WS_EDITOR_SETTINGS_OVERRIDE_FILE="/workspace/.settings.json"
Read More →

WS_EDITOR_TRUSTED_DOMAINS

Comma-separated list of trusted domains that bypass link confirmation prompts.

When a link matching one of these domains is clicked in the editor, it opens directly in the browser without prompting for user confirmation.

Accepts a comma-delimited list of domain URL patterns.

The editor ships with https://open-vsx.org trusted by default (via product.json); entries from this variable are added on top.

Type
string
Default
null
Delimiter
comma
Since
v0.2.0
sh
WS_EDITOR_TRUSTED_DOMAINS=" \
                           https://github.com,https://stackoverflow.com"

Features ​

WS_FEATURES_ADDITIONAL_FEATURES

Installs additional features when a new container starts.

Accepts a space-delimited list of features.

Type
string
Default
null
Delimiter
space
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
path
Default
/usr/share/workspace/features.d
Since
v0.0.20
Read More →

WS_FEATURES_STORE_ALLOW_FALLBACK

Allow upstream Debian fallback on older-drift detection.

When the ws-feature-store serves a package strictly older than what the workspace already has installed, or cannot satisfy the install, opt into temporarily re-enabling debian.sources for this install. Only effective when WS_APT_DISABLE_REPOS covers debian. In air-gapped deployments (no path to deb.debian.org) this knob has no effect, the install proceeds via the per-install Pin fragment regardless.

Type
boolean
Default
false
Since
v0.3.0
Read More →

WS_FEATURES_STORE_URL

URL of a ws-feature-store instance used as a local mirror.

When set, workspace features that require third-party APT repositories (e.g. dotnet, gcloud, php, etc.) will fetch packages from this URL instead of enabling individual vendor repositories. Features that install static binaries download them from the store's artifacts as well.

Type
string
Default
null
Since
v0.2.0
sh
WS_FEATURES_STORE_URL="http://feature-store.local:8080"
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 set the cache timeout to 1 year (31536000 seconds).

Type
integer
Default
3600
Read More →

Helm ​

WS_HELM_PRELOAD_CACHE

Runs helm repo update when a new container starts.
Type
boolean
Default
false
Since
v0.0.20
Read More →

Logging ​

WS_LOGGING_CLOUDFLARED_FILE

Log file for the Cloudflared tunnel.
Type
string
Default
cloudflared.log
Since
v0.4.0

WS_LOGGING_DIR

Base directory for all workspace logs.
Type
path
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_DOCKER_FILE

Log file for the in-container Docker daemon.
Type
string
Default
dockerd.log
Since
v0.3.0

WS_LOGGING_MAIN_FILE

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

WS_LOGGING_METRICS_FILE

Log file for the metrics exporter.
Type
string
Default
metrics.log
Since
v0.3.0

Marketplace ​

WS_MARKETPLACE_CONTROL_URL

URL of the gallery's extension control manifest (controlUrl).

The control manifest lists malicious and deprecated extensions. The baked Open VSX gallery has none, so leave this unset unless your gallery serves one.

Type
string
Default
null
Since
v0.5.0
sh
WS_MARKETPLACE_CONTROL_URL=" \
                            https://vsx.example.com/vscode/control"
Read More →

WS_MARKETPLACE_EXTENSION_URL_TEMPLATE

URL template for a single extension's latest metadata (extensionUrlTemplate).
Type
string
Default
null
Since
v0.5.0
sh
WS_MARKETPLACE_EXTENSION_URL_TEMPLATE=" \
                                       https://vsx.example.com/vscode/gallery/{publisher}/{name}/latest"
Read More →
Replaces the whole extension gallery with a JSON object (extensionsGallery).

Use this for a gallery whose layout differs from Open VSX. The object replaces the baked Open VSX gallery; any per-key WS_MARKETPLACE_*_URL variable that is also set overrides its key. Malformed JSON is ignored and the baked gallery is kept.

Type
string
Default
null
Since
v0.5.0
sh
WS_MARKETPLACE_GALLERY="{ "serviceUrl": \
                        "https://vsx.example.com/vscode/gallery", \
                        "itemUrl": \
                        "https://vsx.example.com/vscode/item" }"
Read More →

WS_MARKETPLACE_ITEM_URL

URL of the extension details page (itemUrl).
Type
string
Default
null
Since
v0.5.0
sh
WS_MARKETPLACE_ITEM_URL="https://vsx.example.com/vscode/item"
Read More →

WS_MARKETPLACE_RESOURCE_URL_TEMPLATE

URL template for an extension's web resources (resourceUrlTemplate).
Type
string
Default
null
Since
v0.5.0
sh
WS_MARKETPLACE_RESOURCE_URL_TEMPLATE=" \
                                      https://vsx.example.com/vscode/asset/{publisher}/{name}/{version}/Microsoft.VisualStudio.Code.WebResources/{path}"
Read More →

WS_MARKETPLACE_SERVICE_URL

URL of the gallery API used to search and install extensions (serviceUrl).
Type
string
Default
null
Since
v0.5.0
sh
WS_MARKETPLACE_SERVICE_URL=" \
                            https://vsx.example.com/vscode/gallery"
Read More →

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

Type
string
Default
*
Delimiter
comma
Since
v0.1.2
sh
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).

Type
boolean
Default
false
Since
v0.1.2

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.

Type
integer
Default
9100
Since
v0.1.2

npm ​

WS_NPM_ADDITIONAL_PACKAGES

Additional global npm packages installed during startup.

Accepts a space-delimited package list. Each entry is a full npm spec, so @version pins (prettier@3.2.5) and scoped packages (@angular/cli) are supported.

Type
string
Default
null
Delimiter
space
Since
v0.4.0
sh
WS_NPM_ADDITIONAL_PACKAGES="prettier@3.2.5 @angular/cli"

pip ​

WS_PIP_ADDITIONAL_PACKAGES

Additional global Python packages installed during startup.

Accepts a space-delimited package list. Each entry is a full pip spec, so == pins (httpx==0.27.0) and extras (rich[jupyter]) are supported. For installable CLI tools prefer WS_UV_ADDITIONAL_TOOLS.

Type
string
Default
null
Delimiter
space
Since
v0.4.0
sh
WS_PIP_ADDITIONAL_PACKAGES="httpx==0.27.0 rich"
Read More →

Secrets ​

WS_SECRETS_MASTER_KEY

Master encryption key for seed secrets.

Used to encrypt and decrypt secrets projected by the seed engine. Can be provided as:

  • A base64-encoded string.
  • A plaintext string.

Resolution chain:

  1. CLI --master flag (if provided).
  2. Env literal: WS_SECRETS_MASTER_KEY=<key>.
  3. file: env value: WS_SECRETS_MASTER_KEY=file:/path/to/key.
  4. Convention default: file mounted at /run/secrets/workspace/secrets/master_key.
  5. Schema default (unset).
Type
string
Default
null
Since
v0.1.1
sh
WS_SECRETS_MASTER_KEY="dGhpcyBpcyBhIHNlY3JldCBrZXkgZXhhbXBsZQ=="

Seed ​

WS_SEED_SOURCE

Directory projected onto the filesystem at startup.

Bare files mirror the filesystem tree; a hidden .seed.yaml manifest overlays declarative behaviors (merge/append/prepend/block, templating, whole-file secrets). Projected when a new container starts, not on restarts; empty or absent is a no-op.

Type
path
Default
~/.ws/seed.d
Since
v0.5.0
sh
WS_SEED_SOURCE="/mnt/seed"
Read More →

Server ​

WS_SERVER_HOST

Address on which the web server listens.

Binds all interfaces by default so Docker-published traffic reaches the editor. Set to 127.0.0.1 to restrict the listener to loopback when a front proxy on the same host terminates external traffic.

Type
string
Default
0.0.0.0
Since
v0.5.0

WS_SERVER_PORT

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

WS_SERVER_PROXY_ALLOW_PUBLIC

Allows forwarded ports to be shared without sign-in.

When true, ws-cli port share <port> and the Ports view's Port Visibility menu can make a forwarded port public: it then answers on <port>.<suffix> of WS_SERVER_PROXY_DOMAIN without the workspace sign-in, for as long as the share is held.

/proxy/<port>/ and /absproxy/<port>/ always need sign-in. A restart makes every port private again.

Type
boolean
Default
false
Since
vnext
sh
WS_SERVER_PROXY_ALLOW_PUBLIC="true"
Read More →

WS_SERVER_PROXY_DOMAIN

Domain suffix used to expose server's forwarded ports.

Accepts either a single domain suffix or multiple space-delimited suffixes. Each suffix is exposed as {{port}}.<suffix>; the {{port}}. prefix is added automatically unless the suffix already contains a {{port}} placeholder (e.g. {{port}}-project.ws.dev). A leading *. is ignored, so *.ws.dev is the same as ws.dev. > Multiple domain support was added in v0.0.22.

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

WS_SERVER_ROOT

Root directory for the workspace.

This should only be overridden in extreme cases.

Type
path
Default
/workspace
Since
v0.0.20

WS_SERVER_SSL_CERT

Inline PEM or file: path for the server certificate.

Accepts either:

  • Literal certificate body starting with -----BEGIN CERTIFICATE----- (newline characters may be provided as \n escapes).
  • A file: env value: WS_SERVER_SSL_CERT=file:/path/to/server.crt.

Resolution chain:

  1. Env literal (inline PEM).
  2. file: env value (reads the file at the given path).
  3. Convention default: file mounted at /run/secrets/workspace/server/ssl_cert.
  4. Schema default (unset).

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
path
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
null
Since
v0.0.21
sh
WS_SERVER_SSL_HOSTS="ws.dev *.ws.dev"
Read More →

WS_SERVER_SSL_KEY

Inline PEM or file: path for the private key.

Accepts either:

  • Literal key body starting with -----BEGIN PRIVATE KEY----- (newline characters may be provided as \n escapes).
  • A file: env value: WS_SERVER_SSL_KEY=file:/path/to/server.key.

Resolution chain:

  1. Env literal (inline PEM).
  2. file: env value (reads the file at the given path).
  3. Convention default: file mounted at /run/secrets/workspace/server/ssl_key.
  4. Schema default (unset).
Type
path
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.

When true, the autoloader stops at the first failing startup or entrypoint and the container startup 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 →

uv ​

WS_UV_ADDITIONAL_TOOLS

Additional global Python CLI tools installed during startup.

Accepts a space-delimited package list. Each entry is a full uv spec, so == pins (poetry==1.8.0) are supported. Installs global CLI tools only, for importable libraries use WS_PIP_ADDITIONAL_PACKAGES.

Type
string
Default
null
Delimiter
space
Since
v0.4.0
sh
WS_UV_ADDITIONAL_TOOLS="ruff poetry==1.8.0"
Read More →

Zsh ​

WS_ZSH_ADDITIONAL_PLUGINS

Loads additional oh-my-zsh plugins.

Accepts a space-delimited list of plugin names appended to the built-in oh-my-zsh plugin set.

Type
string
Default
null
Delimiter
space
Since
v0.0.20
sh
WS_ZSH_ADDITIONAL_PLUGINS="php"

WS_ZSH_FZF_HISTORY_ARGS

Default arguments passed to fzf for history search.
Type
string
Default
+s +m -x -e --preview-window=hidden
Since
v0.1.1
Read More →

WS_ZSH_FZF_HISTORY_BIND

Key binding that triggers fzf history search.
Type
string
Default
^r
Since
v0.1.1
Read More →
Includes ISO 8601 date timestamps in search results.
Type
boolean
Default
false
Since
v0.1.1
Read More →

WS_ZSH_FZF_HISTORY_END_OF_LINE

Moves cursor to end-of-line after selecting a history entry.
Type
string
Default
null
Since
v0.1.1
Read More →

WS_ZSH_FZF_HISTORY_EVENT_NUMBERS

Shows event numbers in history search results.
Type
boolean
Default
false
Since
v0.1.1
Read More →

WS_ZSH_FZF_HISTORY_EXTRA_ARGS

Additional arguments appended to the default fzf arguments.
Type
string
Default
null
Since
v0.1.1
Read More →

WS_ZSH_FZF_HISTORY_QUERY_PREFIX

Prefix prepended to the fzf query when the buffer is non-empty.
Type
string
Default
null
Since
v0.1.1
Read More →

WS_ZSH_FZF_HISTORY_REMOVE_DUPLICATES

Removes duplicate entries from history search results.
Type
boolean
Default
true
Since
v0.1.1
Read More →

WS_ZSH_PLUGINS

Enables built-in oh-my-zsh plugins.

Accepts a space-delimited list of plugin names. Replaces the default plugin set; use WS_ZSH_ADDITIONAL_PLUGINS to extend it instead.

Type
string
Default
1password auto-venv docker encode64 fzf-history git golang helm kubectl npm python pip ssh-agent zsh-autosuggestions
Delimiter
space
sh
WS_ZSH_PLUGINS="kubectl npm python pip"

Deprecated ​

NameReplacementSinceRemoval
WS_APT_UPDATE_REPOSWS_APT_UPDATE_CACHEv0.0.20v0.1.0
WS_AUTH_GITHUB_TOKEN_FILEWS_AUTH_GITHUB_TOKENv0.3.0v0.3.0
WS_AUTH_OIDC_ALLOWED_GROUPSUse WS_AUTH_OIDC_ALLOWED_EMAILS; the workspace refuses to start while this is set.v0.6.0v0.6.0
WS_AUTH_OIDC_FORBIDDEN_MESSAGEThe access-denied page text is fixed.v0.6.0v0.6.0
WS_AUTH_OIDC_SESSION_REFRESHSessions end after WS_AUTH_SESSION_TTL; signing in again is a silent IdP round trip.v0.6.0v0.6.0
WS_AUTH_PASSWORD_FILEWS_AUTH_PASSWORDv0.3.0v0.3.0
WS_AUTH_PASSWORD_HASHED_FILEWS_AUTH_PASSWORD_HASHEDv0.3.0v0.3.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_EDITOR_ADDITIONAL_VS_EXTENSIONS_DIRplace .vsix files in ~/.ws/extensions/ insteadv0.2.0v0.3.0
WS_EXTRA_CA_CERT_ENDPOINTSWS_CA_ADDITIONAL_CERT_ENDPOINTSv0.0.20v0.1.0
WS_EXTRA_CA_CERT_INSECUREWS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTSv0.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_DIRplace .vsix files in ~/.ws/extensions/ insteadv0.0.20v0.1.0
WS_LOGGING_AUTH_PROXY_FILESign-in events are in the main workspace log.v0.6.0v0.6.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_SECRETS_MASTER_KEY_FILEWS_SECRETS_MASTER_KEYv0.3.0v0.3.0
WS_SECRETS_VAULTThe secrets vault has been removed. Declare secrets in the seed manifest at <seed.source>/.seed.yaml (the secrets: map and secret: true entries); see /tools/seed.v0.3.0v0.3.0
WS_SERVER_AUTH_PROXY_PORTPublish WS_SERVER_PORT instead; the editor signs users in itself.v0.6.0v0.6.0
WS_SERVER_SSL_ROOTTLS material is no longer persisted to disk. The self-signed certificate and key are minted in memory by the editor and served directly; there is no on-disk SSL root to configure.v0.3.0v0.5.0
WS_ZSH_EXTRA_PLUGINSWS_ZSH_ADDITIONAL_PLUGINSv0.0.20v0.1.0

Global Variables ​

ENVDescriptionRead More
EDITORDefault terminal editor (default: code --wait --reuse-window)
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