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 1 commit
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
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` |

### 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