# Wildcard Access URLs

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](https://coder.com/docs/user-guides/workspace-access/port-forwarding#dashboard) (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](https://coder.com/docs/admin/networking/port-forwarding.md#dashboard) via the dashboard or running [coder_apps](https://coder.com/docs/admin/templates.md) 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:

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

```sh
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](https://coder.com/docs/admin/setup.md#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:

- [NGINX with Let's Encrypt](https://coder.com/docs/tutorials/reverse-proxy-nginx.md)
- [Apache with Let's Encrypt](https://coder.com/docs/tutorials/reverse-proxy-apache.md)
- [Caddy reverse proxy](https://coder.com/docs/tutorials/reverse-proxy-caddy.md)

If your reverse proxy rewrites the request `Host` and forwards the original
host in `X-Forwarded-Host`, configure
[`CODER_PROXY_TRUSTED_ORIGINS`](https://coder.com/docs/reference/cli/server.md#--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.

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

Or alternatively, using a CNAME record:

```txt
*.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:

```txt
*.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](https://coder.com/docs/admin/networking/workspace-proxies.md) for geo-distributed teams, each proxy requires its own wildcard access URL configuration:

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

```txt
*.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:

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

1. 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
2. Check DNS resolution for wildcard subdomains:

   ```sh
   dig test.coder.example.com
   nslookup test.coder.example.com
   ```

3. Ensure TLS certificates cover the wildcard domain
4. Confirm template `coder_app` resources have `subdomain = true`

## See also

- [Workspace Proxies](https://coder.com/docs/admin/networking/workspace-proxies.md) - Improve performance for geo-distributed teams using wildcard URLs