Configuration
💡 TIP
For VS Code editor settings (JSON-based), see Editor Settings.
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:
docker run \
-e WS_METRICS_ENABLE=true \
-e TZ=Europe/London \
ghcr.io/kloudkit/workspace:v0.6.0To keep them in a file, write one NAME=value per line, such as this workspace.env:
WS_METRICS_ENABLE=true
TZ=Europe/LondonThen pass the file with --env-file:
docker run --env-file workspace.env ghcr.io/kloudkit/workspace:v0.6.0Docker 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 andgh.WS_AUTH_OIDC_CLIENT_SECRET: OIDC client secret. Required whenWS_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 orfile:path for the server certificate.WS_SERVER_SSL_KEY: Inline PEM orfile:path for the private key.
Each value comes from the first of these that applies:
- Literal value:
WS_X=value. file:prefix:WS_X=file:/pathreads the file (the editor trims surrounding whitespace;ws-clistrips one trailing newline).- Mounted file: mount a file at
/run/secrets/workspace/<group>/<property>and leave the variable unset. - Default: typically unset.
docker run \
-e WS_AUTH_PASSWORD=super_duper_secret \
ghcr.io/kloudkit/workspace:v0.6.0docker 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.0volumes:
- 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.
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.
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.
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). - A boolean
trueor*value to disable all repositories.
WS_APT_DISABLE_REPOS="debian additional"
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
trueor*value to disable all restrictions.
WS_APT_DISABLE_RESTRICTIONS="x11 mail"
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.
WS_APT_OVERRIDE_RESTRICTIONS="true"
WS_APT_UPDATE_CACHE
RunsRead More →apt-get updatewhen a new container starts, beforeWS_APT_ADDITIONAL_PACKAGESinstalls.
Auth
WS_AUTH_DISABLE_SUDO
Disables password-less sudo.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:
- Env literal:
WS_AUTH_GITHUB_TOKEN=ghp_.... file:env value:WS_AUTH_GITHUB_TOKEN=file:/path/to/token.- Convention default: file mounted at
/run/secrets/workspace/auth/github_token. - Schema default (unset).
WS_AUTH_GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
WS_AUTH_MODE
Web authentication mode, eitherpasswordoroidc.
password(default): the editor's built-in password login viaWS_AUTH_PASSWORD/WS_AUTH_PASSWORD_HASHED.oidc: the editor signs users in with OpenID Connect onWS_SERVER_PORT. RequiresWS_AUTH_OIDC_ISSUER,WS_AUTH_OIDC_CLIENT_ID,WS_AUTH_OIDC_CLIENT_SECRETandWS_AUTH_OIDC_ALLOWED_EMAILS, and refuses to start without them or alongside a password.
Any other value is treated as password.
WS_AUTH_MODE="oidc"
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.
WS_AUTH_OIDC_ALLOWED_EMAILS="alice@corp.com *@team.corp.com"
WS_AUTH_OIDC_CLIENT_ID
OIDC client ID. Required when WS_AUTH_MODE=oidc.WS_AUTH_OIDC_CLIENT_ID="workspace"
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:
- Env literal:
WS_AUTH_OIDC_CLIENT_SECRET=.... file:env value:WS_AUTH_OIDC_CLIENT_SECRET=file:/path/to/secret.- Convention default: file mounted at
/run/secrets/workspace/auth/oidc_client_secret. - Schema default (unset).
WS_AUTH_OIDC_COOKIE_SECRET
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:
- Env literal:
WS_AUTH_OIDC_COOKIE_SECRET=.... file:env value:WS_AUTH_OIDC_COOKIE_SECRET=file:/path/to/secret.- Convention default: file mounted at
/run/secrets/workspace/auth/oidc_cookie_secret. - Generated and persisted (unset).
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.
WS_AUTH_OIDC_ISSUER="https://idp.example.com"
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.
WS_AUTH_OIDC_REDIRECT_URL="https://ws.example.com/oauth2/callback \
https://ws.other.dev/oauth2/callback"
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.
WS_AUTH_OIDC_SCOPES="openid email profile"
WS_AUTH_PASSWORD
Plaintext password for web login.
Use only in ephemeral or local environments, never in shared or production deployments.
Resolution chain:
- Env literal:
WS_AUTH_PASSWORD=mySecret. file:env value:WS_AUTH_PASSWORD=file:/path/to/password.- Convention default: file mounted at
/run/secrets/workspace/auth/password. - Schema default (unset).
WS_AUTH_PASSWORD_HASHED takes precedence over this when both
resolve to a non-empty value.
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.
Resolution chain:
- Env literal:
WS_AUTH_PASSWORD_HASHED=<argon2-hash>. file:env value:WS_AUTH_PASSWORD_HASHED=file:/path/to/hash.- Convention default: file mounted at
/run/secrets/workspace/auth/password_hashed. - Schema default (unset).
WS_AUTH_PASSWORD_HASHED="$argon2i$v=19$m=4096,t=3,p=1$...$..."
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.
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.
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"
Claude
WS_CLAUDE_STATUSLINE_DISABLE
Disables the Claude Code statusline.Read More →
WS_CLAUDE_STATUSLINE_HIDE_CONTEXT_BAR
Hides the context usage bar in the Claude statusline.Read More →
WS_CLAUDE_STATUSLINE_HIDE_GIT
Hides git branch and status in the Claude statusline.Read More →
WS_CLAUDE_STATUSLINE_HIDE_LINES_CHANGED
Hides lines added/removed in the Claude statusline.Read More →
WS_CLAUDE_STATUSLINE_HIDE_MODEL
Hides the model name in the Claude statusline.Read More →
WS_CLAUDE_STATUSLINE_SCRIPT
Path to the statusline script.Read More →
WS_CLAUDE_STATUSLINE_SHELL
Shell used to execute the statusline script.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:
- Env literal:
WS_CLOUDFLARED_TUNNEL_TOKEN=.... file:env value:WS_CLOUDFLARED_TUNNEL_TOKEN=file:/path/to/token.- Convention default: file mounted at
/run/secrets/workspace/cloudflared/tunnel_token. - Schema default (unset).
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_COMMENTS_DISABLE_FONT
Disables the custom font used for code comments.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.
WS_EDITOR_DISABLE_FILE_UPLOADS
Disables uploading files from the browser into the editor.
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 anend_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.
WS_EDITOR_LOGOUT_URL="/logout"
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 of Kloud Workspace's default user settings, including the theme and fonts.
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"
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.
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.
WS_FEATURES_ADDITIONAL_FEATURES="dotnet jupyter"
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_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.
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.
WS_FEATURES_STORE_URL="http://feature-store.local:8080"
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 set the cache timeout to 1
year (31536000 seconds).
Helm
WS_HELM_PRELOAD_CACHE
Runs helm repo update when a new container starts.Read More →Logging
WS_LOGGING_CLOUDFLARED_FILE
Log file for the Cloudflared tunnel.
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_DOCKER_FILE
Log file for the in-container Docker daemon.
WS_LOGGING_MAIN_FILE
Combined log file forstdoutandstderr.
WS_LOGGING_METRICS_FILE
Log file for the metrics exporter.
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.
WS_MARKETPLACE_CONTROL_URL=" \
https://vsx.example.com/vscode/control"
WS_MARKETPLACE_EXTENSION_URL_TEMPLATE
URL template for a single extension's latest metadata (extensionUrlTemplate).WS_MARKETPLACE_EXTENSION_URL_TEMPLATE=" \
https://vsx.example.com/vscode/gallery/{publisher}/{name}/latest"
WS_MARKETPLACE_GALLERY
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.
WS_MARKETPLACE_GALLERY="{ "serviceUrl": \
"https://vsx.example.com/vscode/gallery", \
"itemUrl": \
"https://vsx.example.com/vscode/item" }"
WS_MARKETPLACE_ITEM_URL
URL of the extension details page (itemUrl).WS_MARKETPLACE_ITEM_URL="https://vsx.example.com/vscode/item"
WS_MARKETPLACE_RESOURCE_URL_TEMPLATE
URL template for an extension's web resources (resourceUrlTemplate).WS_MARKETPLACE_RESOURCE_URL_TEMPLATE=" \
https://vsx.example.com/vscode/asset/{publisher}/{name}/{version}/Microsoft.VisualStudio.Code.WebResources/{path}"
WS_MARKETPLACE_SERVICE_URL
URL of the gallery API used to search and install extensions (serviceUrl).WS_MARKETPLACE_SERVICE_URL=" \
https://vsx.example.com/vscode/gallery"
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.
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.
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.
WS_PIP_ADDITIONAL_PACKAGES="httpx==0.27.0 rich"
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:
- CLI
--masterflag (if provided). - Env literal:
WS_SECRETS_MASTER_KEY=<key>. file:env value:WS_SECRETS_MASTER_KEY=file:/path/to/key.- Convention default: file mounted at
/run/secrets/workspace/secrets/master_key. - Schema default (unset).
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.
WS_SEED_SOURCE="/mnt/seed"
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.
WS_SERVER_PORT
Port on which the web server listens.
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.
WS_SERVER_PROXY_ALLOW_PUBLIC="true"
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.
WS_SERVER_PROXY_DOMAIN="ws.dev *.local.ws.dev"
WS_SERVER_ROOT
Root directory for the workspace.
This should only be overridden in extreme cases.
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\nescapes). - A
file:env value:WS_SERVER_SSL_CERT=file:/path/to/server.crt.
Resolution chain:
- Env literal (inline PEM).
file:env value (reads the file at the given path).- Convention default: file mounted at
/run/secrets/workspace/server/ssl_cert. - 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).
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
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\nescapes). - A
file:env value:WS_SERVER_SSL_KEY=file:/path/to/server.key.
Resolution chain:
- Env literal (inline PEM).
file:env value (reads the file at the given path).- Convention default: file mounted at
/run/secrets/workspace/server/ssl_key. - Schema default (unset).
WS_SERVER_SSL_KEY="/etc/workspace/ssl/server.key"
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.
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 →
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.
WS_UV_ADDITIONAL_TOOLS="ruff poetry==1.8.0"
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.
WS_ZSH_ADDITIONAL_PLUGINS="php"
WS_ZSH_FZF_HISTORY_ARGS
Default arguments passed to fzf for history search.Read More →WS_ZSH_FZF_HISTORY_BIND
Key binding that triggers fzf history search.Read More →
WS_ZSH_FZF_HISTORY_DATES_IN_SEARCH
Includes ISO 8601 date timestamps in search results.Read More →
WS_ZSH_FZF_HISTORY_END_OF_LINE
Moves cursor to end-of-line after selecting a history entry.Read More →
WS_ZSH_FZF_HISTORY_EVENT_NUMBERS
Shows event numbers in history search results.Read More →
WS_ZSH_FZF_HISTORY_EXTRA_ARGS
Additional arguments appended to the default fzf arguments.Read More →WS_ZSH_FZF_HISTORY_QUERY_PREFIX
Prefix prepended to the fzf query when the buffer is non-empty.Read More →
WS_ZSH_FZF_HISTORY_REMOVE_DUPLICATES
Removes duplicate entries from history search results.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.
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_AUTH_GITHUB_TOKEN_FILE | WS_AUTH_GITHUB_TOKEN | v0.3.0 | v0.3.0 |
WS_AUTH_OIDC_ALLOWED_GROUPS | Use WS_AUTH_OIDC_ALLOWED_EMAILS; the workspace refuses to start while this is set. | v0.6.0 | v0.6.0 |
WS_AUTH_OIDC_FORBIDDEN_MESSAGE | The access-denied page text is fixed. | v0.6.0 | v0.6.0 |
WS_AUTH_OIDC_SESSION_REFRESH | Sessions end after WS_AUTH_SESSION_TTL; signing in again is a silent IdP round trip. | v0.6.0 | v0.6.0 |
WS_AUTH_PASSWORD_FILE | WS_AUTH_PASSWORD | v0.3.0 | v0.3.0 |
WS_AUTH_PASSWORD_HASHED_FILE | WS_AUTH_PASSWORD_HASHED | v0.3.0 | v0.3.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_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 | v0.0.20 | v0.1.0 |
WS_EXTRA_CA_CERT_INSECURE | WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS | 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 | place .vsix files in ~/.ws/extensions/ instead | v0.0.20 | v0.1.0 |
WS_LOGGING_AUTH_PROXY_FILE | Sign-in events are in the main workspace log. | v0.6.0 | v0.6.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_SECRETS_MASTER_KEY_FILE | 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.source>/.seed.yaml (the secrets: map and secret: true entries); see /tools/seed. | v0.3.0 | v0.3.0 |
WS_SERVER_AUTH_PROXY_PORT | Publish WS_SERVER_PORT instead; the editor signs users in itself. | v0.6.0 | v0.6.0 |
WS_SERVER_SSL_ROOT | TLS 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.0 | v0.5.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 --wait --reuse-window) | |
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 |