#372·portless

feat: support configurable worktree label placement for multi-service hostnames

Author: ReoHakaseCreated Jul 28, 2026Updated Sep 3, 2026

Problem

Portless currently prepends the worktree label to the complete app name:

<worktree>.<name>.<tld>

For a monorepo with a Web app and sibling services, this produces:

feature-auth.enterprise-agentic-saas.localhost
feature-auth.api.enterprise-agentic-saas.localhost
feature-auth.storybook.ui.enterprise-agentic-saas.localhost

These hostnames do not have a worktree-specific common parent domain. A session cookie shared by Web and API must use:

Domain=enterprise-agentic-saas.localhost

which also sends the cookie to every other worktree.

Desired behavior

Allow the worktree label to be inserted before a configured project/base suffix:

<service>.<worktree>.<project>.<tld>

Example:

feature-auth.enterprise-agentic-saas.localhost
api.feature-auth.enterprise-agentic-saas.localhost
storybook.ui.feature-auth.enterprise-agentic-saas.localhost

The Web and API can then share:

Domain=feature-auth.enterprise-agentic-saas.localhost

without sharing the session cookie with another worktree.

Possible interface

A CLI/environment option identifying the stable base suffix, for example:

bash
PORTLESS_WORKTREE_BASE=enterprise-agentic-saas

or:

bash
portless run \
  --name api.enterprise-agentic-saas \
  --worktree-base enterprise-agentic-saas \
  <command>

When configured, Portless would insert the detected worktree label immediately before that suffix. Names may have zero, one, or multiple service labels.

The existing prefix-first behavior should remain the default when this option is absent.

Expected examples

Name Main checkout Linked worktree feature-auth
enterprise-agentic-saas enterprise-agentic-saas.localhost feature-auth.enterprise-agentic-saas.localhost
api.enterprise-agentic-saas api.enterprise-agentic-saas.localhost api.feature-auth.enterprise-agentic-saas.localhost
storybook.ui.enterprise-agentic-saas storybook.ui.enterprise-agentic-saas.localhost storybook.ui.feature-auth.enterprise-agentic-saas.localhost

portless get and app-running commands should resolve the same layout and retain the existing worktree sanitization and truncation rules.

Current workaround

We resolve the worktree namespace from the base project name, construct each service hostname ourselves, and invoke Portless with the complete direct name. This preserves process wrapping but requires a repository-specific wrapper.

Related issues

  • #68 introduced automatic worktree prefixes.
  • #326 proposes opting out when callers compute the complete name.
  • #97 proposes cookie/header/query-based routing, which is a different routing model.
  • #226 asks about recommended monorepo configuration.