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

> Explore code-server environment variables to customize authentication, networking, logging, and feature toggles. Learn how to configure your instance beyond CLI arguments for ultimate control.

- Repository: [Coder/code-server](https://github.com/coder/code-server)
- Tags: documentation
- Published: 2026-03-01

---

**code-server respects environment variables for authentication, networking, logging, and feature toggles, with values sourced in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) and [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) and [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/src/node/main.ts) at line 56 and [`src/node/wrapper.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/src/node/main.ts) to enable extra logging and disable minification. The **NODE_ENV** variable (checked in [`src/node/i18n/index.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/src/node/cli.ts).

## How Environment Variables Interact with CLI Arguments

The CLI parser in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/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:

```bash

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

```bash
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:

```bash
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`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) | Core logic mapping environment variables to CLI options; handles passwords, ports, logging, and feature toggles. |
| [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/src/node/wrapper.ts) | Implements the child-process wrapper that monitors `CODE_SERVER_PARENT_PID`. |
| [`src/node/constants.ts`](https://github.com/coder/code-server/blob/main/src/node/constants.ts) | Defines standard proxy environment variables for `node-fetch` operations. |
| [`src/node/i18n/index.ts`](https://github.com/coder/code-server/blob/main/src/node/i18n/index.ts) | Checks `NODE_ENV` for development-mode localization behaviors. |
| [`docs/FAQ.md`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) and [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/src/node/constants.ts) at line 28.