Port Allocation

Formula

rft allocates ports using a deterministic formula:

allocated_port = base_offset + default_port + worktree_index

Where:

• base_offset — configurable, defaults to 20000
• default_port — the default value from ${VAR:-default} in your compose file
• worktree_index — the 1-based index of the worktree

Example

Given a compose file with:

services:
  frontend:
    ports:
      - "${FRONTEND_PORT:-3000}:3000"
  api:
    ports:
      - "${API_PORT:-8080}:8080"

The allocated ports are:

Custom Offset

Change the base offset in .rftrc.toml:

port_offset = 30000

Or via environment variable:

RFT_PORT_OFFSET=30000 rft start

With port_offset = 30000, the same example produces:

Overflow Fallback

If the calculated port exceeds 65535 (the maximum valid port number), rft falls back to an alternative formula:

fallback_port = default_port + 100 * worktree_index

For example, with a high default port like 60000:

This ensures ports always stay within the valid range.