code-server Environment Variables: Complete Configuration Guide Beyond CLI Arguments

code-server respects environment variables for authentication, networking, logging, and feature toggles, with values sourced in src/node/cli.ts and src/node/main.ts typically establishing defaults that CLI arguments can override.

The coder/code-server project exposes nearly every runtime behavior through environment variables inspected at startup. These variables are read during initialization—primarily in src/node/cli.ts and src/node/main.ts—providing a configuration layer that operates independently of command-line flags and integrates seamlessly with container orchestration and systemd units.

Authentication and Session Security

Password and Cookie Configuration

You can supply credentials via the environment to avoid exposing secrets in process listings. In src/node/cli.ts lines 603–606 and 620–622, the parser checks for PASSWORD and HASHED_PASSWORD; when either is present, the corresponding --password and --hashed-password CLI flags are ignored entirely.

To distinguish sessions when running multiple instances on the same host, set CODE_SERVER_COOKIE_SUFFIX. This appends a custom string to the session cookie name, as implemented at line 626 in src/node/cli.ts.

Network Binding and Connectivity

Host and Port Overrides

Force the listening address without modifying startup scripts using CODE_SERVER_HOST and PORT. According to src/node/cli.ts at lines 798 and 805, these variables override the default bind address and TCP port, though an explicit --host or --port flag takes precedence when provided.

Session Socket

For Unix-domain socket support, CODE_SERVER_SESSION_SOCKET specifies the socket path. This is read at line 545 in src/node/cli.ts and enables the session-socket feature for reverse-proxy integrations.

Process Lifecycle and Idle Timeout

Parent Process Monitoring

When CODE_SERVER_PARENT_PID is set, code-server spawns a child process that monitors the specified PID and exits if the parent dies. This logic resides in src/node/main.ts at line 56 and src/node/wrapper.ts lines 377–378, ensuring cleanup in managed process hierarchies.

Idle Timeout Shutdown

Set CODE_SERVER_IDLE_TIMEOUT_SECONDS to force shutdown after a period of inactivity. The parser in src/node/cli.ts (lines 634–641) validates that the value exceeds 60 seconds before applying the timeout.

Logging and Development Mode

Log Levels and Debug Output

Control verbosity with LOG_LEVEL, which accepts error, warn, info, debug, or trace. Defined in src/node/cli.ts lines 553–556, this variable overrides the --log and --verbose flags. For development builds, set VSCODE_DEV to 1 in src/node/main.ts to enable extra logging and disable minification. The NODE_ENV variable (checked in src/node/i18n/index.ts line 55) toggles development-only behaviors in the i18n module.

Feature Toggles

UI and Proxy Disables

Several CS_DISABLE_* variables disable specific features:

• CS_DISABLE_FILE_DOWNLOADS (line 608 in src/node/cli.ts): Removes the Download button from the UI when set to 1 or true.
• CS_DISABLE_GETTING_STARTED_OVERRIDE (line 612): Suppresses the Getting Started welcome page regardless of user settings.
• CS_DISABLE_PROXY (line 616): Disables automatic proxy detection, causing the server to ignore VSCODE_PROXY_URI.

Extensions and External Services

GitHub and Marketplace Integration

Supply a GITHUB_TOKEN (read at line 630 in src/node/cli.ts) to authenticate API calls for the GitHub extension. Override the default VS Code extensions marketplace by setting EXTENSIONS_GALLERY, handled in src/node/main.ts lines 209–211.

Proxy Configuration

For the Ports tab proxy, VSCODE_PROXY_URI defines the target URL; if unset, code-server builds one from detected proxies (lines 663–664 in src/node/cli.ts). For extension gallery requests using node-fetch, the standard HTTPS_PROXY, https_proxy, HTTP_PROXY, and http_proxy variables are referenced from src/node/constants.ts at line 28.

Configuration Files and Data Directories

Config Path and XDG Compliance

