|
| 1 | +#Wildcard Access URLs |
| 2 | + |
| 3 | +>[!IMPORTANT] |
| 4 | +>**Wildcard access URL is 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. |
| 5 | +
|
| 6 | +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. |
| 7 | + |
| 8 | +##Why configure wildcard access URLs? |
| 9 | + |
| 10 | +###Key benefits |
| 11 | + |
| 12 | +-**Eliminates port conflicts**: Each application gets a unique subdomain (e.g.,`8080--main--myworkspace--john.coder.example.com`) |
| 13 | +-**Enhanced security**: Applications run in isolated subdomains with separate browser security contexts |
| 14 | +-**Better compatibility**: Web-based IDEs, mobile devices, and third-party integrations work reliably with standard HTTPS URLs |
| 15 | + |
| 16 | +###When wildcard access URL is required |
| 17 | + |
| 18 | +Wildcard access URL enables subdomain-based workspace applications, which is required for: |
| 19 | + |
| 20 | +-**Web IDEs**: code-server, VS Code Web, JupyterLab, RStudio work better with dedicated subdomains |
| 21 | +-**Modern development frameworks**: Vite, React dev server, Next.js, and similar tools expect to control the entire domain for features like hot module replacement and asset serving |
| 22 | +-**Development servers with preview URLs**: Applications that generate preview URLs or use absolute paths |
| 23 | +-**Applications that don't support path-based routing**: Some tools like KasmVNC cannot function with path-based access |
| 24 | +-**Secure development environment isolation**: Each development application runs on its own subdomain |
| 25 | + |
| 26 | +##Configuration |
| 27 | + |
| 28 | +`CODER_WILDCARD_ACCESS_URL` is necessary for[port forwarding](port-forwarding.md#dashboard) via the dashboard or running[coder_apps](../templates/index.md) on an absolute path. Set this to a wildcard subdomain that resolves to Coder (e.g.`*.coder.example.com`). |
| 29 | + |
| 30 | +```bash |
| 31 | +export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" |
| 32 | +coder server |
| 33 | +``` |
| 34 | + |
| 35 | +###DNS Setup |
| 36 | + |
| 37 | +You'll need to configure DNS to point wildcard subdomains to your Coder server: |
| 38 | + |
| 39 | +```text |
| 40 | +*.coder.example.com A <your-coder-server-ip> |
| 41 | +``` |
| 42 | + |
| 43 | +##Template Configuration |
| 44 | + |
| 45 | +In your Coder templates, enable subdomain applications using the`subdomain` parameter: |
| 46 | + |
| 47 | +```hcl |
| 48 | +resource "coder_app" "code-server" { |
| 49 | + agent_id = coder_agent.main.id |
| 50 | + slug = "code-server" |
| 51 | + display_name = "VS Code" |
| 52 | + url = "http://localhost:8080" |
| 53 | + icon = "/icon/code.svg" |
| 54 | + subdomain = true |
| 55 | + share = "owner" |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +##Troubleshooting |
| 60 | + |
| 61 | +###Applications not accessible |
| 62 | + |
| 63 | +If workspace applications are not working: |
| 64 | + |
| 65 | +1. Verify the`CODER_WILDCARD_ACCESS_URL` environment variable is configured correctly |
| 66 | +2. Check DNS resolution for wildcard subdomains |
| 67 | +3. Ensure TLS certificates cover the wildcard domain |
| 68 | +4. Confirm template`coder_app` resources have`subdomain = true` |
| 69 | + |
| 70 | +##See also |
| 71 | + |
| 72 | +-[Port Forwarding](port-forwarding.md) - Access workspace applications via dashboard when wildcard URL is not configured |
| 73 | +-[Workspace Proxies](workspace-proxies.md) - Improve performance for geo-distributed teams using wildcard URLs |