Kloud Workspace

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

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

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

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

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, trixie).
A boolean true or * value to disable all repositories.

Type: string
Default: null
Delimiter: space
Since: v0.0.22

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, language-pack, 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

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

WS_APT_OVERRIDE_RESTRICTIONS="true"

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

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

Type: string
Default: null
Since: v0.3.0

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. Unchanged behaviour.
oidc: an in-workspace oauth2-proxy listens on WS_SERVER_AUTH_PROXY_PORT and authenticates every request against WS_AUTH_OIDC_ISSUER before forwarding to the editor, which binds loopback-only on WS_SERVER_PORT. Requires WS_AUTH_OIDC_ISSUER, WS_AUTH_OIDC_CLIENT_ID and WS_AUTH_OIDC_CLIENT_SECRET. Publish the proxy port.

Any other value is treated as password.

Type: string
Default: password
Since: v0.4.0

WS_AUTH_MODE="oidc"

Read More →

`WS_AUTH_OIDC_ALLOWED_EMAILS`

Restrict OIDC login to an explicit email allowlist.

A space-delimited list. When unset, any email the IdP authenticates is allowed. oidc assumes a single-user workspace whose authorization is enforced upstream. Only used when WS_AUTH_MODE=oidc.

Type: string
Default: null
Delimiter: space
Since: v0.4.0

WS_AUTH_OIDC_ALLOWED_EMAILS="[email protected] [email protected]"

Read More →

`WS_AUTH_OIDC_ALLOWED_GROUPS`

Restrict OIDC login to members of these IdP groups.

A space-delimited list mapped to oauth2-proxy --allowed-group. Only used when WS_AUTH_MODE=oidc.

Type: string
Default: null
Delimiter: space
Since: v0.4.0

WS_AUTH_OIDC_ALLOWED_GROUPS="engineering platform"

Read More →

`WS_AUTH_OIDC_CLIENT_ID`

OIDC client ID. Required when WS_AUTH_MODE=oidc.

Type: string
Default: null
Since: v0.4.0

WS_AUTH_OIDC_CLIENT_ID="workspace"

Read More →

`WS_AUTH_OIDC_CLIENT_SECRET`

OIDC client secret. Required when WS_AUTH_MODE=oidc.

Required for oidc mode. oauth2-proxy authenticates to the IdP as a confidential client and refuses to start without it. PKCE (--code-challenge-method=S256) is layered on top as defence in depth. Register the workspace as a confidential client and supply its secret here. Never baked or shared, provide it per deployment via the resolution chain below.

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

Type: string
Default: null
Since: v0.4.0

Read More →

`WS_AUTH_OIDC_COOKIE_SECRET`

Secret that signs and encrypts the oauth2-proxy session cookie.

A 16, 24, or 32-byte secret (raw or base64). When unset it is generated once and persisted under the workspace home so sessions survive restarts and redeploys that reattach the volume. For multi-replica or volume-less deployments, set this to a shared value so every instance signs cookies identically. 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).

Type: string
Default: null
Since: v0.4.0

Read More →

`WS_AUTH_OIDC_FORBIDDEN_MESSAGE`

Custom guidance shown on the OIDC not-authorized (403) page.

Replaces the default guidance on the 403 error page shown when an authenticated user is denied (failed group/email allowlist). When unset, a default "contact your administrator" message is shown. Only used when WS_AUTH_MODE=oidc.

Type: string
Default: Contact your administrator to request access; retrying will not help.
Since: v0.4.0

WS_AUTH_OIDC_FORBIDDEN_MESSAGE="Contact the platform team to \
                                request access."

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

WS_AUTH_OIDC_ISSUER="https://idp.example.com"

Read More →

`WS_AUTH_OIDC_REDIRECT_URL`

Explicit OAuth redirect URL override.