Point to a JSON configuration file with CODE_SERVER_CONFIG (line 711 in src/node/cli.ts), allowing any CLI option to be specified via file. On Linux and macOS, XDG_DATA_HOME determines where user data (extensions and settings) is stored, as documented in docs/FAQ.md lines 200–209.

IPC Hook

Enable the VS Code IPC hook for child processes by setting VSCODE_IPC_HOOK_CLI, read at lines 837–839 in src/node/cli.ts.

How Environment Variables Interact with CLI Arguments

The CLI parser in src/node/cli.ts generally reads environment variables first, establishing default values. If a corresponding command-line flag is also supplied, the flag’s value takes precedence—as seen with --port overriding PORT. However, PASSWORD and HASHED_PASSWORD are exceptions: when these environment variables are present, the related CLI flags are ignored entirely, ensuring secrets remain out of argument lists.

Practical Configuration Examples

Run code-server without any CLI flags using only environment variables:

# Authenticate with a hashed password and bind to localhost only

export HASHED_PASSWORD="$2y$10$..."
export CODE_SERVER_HOST=127.0.0.1
export PORT=8080
code-server

Disable UI features and set a custom idle timeout:

export CS_DISABLE_FILE_DOWNLOADS=1
export CS_DISABLE_GETTING_STARTED_OVERRIDE=true
export CODE_SERVER_IDLE_TIMEOUT_SECONDS=600
export CODE_SERVER_COOKIE_SUFFIX=_production
code-server

Use a custom extensions marketplace behind a corporate proxy:

export EXTENSIONS_GALLERY="https://internal.registry/vscode"
export VSCODE_PROXY_URI="http://proxy.corp.local:3128"
export HTTPS_PROXY="http://proxy.corp.local:3128"
code-server

Key Source Files

File	Relevance
src/node/cli.ts	Core logic mapping environment variables to CLI options; handles passwords, ports, logging, and feature toggles.
src/node/main.ts	Server startup logic, proxy URL handling (VSCODE_PROXY_URI), and parent PID monitoring (CODE_SERVER_PARENT_PID).
src/node/wrapper.ts	Implements the child-process wrapper that monitors CODE_SERVER_PARENT_PID.
src/node/constants.ts	Defines standard proxy environment variables for node-fetch operations.
src/node/i18n/index.ts	Checks NODE_ENV for development-mode localization behaviors.
docs/FAQ.md	Human-readable reference for common variables like CODE_SERVER_CONFIG and XDG_DATA_HOME.

Summary

• Environment variables in code-server configure authentication, networking, logging, extensions, and feature toggles without modifying CLI invocations.
• Values are sourced primarily from src/node/cli.ts and src/node/main.ts during early initialization.
• Most variables establish defaults that CLI flags can override, except PASSWORD and HASHED_PASSWORD, which disable their corresponding flags when set.
• Use these variables to simplify container deployments, systemd services, and multi-instance hosting scenarios.

Frequently Asked Questions

Can I completely replace CLI arguments with environment variables for code-server authentication?

Yes. Setting PASSWORD or HASHED_PASSWORD in the environment disables the --password and --hashed-password CLI flags entirely. The server reads these values from process.env in src/node/cli.ts (lines 603–622) and ignores any command-line credentials when the variables are present.

How do I configure the listening port without changing the command line?

Export the PORT environment variable. As implemented in src/node/cli.ts at line 805, this sets the default TCP port, though an explicit --port flag takes precedence if provided. For the bind address, use CODE_SERVER_HOST (line 798).

What controls automatic shutdown when code-server is idle?

The CODE_SERVER_IDLE_TIMEOUT_SECONDS variable forces the server to shut down after the specified number of seconds without connections. The parser in src/node/cli.ts (lines 634–641) requires the value to be greater than 60 seconds.

Where does code-server read proxy settings for extensions versus the Ports tab?

The Ports tab uses VSCODE_PROXY_URI (read in src/node/cli.ts lines 663–664), while extension gallery requests respect HTTPS_PROXY, HTTP_PROXY, and their lowercase variants defined in src/node/constants.ts at line 28.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}