Skip to content

docs: add initial_path configuration for preview environment ports #519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jr merged 2 commits into from
Feb 6, 2026
Merged

docs: add initial_path configuration for preview environment ports #519

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
83c7d30
docs: add initial_path configuration for preview environment ports
roomote Jan 30, 2026
6619e59
docs: align initial_path docs with cloud implementation
roomote Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 51 additions & 5 deletions docs/roo-code-cloud/environments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ keywords:
- Detached Commands
- Tool Versions
- mise
- Initial Path
---

# Preview Environments
Expand Down Expand Up @@ -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: 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

Expand All @@ -103,6 +113,42 @@ 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.preview.roocode.cloud/login` instead of the root URL.

:::note
The `ROO_<NAME>_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 (`/`)
- Contain only valid URI characters

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)

## Using Environment Variables in Your Code

Use the `ROO_<NAME>_HOST` variables instead of hardcoded URLs so your services can find each other in both preview and local environments:
Expand Down Expand Up @@ -323,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:

Expand Down Expand Up @@ -356,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://<id>.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://<id>.preview.roocode.cloud`:

```typescript
// Vite — vite.config.ts
Expand Down