coder · EdwardAngert · Jul 1, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 17, 2025
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 a wildcard sub-domain, [disable path-based apps](../../tutorials/best-practices/security-best-practices.md#disable-path-based-apps).
+
 ## 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,31 @@ 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, disable path-based apps.
+
+Path-based apps share the same origin as the Coder API.
+This setup is convenient for demos, 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, Coder limits the risk:
+
+- 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 workspace unless the server is started with `--dangerous-allow-path-app-site-owner-access`.
+
 ## PostgreSQL
 
 PostgreSQL is the persistent datastore underlying the entire Coder deployment.