feat: support configurable worktree label placement for multi-service hostnames
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.localhostThese hostnames do not have a worktree-specific common parent domain. A session cookie shared by Web and API must use:
Domain=enterprise-agentic-saas.localhostwhich 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.localhostThe Web and API can then share:
Domain=feature-auth.enterprise-agentic-saas.localhostwithout sharing the session cookie with another worktree.
Possible interface
A CLI/environment option identifying the stable base suffix, for example:
PORTLESS_WORKTREE_BASE=enterprise-agentic-saasor:
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.
Source: vercel-labs/portless