When unset, oauth2-proxy derives the callback from the incoming request host as https://<host>/oauth2/callback. Set this when the externally-visible host differs from what oauth2-proxy can infer (e.g. behind a terminator that rewrites the Host header). The in-IDE logout action also uses this value to build the sign-out URL. Only used when WS_AUTH_MODE=oidc.

Type: string
Default: null
Since: v0.4.0

WS_AUTH_OIDC_REDIRECT_URL="https://ws.example.com/oauth2/callback"

Read More →

`WS_AUTH_OIDC_SCOPES`

OAuth scopes requested at login.

A space-delimited scope list requested from the IdP. Add groups when you use WS_AUTH_OIDC_ALLOWED_GROUPS and your IdP exposes a groups scope. Only used when WS_AUTH_MODE=oidc.

Type: string
Default: openid email profile
Delimiter: space
Since: v0.4.0

WS_AUTH_OIDC_SCOPES="openid email profile groups"

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:

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.

Type: string
Default: null
Since: v0.0.20

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:

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

Type: string
Default: null
Since: v0.0.20

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
Delimiter: space
Since: v0.0.20

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

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:

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

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

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_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

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

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 default workspace settings.

Use WS_EDITOR_SETTINGS_MERGE for partial updates.

Type: string
Default: null
Since: v0.1.2

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

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

WS_EDITOR_TRUSTED_DOMAINS=" \
                           https://github.com,https://stackoverflow.com"

Features

`WS_FEATURES_ADDITIONAL_FEATURES`

Installs additional feature at startup.

Accepts a space-delimited list of features.

Type: string
Default: null
Delimiter: space
Since: v0.0.20

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, opt into temporarily re-enabling debian.sources for this install. Only effective when WS_APT_DISABLE_REPOS does NOT cover 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. cloudflared, gcloud, gh, etc.) will fetch packages from this URL instead of enabling individual vendor repositories.

Type: string
Default: null
Since: v0.2.0

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

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`

Restores the Helm repo cache.

Type: boolean
Default: false
Since: v0.0.20

Read More →

Logging

`WS_LOGGING_AUTH_PROXY_FILE`

Log file for the OIDC authentication proxy.

Type: string
Default: auth-proxy.log
Since: v0.4.0

`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

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

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 ([email protected]) and scoped packages (@angular/cli) are supported.

Type: string
Default: null
Delimiter: space
Since: v0.4.0

WS_NPM_ADDITIONAL_PACKAGES="[email protected] @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

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:

CLI --master flag (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).

Type: string
Default: null
Since: v0.1.1

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). Re-projected on every boot; empty or absent is a no-op.

Type: path
Default: ~/.ws/seed.d
Since: vnext

WS_SEED_SOURCE="/mnt/seed"

Read More →

Server

`WS_SERVER_AUTH_PROXY_PORT`

Port the OIDC auth proxy listens on when WS_AUTH_MODE is oidc.

When WS_AUTH_MODE=oidc the auth proxy listens on this port and forwards authenticated traffic to the editor on WS_SERVER_PORT. Publish this port instead of WS_SERVER_PORT so every request is authenticated before it reaches the editor.

Type: integer
Default: 38080
Since: v0.4.0

Read More →

