HomeAdministrationNetworkingWildcard Access URL

Wildcard Access URL

Wildcard access URLs unlock Coder's full potential for modern development workflows. While optional for basic SSH usage, this feature becomes essential when teams need web applications, development previews, or browser-based tools. Wildcard access URLs are essential for many development workflows in Coder - Web IDEs (code-server, VS Code Web, JupyterLab) and some development frameworks work significantly better with subdomain-based access rather than path-based URLs.

Why configure wildcard access URLs?

Key benefits

Enables port access: Each application gets a unique subdomain with port support (e.g. 8080--main--myworkspace--john.coder.example.com).
Enhanced security: Applications run in isolated subdomains with separate browser security contexts and prevents access to the Coder API from malicious JavaScript
Better compatibility: Most applications are designed to work at the root of a hostname rather than at a subpath, making subdomain access more reliable

Applications that require subdomain access

The following tools require wildcard access URL:

Vite dev server: Hot module replacement and asset serving issues with path-based routing
React dev server: Similar issues with hot reloading and absolute path references
Next.js development server: Asset serving and routing conflicts with path-based access
JupyterLab: More complex template configuration and security risks when using path-based routing
RStudio: More complex template configuration and security risks when using path-based routing

Configuration

CODER_WILDCARD_ACCESS_URL is necessary for port forwarding via the dashboard or running coder_apps on an absolute path. Set it to a wildcard hostname that resolves to Coder. The value must contain exactly one * at the beginning of the hostname. Coder replaces * with the generated application name, which stays within a single DNS label.

Coder supports the wildcard as a full label or with a suffix in the first label:

Pattern	Example generated application hostname	Required DNS and TLS wildcard
`*.apps.example.com`	`8080--main--myworkspace--john.apps.example.com`	`*.apps.example.com`
`*-apps.example.com`	`8080--main--myworkspace--john-apps.example.com`	`*.example.com`

For example, use the suffix pattern to keep the Coder dashboard and application hostnames at the same DNS level:

CODER_ACCESS_URL=https://apps.example.com
CODER_WILDCARD_ACCESS_URL=*-apps.example.com

This configuration serves the dashboard from https://apps.example.com and a workspace application from a hostname such as https://8080--main--myworkspace--john-apps.example.com.

TLS Certificate Setup

Wildcard access URLs require a TLS certificate that covers the wildcard domain. You have several options:

Tip

You can use a single certificate for both the access URL and wildcard access URL. For *.apps.example.com, the certificate must include apps.example.com and *.apps.example.com. For *-apps.example.com with an access URL of apps.example.com, a certificate for *.example.com covers both hostnames.

Direct TLS Configuration

Configure Coder to handle TLS directly using the wildcard certificate:

export CODER_TLS_ENABLE=true
export CODER_TLS_CERT_FILE=/path/to/wildcard.crt
export CODER_TLS_KEY_FILE=/path/to/wildcard.key

See TLS & Reverse Proxy for detailed configuration options.

Reverse Proxy with Let's Encrypt

Use a reverse proxy to handle TLS termination with automatic certificate management:

If your reverse proxy rewrites the request Host and forwards the original host in X-Forwarded-Host, configure CODER_PROXY_TRUSTED_ORIGINS to trust that proxy's address. Otherwise Coder will ignore X-Forwarded-Host for subdomain app routing.

DNS Setup

You'll need to configure DNS to point wildcard subdomains to your Coder server:

Note

We do not recommend using a top-level-domain for Coder wildcard access (for example *.workspaces), even on private networks with split-DNS. Some browsers consider these "public" domains and will refuse Coder's cookies, which are vital to the proper operation of this feature.

*.coder.example.com    A    <your-coder-server-ip>

Or alternatively, using a CNAME record:

*.coder.example.com    CNAME    coder.example.com

For a suffix pattern such as *-apps.example.com, DNS and TLS wildcards must cover the entire first label:

*.example.com    A    <your-coder-server-ip>

DNS providers and certificate authorities don't interpret *-apps.example.com as a wildcard record or certificate name. Configure *.example.com instead, and ensure routing that wildcard to Coder doesn't conflict with other services under example.com.

Workspace Proxies

If you're using workspace proxies for geo-distributed teams, each proxy requires its own wildcard access URL configuration:

# Main Coder server
export CODER_WILDCARD_ACCESS_URL="*.coder.example.com"

# Sydney workspace proxy
export CODER_WILDCARD_ACCESS_URL="*.sydney.coder.example.com"

# London workspace proxy
export CODER_WILDCARD_ACCESS_URL="*.london.coder.example.com"

Each proxy's wildcard domain must have corresponding DNS records:

*.sydney.coder.example.com    A    <sydney-proxy-ip>
*.london.coder.example.com    A    <london-proxy-ip>

Template Configuration

In your Coder templates, enable subdomain applications using the subdomain parameter:

resource "coder_app" "code-server" {
  agent_id     = coder_agent.main.id
  slug         = "code-server"
  display_name = "VS Code"
  url          = "http://localhost:8080"
  icon         = "/icon/code.svg"
  subdomain    = true
  share        = "owner"
}

Troubleshooting

Applications not accessible

If workspace applications are not working:

Verify the CODER_WILDCARD_ACCESS_URL environment variable is configured correctly:
- Check the deployment settings in the Coder dashboard (Settings > Deployment)
- Ensure it matches your wildcard domain (e.g., *.coder.example.com)
- Restart the Coder server if you made changes to the environment variable
Check DNS resolution for wildcard subdomains:

dig test.coder.example.com nslookup test.coder.example.com
Ensure TLS certificates cover the wildcard domain
Confirm template coder_app resources have subdomain = true