docs: add section about how to disable path based apps to security best practices (#18419)

EdwardAngert · deansheather · web-flow · commit ab254adfb958 · 2025-07-01T13:18:47.000-04:00
add a new section specifically about how to disable path-based apps to
the security best practices doc

## todo

- [x] copy review
- [x] cross-linking

---------

Co-authored-by: EdwardAngert &lt;17991901+EdwardAngert@users.noreply.github.com&gt;
Co-authored-by: Dean Sheather &lt;dean@deansheather.com&gt;
diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md
@@ -60,6 +60,8 @@ If you are providing TLS certificates directly to the Coder server, either
    options (these both take a comma separated list of files; list certificates
    and their respective keys in the same order).
 
+After you enable the wildcard access URL, you should [disable path-based apps](../../tutorials/best-practices/security-best-practices.md#disable-path-based-apps) for security.
+
 ## TLS & Reverse Proxy
 
 The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
diff --git a/docs/tutorials/best-practices/security-best-practices.md b/docs/tutorials/best-practices/security-best-practices.md
@@ -66,6 +66,33 @@ logs (which have `msg: audit_log`) and retain them for a minimum of two years
 If a security incident with Coder does occur, audit logs are invaluable in
 determining the nature and scope of the impact.
 
+### Disable path-based apps
+
+For production deployments, we recommend that you disable path-based apps after you've configured a wildcard access URL.
+
+Path-based apps share the same origin as the Coder API, which can be convenient for trialing Coder,
+but can expose the deployment to cross-site-scripting (XSS) attacks in production.
+A malicious workspace could reuse Coder cookies to call the API or interact with other workspaces owned by the same user.
+
+1. [Enable sub-domain apps with a wildcard DNS record](../../admin/setup/index.md#wildcard-access-url) (like `*.coder.example.com`)
+
+1. Disable path-based apps:
+
+   ```shell
+   coderd server --disable-path-apps
+   # or
+   export CODER_DISABLE_PATH_APPS=true
+   ```
+
+By default, Coder mitigates the impact of having path-based apps enabled, but we still recommend disabling it to prevent
+malicious workspaces accessing other workspaces owned by the same user or performing requests against the Coder API.
+
+If you do keep path-based apps enabled:
+
+- Path-based apps cannot be shared with other users unless you start the Coder server with `--dangerous-allow-path-app-sharing`.
+- Users with the site `owner` role cannot use their admin privileges to access path-based apps for workspaces unless the
+  server is started with `--dangerous-allow-path-app-site-owner-access`.
+
 ## PostgreSQL
 
 PostgreSQL is the persistent datastore underlying the entire Coder deployment.