`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. 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). Wildcards are not accepted. > Multiple domain support was added in v0.0.22.

Type: string
Default: null
Delimiter: space
Since: v0.0.20

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:

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

Type: path
Default: null
Since: v0.0.21

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

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:

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

Type: path
Default: null
Since: v0.0.21

WS_SERVER_SSL_KEY="/etc/workspace/ssl/server.key"

Read More →

`WS_SERVER_SSL_ROOT`

Root directory for self-signed SSL artifacts.

Directory where startup writes the generated self-signed certificate and private key when WS_SERVER_SSL_KEY is supplied without WS_SERVER_SSL_CERT.

This is a structural path; overrides are discouraged.

Type: path
Default: /etc/workspace/ssl
Since: v0.3.0

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

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

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 →

`WS_ZSH_FZF_HISTORY_DATES_IN_SEARCH`

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 yarn zsh-autosuggestions
Delimiter: space

WS_ZSH_PLUGINS="kubectl npm python pip"

APT ​

WS_APT_ADDITIONAL_GPG_KEYS

WS_APT_ADDITIONAL_INSECURE_GPG_KEYS

WS_APT_ADDITIONAL_PACKAGES

WS_APT_ADDITIONAL_REPOS

WS_APT_DISABLE_REPOS

WS_APT_DISABLE_RESTRICTIONS

WS_APT_OVERRIDE_RESTRICTIONS

WS_APT_UPDATE_CACHE

Auth ​

WS_AUTH_DISABLE_SUDO

WS_AUTH_GITHUB_TOKEN

WS_AUTH_MODE

WS_AUTH_OIDC_ALLOWED_EMAILS

WS_AUTH_OIDC_ALLOWED_GROUPS

WS_AUTH_OIDC_CLIENT_ID

WS_AUTH_OIDC_CLIENT_SECRET

WS_AUTH_OIDC_COOKIE_SECRET

WS_AUTH_OIDC_FORBIDDEN_MESSAGE

WS_AUTH_OIDC_ISSUER

WS_AUTH_OIDC_REDIRECT_URL

WS_AUTH_OIDC_SCOPES

WS_AUTH_PASSWORD

WS_AUTH_PASSWORD_HASHED

Enterprise CA ​

WS_CA_ADDITIONAL_CERT_ENDPOINTS

WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS

Claude ​

WS_CLAUDE_STATUSLINE_DISABLE

WS_CLAUDE_STATUSLINE_HIDE_CONTEXT_BAR

WS_CLAUDE_STATUSLINE_HIDE_GIT

WS_CLAUDE_STATUSLINE_HIDE_LINES_CHANGED

WS_CLAUDE_STATUSLINE_HIDE_MODEL

WS_CLAUDE_STATUSLINE_SCRIPT

WS_CLAUDE_STATUSLINE_SHELL

Cloudflared ​

WS_CLOUDFLARED_TUNNEL_TOKEN

Docker ​

WS_DOCKER_ENABLE_CLIENT

Editor ​

WS_EDITOR_ADDITIONAL_VS_EXTENSIONS

WS_EDITOR_COMMENTS_DISABLE_FONT

WS_EDITOR_SCROLLBAR_SIZE

WS_EDITOR_SETTINGS_MERGE

WS_EDITOR_SETTINGS_MERGE_FILE

WS_EDITOR_SETTINGS_OVERRIDE

WS_EDITOR_SETTINGS_OVERRIDE_FILE

WS_EDITOR_TRUSTED_DOMAINS

Features ​

WS_FEATURES_ADDITIONAL_FEATURES

WS_FEATURES_DIR

WS_FEATURES_STORE_ALLOW_FALLBACK

WS_FEATURES_STORE_URL

Git ​

WS_GIT_CLEAR_NOTEBOOK_OUTPUT

WS_GIT_CLONE_REPO

WS_GIT_CREDENTIAL_CACHE_TIMEOUT

Helm ​

WS_HELM_PRELOAD_CACHE

Logging ​

WS_LOGGING_AUTH_PROXY_FILE

WS_LOGGING_CLOUDFLARED_FILE

WS_LOGGING_DIR

WS_LOGGING_DISABLE_CONSOLE_OUTPUT

WS_LOGGING_DOCKER_FILE

WS_LOGGING_MAIN_FILE

WS_LOGGING_METRICS_FILE

Metrics ​

WS_METRICS_COLLECTORS

WS_METRICS_ENABLE

WS_METRICS_PORT

npm ​

WS_NPM_ADDITIONAL_PACKAGES

pip ​

WS_PIP_ADDITIONAL_PACKAGES

Secrets ​

WS_SECRETS_MASTER_KEY

Seed ​

WS_SEED_SOURCE

Server ​

APT

`WS_APT_ADDITIONAL_GPG_KEYS`

`WS_APT_ADDITIONAL_INSECURE_GPG_KEYS`

`WS_APT_ADDITIONAL_PACKAGES`

`WS_APT_ADDITIONAL_REPOS`

`WS_APT_DISABLE_REPOS`

`WS_APT_DISABLE_RESTRICTIONS`

`WS_APT_OVERRIDE_RESTRICTIONS`

`WS_APT_UPDATE_CACHE`

Auth

`WS_AUTH_DISABLE_SUDO`

`WS_AUTH_GITHUB_TOKEN`

`WS_AUTH_MODE`

`WS_AUTH_OIDC_ALLOWED_EMAILS`

`WS_AUTH_OIDC_ALLOWED_GROUPS`

`WS_AUTH_OIDC_CLIENT_ID`

`WS_AUTH_OIDC_CLIENT_SECRET`

`WS_AUTH_OIDC_COOKIE_SECRET`

`WS_AUTH_OIDC_FORBIDDEN_MESSAGE`

`WS_AUTH_OIDC_ISSUER`

`WS_AUTH_OIDC_REDIRECT_URL`

`WS_AUTH_OIDC_SCOPES`

`WS_AUTH_PASSWORD`

`WS_AUTH_PASSWORD_HASHED`

Enterprise CA

`WS_CA_ADDITIONAL_CERT_ENDPOINTS`

`WS_CA_ADDITIONAL_CERT_INSECURE_ENDPOINTS`

Claude

`WS_CLAUDE_STATUSLINE_DISABLE`

`WS_CLAUDE_STATUSLINE_HIDE_CONTEXT_BAR`

`WS_CLAUDE_STATUSLINE_HIDE_GIT`

`WS_CLAUDE_STATUSLINE_HIDE_LINES_CHANGED`

`WS_CLAUDE_STATUSLINE_HIDE_MODEL`

`WS_CLAUDE_STATUSLINE_SCRIPT`

`WS_CLAUDE_STATUSLINE_SHELL`

Cloudflared

`WS_CLOUDFLARED_TUNNEL_TOKEN`

Docker

`WS_DOCKER_ENABLE_CLIENT`

Editor

`WS_EDITOR_ADDITIONAL_VS_EXTENSIONS`

`WS_EDITOR_COMMENTS_DISABLE_FONT`

`WS_EDITOR_SCROLLBAR_SIZE`

`WS_EDITOR_SETTINGS_MERGE`

`WS_EDITOR_SETTINGS_MERGE_FILE`

`WS_EDITOR_SETTINGS_OVERRIDE`

`WS_EDITOR_SETTINGS_OVERRIDE_FILE`

`WS_EDITOR_TRUSTED_DOMAINS`

Features

`WS_FEATURES_ADDITIONAL_FEATURES`

`WS_FEATURES_DIR`

`WS_FEATURES_STORE_ALLOW_FALLBACK`

`WS_FEATURES_STORE_URL`

Git

`WS_GIT_CLEAR_NOTEBOOK_OUTPUT`

`WS_GIT_CLONE_REPO`

`WS_GIT_CREDENTIAL_CACHE_TIMEOUT`

Helm

`WS_HELM_PRELOAD_CACHE`

Logging

`WS_LOGGING_AUTH_PROXY_FILE`

`WS_LOGGING_CLOUDFLARED_FILE`

`WS_LOGGING_DIR`

`WS_LOGGING_DISABLE_CONSOLE_OUTPUT`

`WS_LOGGING_DOCKER_FILE`

`WS_LOGGING_MAIN_FILE`

`WS_LOGGING_METRICS_FILE`

Metrics

`WS_METRICS_COLLECTORS`

`WS_METRICS_ENABLE`

`WS_METRICS_PORT`

npm

`WS_NPM_ADDITIONAL_PACKAGES`

pip

`WS_PIP_ADDITIONAL_PACKAGES`

Secrets

`WS_SECRETS_MASTER_KEY`

Seed

`WS_SEED_SOURCE`

Server