From 83c7d302708e31e67e84c182bf09c07ccfa1cef5 Mon Sep 17 00:00:00 2001 From: Roo Code Date: Fri, 30 Jan 2026 16:14:30 +0000 Subject: [PATCH 1/2] docs: add initial_path configuration for preview environment ports --- docs/roo-code-cloud/environments.mdx | 45 +++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index ba87ac1d..eebac8e8 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -12,6 +12,7 @@ keywords: - Detached Commands - Tool Versions - mise + - Initial Path --- # Preview Environments @@ -80,15 +81,24 @@ ports: port: 3001 - name: ADMIN port: 3002 + initial_path: /dashboard ``` +### Port Configuration Fields + +| Field | Description | Required | +|-------|-------------|----------| +| `name` | Identifier for the port (used to generate environment variables) | Yes | +| `port` | The port number to expose | Yes | +| `initial_path` | Default path to append to the preview URL | No | + For each named port, an environment variable is injected into your container: | Port Config | Environment Variable | Example Value | |-------------|---------------------|---------------| | `name: WEB, port: 3000` | `ROO_WEB_HOST` | `https://abc123.vercel.run` | | `name: API, port: 3001` | `ROO_API_HOST` | `https://def456.vercel.run` | -| `name: ADMIN, port: 3002` | `ROO_ADMIN_HOST` | `https://ghi789.vercel.run` | +| `name: ADMIN, port: 3002, initial_path: /dashboard` | `ROO_ADMIN_HOST` | `https://ghi789.vercel.run/dashboard` | ### Naming Rules @@ -103,6 +113,39 @@ The name is converted to uppercase for the environment variable (e.g., `web` bec You can configure up to **4 named ports** per environment. +### Initial Path + +Use `initial_path` to specify the default URL path for a port's preview link. This is useful when your application's entry point isn't at the root path. + +For example, if your app requires authentication and the login page is at `/login`: + +```yaml +ports: + - name: WEB + port: 3000 + initial_path: /login +``` + +When the environment starts, the preview URL provided in the UI and task will be `https://abc123.vercel.run/login` instead of the root URL. + +#### Validation Rules + +The `initial_path` must: +- Start with a forward slash (`/`) +- Be a valid URI path (no query strings or fragments) +- Contain only valid URI characters + +Valid examples: +- `/login` +- `/dashboard` +- `/api/v1/health` +- `/app/projects/123` + +Invalid examples: +- `login` (missing leading slash) +- `/path?query=1` (contains query string) +- `/path#section` (contains fragment) + ## 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 6619e59df1187cc5b31fad2614c9de5eedd5286d Mon Sep 17 00:00:00 2001 From: Roo Code Date: Fri, 6 Feb 2026 03:07:56 +0000 Subject: [PATCH 2/2] docs: align initial_path docs with cloud implementation - Fix validation rules: query params and hash fragments are allowed - Fix domain names: keep preview.roocode.cloud (revert vercel.run changes) - Fix env var table: ROO_*_HOST contains base URL only, not initial_path - Add note clarifying initial_path only affects UI preview links - Update examples to include query params and hash fragments --- docs/roo-code-cloud/environments.mdx | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/roo-code-cloud/environments.mdx b/docs/roo-code-cloud/environments.mdx index eebac8e8..1dec0c82 100644 --- a/docs/roo-code-cloud/environments.mdx +++ b/docs/roo-code-cloud/environments.mdx @@ -96,9 +96,9 @@ For each named port, an environment variable is injected into your container: | Port Config | Environment Variable | Example Value | |-------------|---------------------|---------------| -| `name: WEB, port: 3000` | `ROO_WEB_HOST` | `https://abc123.vercel.run` | -| `name: API, port: 3001` | `ROO_API_HOST` | `https://def456.vercel.run` | -| `name: ADMIN, port: 3002, initial_path: /dashboard` | `ROO_ADMIN_HOST` | `https://ghi789.vercel.run/dashboard` | +| `name: WEB, port: 3000` | `ROO_WEB_HOST` | `https://abc123.preview.roocode.cloud` | +| `name: API, port: 3001` | `ROO_API_HOST` | `https://def456.preview.roocode.cloud` | +| `name: ADMIN, port: 3002` | `ROO_ADMIN_HOST` | `https://ghi789.preview.roocode.cloud` | ### Naming Rules @@ -126,25 +126,28 @@ ports: initial_path: /login ``` -When the environment starts, the preview URL provided in the UI and task will be `https://abc123.vercel.run/login` instead of the root URL. +When the environment starts, the preview URL provided in the UI and task will be `https://abc123.preview.roocode.cloud/login` instead of the root URL. + +:::note +The `ROO__HOST` environment variable always contains the base URL without the initial path (e.g., `https://abc123.preview.roocode.cloud`). The `initial_path` only affects the preview link shown in the UI. +::: #### Validation Rules The `initial_path` must: - Start with a forward slash (`/`) -- Be a valid URI path (no query strings or fragments) - Contain only valid URI characters -Valid examples: +Query parameters and hash fragments are allowed. Valid examples: - `/login` - `/dashboard` - `/api/v1/health` - `/app/projects/123` +- `/login?redirect=home` +- `/docs#getting-started` Invalid examples: - `login` (missing leading slash) -- `/path?query=1` (contains query string) -- `/path#section` (contains fragment) ## Using Environment Variables in Your Code @@ -366,7 +369,7 @@ After the environment starts, you'll get unique URLs for each port. Visit the WE ### CORS Errors -In a preview environment, your frontend and backend run on different domains (e.g., `https://abc123.vercel.run` and `https://def456.vercel.run`). Browsers block cross-origin requests by default, so you need to configure both sides: the backend must allow the frontend's origin, and the frontend dev server must accept the preview domain. +In a preview environment, your frontend and backend run on different domains (e.g., `https://abc123.preview.roocode.cloud` and `https://def456.preview.roocode.cloud`). Browsers block cross-origin requests by default, so you need to configure both sides: the backend must allow the frontend's origin, and the frontend dev server must accept the preview domain. Make sure both ports are defined so the `ROO_*_HOST` variables get injected: @@ -399,7 +402,7 @@ app.register(import('@fastify/cors'), { #### Frontend: Allow the preview domain -Dev servers like Vite and Next.js reject requests from unrecognized hosts by default. You need to allow the preview domain so the dev server responds to requests on `https://.vercel.run`: +Dev servers like Vite and Next.js reject requests from unrecognized hosts by default. You need to allow the preview domain so the dev server responds to requests on `https://.preview.roocode.cloud`: ```typescript // Vite — vite.config.ts