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

> Learn how the --link-protection-trusted-domains flag in code-server enhances external link security by letting you whitelist trusted domains, bypassing confirmation prompts for specified URLs.

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

---

**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`](https://github.com/coder/code-server/blob/main/src/node/cli.ts), where it accepts an array of string values:

```typescript
// 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`](https://github.com/coder/code-server/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```bash
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`](https://github.com/coder/code-server/blob/main/config.yaml) using YAML array syntax:

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

```

Start the server with the configuration file:

```bash
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`](https://github.com/coder/code-server/blob/main/src/node/cli.ts)** (lines 208-211): Defines the CLI flag schema and description
- **[`lib/vscode/src/vs/server/node/webClientServer.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/lib/vscode/product.json)**: Static configuration file that can pre-populate `linkProtectionTrustedDomains` at build time
- **[`ci/build/build-vscode.sh`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/product.json) in [`webClientServer.ts`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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`](https://github.com/coder/code-server/blob/main/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.