`----proxy-domain` vs `--disable-proxy` in code-server: Key Differences Explained

--proxy-domain enables domain-based forwarding for specific host patterns, while --disable-proxy globally blocks all proxy routes regardless of configuration.

The coder/code-server project exposes the VS Code UI via HTTP and can route traffic to forwarded ports through an internal proxy. Understanding the distinction between these two flags is essential for securing your deployment and controlling how external traffic reaches running processes.

What --proxy-domain Does

The --proxy-domain flag activates domain-based proxying, allowing you to route requests based on the incoming hostname rather than URL paths. When you provide patterns like *.example.com or {{port}}.dev.example.com, code-server converts these into regular-expression matchers in src/node/routes/domainProxy.ts.

If the request's Host header matches one of the configured patterns, the server extracts the port number from the domain and forwards the request to http://0.0.0.0:<port>. This functionality is defined in the CLI parser at src/node/cli.ts (lines 199-202), where the flag is parsed into args["proxy-domain"] as an array of strings.

When the array is non-empty, src/node/main.ts (lines 91-96) logs the active domains and mounts the domain-proxy middleware. If the array is empty, domain-proxy routes are not created, but path-based proxy routes (e.g., /port/8080) remain functional unless explicitly disabled.

# Enable wildcard subdomain proxying

code-server --proxy-domain "*.example.com"

# Configure multiple patterns with explicit port placeholders

code-server --proxy-domain "*.coder.com" --proxy-domain "{{port}}.dev.local"

What --disable-proxy Does

The --disable-proxy flag is a boolean switch that globally disables all proxy functionality, including both domain-based and path-based routes. When set to true, the application rejects any proxy requests with a Forbidden error, forcing code-server to serve only the static UI and API endpoints.

In src/node/http.ts (lines 94-95), the helper function proxyEnabled(req) returns the negation of this flag. All proxy routes invoke ensureProxyEnabled(req), which throws a Forbidden exception if --disable-proxy is active, as implemented in src/node/routes/domainProxy.ts (lines 62-65). Additionally, src/node/main.ts prints "Proxy disabled" during startup when this flag is detected.

# Run code-server with all proxy routes disabled

code-server --disable-proxy

How the Flags Interact

The interaction between these flags follows a strict priority order:

1. If --disable-proxy is set: All proxy handling is turned off, and any --proxy-domain values are ignored. The server rejects proxy requests immediately.
2. If --disable-proxy is not set and --proxy-domain is populated: Domain-proxy routes are activated alongside the default path-proxy routes.
3. If neither flag is set: Only path-based proxying (via /port/<number>) is available.

This hierarchy ensures that --disable-proxy acts as a security kill-switch, overriding any domain-specific configurations that might otherwise expose internal ports.

Configuration Examples

Scenario 1: Public Development Environment with Custom Domains

Use --proxy-domain when you want users to access forwarded ports via clean URLs rather than path prefixes:

code-server --proxy-domain "{{port}}.dev.mycompany.com" --port 8080

Requests to 3000.dev.mycompany.com automatically proxy to port 3000 on localhost.

Scenario 2: Locked-Down Internal Instance

Use --disable-proxy when running code-server behind a dedicated reverse proxy (like Nginx or Traefik) that handles its own port forwarding:

code-server --disable-proxy --auth password

This prevents users from circumventing your external proxy rules by accessing ports directly through code-server's built-in router.

Summary

• --proxy-domain enables regex-based domain proxying by setting args["proxy-domain"] in src/node/cli.ts and activating routes in src/node/routes/domainProxy.ts.
• --disable-proxy is a boolean flag that forces proxyEnabled() in src/node/http.ts to return false, blocking all proxy traffic regardless of domain configuration.
• When both flags are present, --disable-proxy takes precedence and ignores any domain patterns.
• Domain patterns support wildcards (*) and port placeholders ({{port}}) for flexible routing rules.

Frequently Asked Questions

Can I use --proxy-domain and --disable-proxy together?

No. When --disable-proxy is set to true, code-server ignores all --proxy-domain configurations. The ensureProxyEnabled middleware in src/node/routes/domainProxy.ts checks the disable flag first and throws a Forbidden error before any domain matching occurs, effectively making the proxy domain settings inert.

Does --disable-proxy affect the VS Code UI itself?

No. The --disable-proxy flag only disables the proxy routes used for forwarding traffic to running processes (like web servers on port 3000). The main VS Code interface, file system access, and terminal functionality continue to work normally. This restriction is enforced in the HTTP helper layer at src/node/http.ts, which specifically guards proxy endpoints while leaving static assets and API routes unaffected.

What happens if I specify --proxy-domain but not --disable-proxy?

The server enables domain-based proxying using your specified patterns while keeping path-based proxying active. In src/node/main.ts (lines 91-96), the application logs the configured domains and initializes the domain-proxy middleware. Users can access ports either via the configured subdomain patterns or through the default /port/<number> paths.

Is --proxy-domain required for port forwarding to work?

No. Port forwarding functions without --proxy-domain via path-based proxying at routes like /port/8080. However, without domain-based proxying, some applications that expect to run at the root path (/) or require specific Host headers may not function correctly behind the path prefix. The domain proxy provides a cleaner integration for such applications by routing the root path directly to the target port.

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