How the `--link-protection-trusted-domains` Flag Controls External Link Security in code-server

The --link-protection-trusted-domains flag in code-server defines a whitelist of domains that bypass the link protection confirmation dialog, allowing administrators to specify which external URLs users can open directly without security prompts.

The coder/code-server project implements a security feature that intercepts external link navigation to prevent malicious redirects. By using the --link-protection-trusted-domains command-line option, system administrators can curate a list of trusted origins that are exempt from these confirmation dialogs, streamlining the user experience while maintaining security boundaries.

Understanding the Link Protection Mechanism

By default, code-server displays a confirmation dialog whenever a user attempts to open an external URL. This link protection prevents automatic navigation to potentially malicious sites. The --link-protection-trusted-domains flag allows specific domains to bypass this safeguard, treating them as safe origins that require no user confirmation.

When a user clicks a hyperlink, the front-end checks the URL against the trusted domains list. If the origin matches any entry, the browser opens the link immediately. If no match exists, a modal asks the user to confirm the navigation.

Server-Side Configuration and CLI Definition

The flag is declared in the CLI argument parser at src/node/cli.ts, where it accepts an array of string values:

// src/node/cli.ts (lines 208-211)
"link-protection-trusted-domains": {
  type: "string[]",
  description: "Links matching a trusted domain can be opened without link protection.",
},

When the server initializes, the parsed arguments populate environmentService.args, making the domain list available to the web server logic. The type definition ensures the flag captures multiple domain entries as an array of strings.

Domain Whitelist Aggregation and Injection

The whitelist assembly occurs in lib/vscode/src/vs/server/node/webClientServer.ts, where the server merges CLI arguments with static product configuration values. The implementation collects domains from both sources:

// lib/vscode/src/vs/server/node/webClientServer.ts (lines 31-37)
const linkProtectionTrustedDomains: string[] = [];
if (this._environmentService.args['link-protection-trusted-domains']) {
  linkProtectionTrustedDomains.push(
    ...this._environmentService.args['link-protection-trusted-domains']
  );
}
if (this._productService.linkProtectionTrustedDomains) {
  linkProtectionTrustedDomains.push(...this._productService.linkProtectionTrustedDomains);
}

This merged array is then injected into the product configuration object sent to the client:

// lib/vscode/src/vs/server/node/webClientServer.ts (lines 46-48)
const productConfiguration: Partial<Mutable<IProductConfiguration>> = {
  linkProtectionTrustedDomains,
};

The client-side application consumes this configuration to make runtime security decisions.

Client-Side Enforcement

In the browser environment, the link protection logic evaluates each clickable URL against the linkProtectionTrustedDomains array provided in the product configuration. The security check determines whether to display the confirmation dialog or allow direct navigation.

If the administrator omits the --link-protection-trusted-domains flag, the array defaults to empty, forcing the protection dialog for every external link.

Configuring Trusted Domains

Administrators can specify trusted domains using either command-line arguments or configuration files.

Command-Line Usage

Pass multiple domains by repeating the flag:

code-server \
  --auth none \
  --link-protection-trusted-domains https://open-vsx.org \
  --link-protection-trusted-domains https://docs.my-corp.com

All sub-paths of these domains will bypass the confirmation dialog.

Configuration File Method

Define the whitelist in config.yaml using YAML array syntax:

link-protection-trusted-domains:
  - https://open-vsx.org
  - https://docs.my-corp.com

Start the server with the configuration file:

code-server --config /path/to/config.yaml

Key Implementation Files

The following source files govern the end-to-end behavior of the link protection feature:

• src/node/cli.ts (lines 208-211): Defines the CLI flag schema and description
• lib/vscode/src/vs/server/node/webClientServer.ts (lines 31-48): Merges CLI arguments with product.json values and injects the whitelist into the client configuration
• lib/vscode/product.json: Static configuration file that can pre-populate linkProtectionTrustedDomains at build time
• ci/build/build-vscode.sh (lines 96-98): Handles default value insertion during the build process

Summary

• --link-protection-trusted-domains accepts an array of domain strings via CLI or config file to whitelist safe external links.
• The server aggregates these domains with any values from product.json in webClientServer.ts before injecting them into the client-side product configuration.
• The front-end skips the confirmation dialog only for URLs matching entries in the trusted domains list.
• When unspecified, the whitelist remains empty, enforcing link protection on all external navigation.
• Configuration supports both command-line flags and YAML config files for flexible deployment scenarios.

Frequently Asked Questions

What happens if no trusted domains are specified?

If the --link-protection-trusted-domains flag is omitted and no values exist in product.json, the whitelist defaults to an empty array. Consequently, every external link triggers the protection confirmation dialog, requiring explicit user approval before navigation.

Can wildcards be used in domain patterns?

The configuration accepts domain patterns such as https://*.my-corp.com in the argument array. The actual matching logic depends on the client-side implementation checking against these stored values. Administrators should test specific patterns to verify matching behavior for their deployment.

How does this flag interact with product.json?

The system merges values from both sources. Domains specified via CLI are combined with any linkProtectionTrustedDomains entries defined in the static product.json file. This allows build-time defaults to coexist with runtime overrides, providing flexibility for containerized and manual deployments.

Is link protection enabled by default?

Yes. Link protection is active by default in code-server to prevent automatic navigation to malicious sites. The confirmation dialog appears for all external URLs unless explicitly exempted via the --link-protection-trusted-domains whitelist or the corresponding product configuration.

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