From e77874bce455e3be8a4badea86209b26abf8f51f Mon Sep 17 00:00:00 2001 From: Roo Code Date: Wed, 18 Feb 2026 20:27:03 +0000 Subject: [PATCH 1/6] docs: add proxied: false documentation for preview environments --- docs/roo-code-cloud/environments.mdx | 37 +++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index f8dc1a48..b3ef082f 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -14,6 +14,8 @@ keywords: - mise - Initial Path - Subdomain Routing + - Proxied Ports + - Direct Port Access --- # Preview Environments @@ -91,6 +93,7 @@ ports: |-------|-------------|----------| | `name` | Identifier for the port (used to generate environment variables) | Yes | | `port` | The port number to expose | Yes | +| `proxied` | Whether traffic goes through the auth proxy (`true` by default). Set to `false` for direct port access (see [Direct Port Access](#direct-port-access-non-proxied)) | No | | `initial_path` | Default path to append to the preview URL | No | | `subdomain` | Subdomain to set on the `Host` header when forwarding requests to the app | No | @@ -113,7 +116,10 @@ The name is converted to uppercase for the environment variable (e.g., `web` bec ### Limits -You can configure up to **4 named ports** per environment. +Port limits depend on whether ports are proxied (default) or non-proxied: + +- **Proxied ports** (default): up to **10** per environment. These share a single internal port slot via multiplexing. +- **Non-proxied ports** (`proxied: false`): up to **1** per environment. Each non-proxied port consumes a dedicated port slot. ### Initial Path @@ -189,6 +195,35 @@ Invalid examples: - **Admin panels**: Serve an admin interface on `admin.localhost:3000` while the main app runs on the root domain - **Subdomain APIs**: Frameworks like Rails can use `api.localhost:3000` to route API requests to a separate controller namespace +### Direct Port Access (Non-Proxied) + +By default, all ports are proxied through an authentication layer that validates requests before forwarding them to your application. Setting `proxied: false` bypasses this proxy and exposes the port directly on the sandbox domain. + +```yaml +ports: + - name: WEB + port: 3000 + - name: METRICS + port: 9090 + proxied: false +``` + +Use `proxied: false` when you need: + +- **Direct socket access** for protocols that don't work well through the HTTP proxy +- **Internal services** that handle their own authentication or don't need external access control + +:::warning[Warning] +When `proxied` is `false`, the port is **completely exposed without authentication**, regardless of the `unauthenticated` setting. Only use this for ports that either handle their own security or don't serve sensitive content. +::: + +The `ROO__HOST` environment variable for a non-proxied port points to the direct sandbox domain instead of the preview proxy URL. Your application code doesn't need to change -- just use the injected variable as usual: + +```typescript +// Works the same whether the port is proxied or not +const metricsUrl = process.env.ROO_METRICS_HOST || 'http://localhost:9090'; +``` + ## Using Environment Variables in Your Code Use the `ROO__HOST` variables instead of hardcoded URLs so your services can find each other in both preview and local environments: From a830bba52385bc725b0cfc697a511c3d4fac00ce Mon Sep 17 00:00:00 2001 From: Roo Code Date: Wed, 18 Feb 2026 20:44:15 +0000 Subject: [PATCH 2/6] docs: strengthen proxied: false as last-resort, recommend unauthenticated: true first --- docs/roo-code-cloud/environments.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index b3ef082f..97fb4978 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -197,7 +197,11 @@ Invalid examples: ### Direct Port Access (Non-Proxied) -By default, all ports are proxied through an authentication layer that validates requests before forwarding them to your application. Setting `proxied: false` bypasses this proxy and exposes the port directly on the sandbox domain. +By default, all ports are proxied through an authentication layer that validates requests before forwarding them to your application. Setting `proxied: false` bypasses this proxy entirely and exposes the port directly on the sandbox domain. + +:::tip[Try `unauthenticated: true` first] +If you just need to skip authentication (e.g., for a public-facing endpoint or webhook), use `unauthenticated: true` instead. It keeps the proxy in place while disabling the auth check, and doesn't count against the stricter non-proxied port limit. Only reach for `proxied: false` when the proxy itself is the problem. +::: ```yaml ports: @@ -208,13 +212,13 @@ ports: proxied: false ``` -Use `proxied: false` when you need: +Use `proxied: false` only when the proxy layer itself is incompatible with your use case: -- **Direct socket access** for protocols that don't work well through the HTTP proxy -- **Internal services** that handle their own authentication or don't need external access control +- **Direct socket access** for protocols that don't work through the HTTP proxy +- **Non-HTTP services** that need the raw port exposed without any intermediary :::warning[Warning] -When `proxied` is `false`, the port is **completely exposed without authentication**, regardless of the `unauthenticated` setting. Only use this for ports that either handle their own security or don't serve sensitive content. +When `proxied` is `false`, the port is **completely exposed without authentication**, regardless of the `unauthenticated` setting. Non-proxied ports also count against a stricter limit (1 per environment vs. 10 for proxied ports). Only use this as a last resort when other options don't work. ::: The `ROO__HOST` environment variable for a non-proxied port points to the direct sandbox domain instead of the preview proxy URL. Your application code doesn't need to change -- just use the injected variable as usual: From 7752e62d0a7cdf34613abd17aa31c3c26df8ccb2 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Wed, 18 Feb 2026 20:46:22 +0000 Subject: [PATCH 3/6] docs: add unauthenticated: true documentation for public ports --- docs/roo-code-cloud/environments.mdx | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index 97fb4978..ec1d8222 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -93,6 +93,7 @@ ports: |-------|-------------|----------| | `name` | Identifier for the port (used to generate environment variables) | Yes | | `port` | The port number to expose | Yes | +| `unauthenticated` | Skip authentication for this port's preview URL (`false` by default). See [Public Ports](#public-ports-unauthenticated) | No | | `proxied` | Whether traffic goes through the auth proxy (`true` by default). Set to `false` for direct port access (see [Direct Port Access](#direct-port-access-non-proxied)) | No | | `initial_path` | Default path to append to the preview URL | No | | `subdomain` | Subdomain to set on the `Host` header when forwarding requests to the app | No | @@ -195,6 +196,28 @@ Invalid examples: - **Admin panels**: Serve an admin interface on `admin.localhost:3000` while the main app runs on the root domain - **Subdomain APIs**: Frameworks like Rails can use `api.localhost:3000` to route API requests to a separate controller namespace +### Public Ports (Unauthenticated) + +By default, all preview URLs require authentication -- visitors must be signed in to your Roo Code Cloud organization to access them. Setting `unauthenticated: true` on a port disables this auth check while keeping the proxy layer intact. + +```yaml +ports: + - name: DOCS + port: 4000 + unauthenticated: true + - name: WEBHOOK + port: 3002 + unauthenticated: true +``` + +Use `unauthenticated: true` when you need: + +- **Public-facing endpoints** like documentation sites or landing pages +- **Webhook receivers** that need to accept requests from external services (e.g., Stripe, GitHub) +- **Health checks** or status pages accessed by monitoring tools + +The port still goes through the proxy, so it benefits from HTTPS termination and domain routing. Only the authentication requirement is removed. + ### Direct Port Access (Non-Proxied) By default, all ports are proxied through an authentication layer that validates requests before forwarding them to your application. Setting `proxied: false` bypasses this proxy entirely and exposes the port directly on the sandbox domain. From e14c32a88bc665584a76c13e0e949e034e483016 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Wed, 18 Feb 2026 20:49:39 +0000 Subject: [PATCH 4/6] docs: fix proxied: false use cases to reflect HTTPS-only sandbox --- docs/roo-code-cloud/environments.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index ec1d8222..7eb7e2cd 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -237,8 +237,8 @@ ports: Use `proxied: false` only when the proxy layer itself is incompatible with your use case: -- **Direct socket access** for protocols that don't work through the HTTP proxy -- **Non-HTTP services** that need the raw port exposed without any intermediary +- **WebSocket or streaming connections** that are disrupted by the proxy intermediary +- **Services with custom connection handling** that conflict with the proxy's request processing :::warning[Warning] When `proxied` is `false`, the port is **completely exposed without authentication**, regardless of the `unauthenticated` setting. Non-proxied ports also count against a stricter limit (1 per environment vs. 10 for proxied ports). Only use this as a last resort when other options don't work. From 43547a9a59f6aec73ec5db245e34311c38627b78 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Wed, 18 Feb 2026 20:52:13 +0000 Subject: [PATCH 5/6] docs: add API endpoints as primary unauthenticated use case --- docs/roo-code-cloud/environments.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index 7eb7e2cd..5ba8c6eb 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -212,8 +212,9 @@ ports: Use `unauthenticated: true` when you need: -- **Public-facing endpoints** like documentation sites or landing pages +- **API endpoints** that your frontend or external clients call directly (the auth proxy would otherwise block non-browser requests) - **Webhook receivers** that need to accept requests from external services (e.g., Stripe, GitHub) +- **Public-facing endpoints** like documentation sites or landing pages - **Health checks** or status pages accessed by monitoring tools The port still goes through the proxy, so it benefits from HTTPS termination and domain routing. Only the authentication requirement is removed. From 2aec93957591046908bb5ca8ef48e371a3ce87c3 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Wed, 18 Feb 2026 20:52:46 +0000 Subject: [PATCH 6/6] docs: add API port to unauthenticated example --- docs/roo-code-cloud/environments.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index 5ba8c6eb..b334ad40 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -202,8 +202,10 @@ By default, all preview URLs require authentication -- visitors must be signed i ```yaml ports: - - name: DOCS - port: 4000 + - name: WEB + port: 3000 + - name: API + port: 3001 unauthenticated: true - name: WEBHOOK port: 3002