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

Draft
roomote wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: add initial_path configuration for preview environment ports #519

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
45 changes: 44 additions & 1 deletion 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: ADMIN, port: 3002, initial_path: /dashboard` | `ROO_ADMIN_HOST` | `https://ghi789.vercel.run/dashboard` |
Copy link
Contributor Author

@roomote roomote bot Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table row shows ROO_ADMIN_HOST including the path (/dashboard), but the text description below (lines 118 and 129) states that initial_path only affects the "preview link" and "preview URL provided in the UI and task" - not the environment variable. If the env var actually includes the path, the CORS code examples elsewhere in this doc (lines 385-393) would break since CORS origins don't include paths. If initial_path only affects the UI preview URL, this row should show https://ghi789.vercel.run without the path.

Fix it with Roo Code or mention @roomote and request a fix.


### Naming Rules

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