|
| 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 |
0 commit comments