feat(daemons): give each daemon a stable URL per git worktree

[jdx]

https://entire.io/gh/jdx/mise/trails/24

The problem

port = "auto" lets several git worktrees of one project run their daemons at
once, but it leaves every service having to be told which port its neighbours
ended up on. That is fine for a database and painful for HTTP services, which is
most of a stack.

Pitchfork's reverse proxy removes that step: it routes a stable hostname to
whatever port a daemon actually bound. This teaches mise to derive the same
hostname while configuration loads, and to export it, so nothing in the project
has to do port arithmetic.

What you get

Every daemon that configures a port is reachable at a hostname, and mise
exports it as <NAME>_URL beside the existing <NAME>_PORT:

[daemons_settings]
namespace = "shop"

[daemons.api]
run = "npm run dev"
port = "auto"

[daemons.postgres]
preset = "postgres"
version = "18"
port = "auto"

[env]
APP_BASE_URL = "{{ env.API_URL }}"

In ~/src/shop that gives API_URL=https://api.shop.localhost. A linked
worktree at ~/src/shop-pr-42 gives
API_URL=https://api.shop-pr-42.shop.localhost. Both run at once, and neither
URL changes when a port moves.

Databases keep port = "auto". The proxy speaks HTTP and a Postgres or Redis
client does not, so the postgres and redis presets opt out of it and keep
exporting PGPORT, DATABASE_URL, and REDIS_URL unchanged.

New declaration keys

Two per-daemon keys, validated by mise and forwarded to pitchfork:

# https://front.shop.localhost rather than https://web.…
[daemons.web]
run = "npm run dev"
port = 5173
proxy = "front"

# No hostname, no WORKER_URL; reachable on its port only.
[daemons.worker]
run = "npm run worker"
port = 9000
proxy = false

# The daemon serves TLS itself; the proxy should not break the connection.
[daemons.secure]
run = "npm run dev:https"
port = 3000
proxy_tls = "passthrough"

proxy takes a DNS label, false, or true (the name-derived label, which is
how a preset's proxy = false is turned back on). proxy_tls takes
"terminate" (the proxy's behaviour today) or "passthrough". Both are
rejected at config load with a message naming the daemon when they are not one
of those.

Seeing the URLs

$ mise daemons urls
~/src/shop-pr-42
Daemon         URL                                 Port  Proxy        Status
shop/api       https://api.pr-42.shop.localhost    3117  terminate    running
shop/web       https://front.pr-42.shop.localhost  5173  passthrough  running
shop/postgres  -                                   5679  off          running
  stack:   https://pr-42.shop.localhost
  project: https://shop.localhost

The proxy column is the daemon's proxy_tls mode, or off when it has no
hostname. Such a daemon is listed with its port alone rather than omitted, so a
database is visible here too. mise daemons ls --json gains host, url,
proxy, and root.

Keeping in step with pitchfork

Every hostname here is derived the way pitchfork #880
derives it, because mise exporting a URL the proxy does not serve is worse than
exporting nothing:

• The primary checkout has no worktree component: api.shop.localhost. Only a
  linked worktree adds one.
• The project component is the explicit [daemons_settings] namespace before
  any per-worktree suffix, otherwise the primary checkout's directory name.
• The worktree component is the linked worktree's directory name, or
  worktree_label from a pitchfork config in that checkout, which is where
  #880 reads it. mise reads it from the same place.
• A bare repository has no primary checkout to name the project, so each
  worktree beside it names itself and gets no worktree component:
  api.main.localhost, not api.main.shop.localhost. The directory holding a
  bare repository often holds unrelated ones too, and #880 declines to put them
  on one label for the same reason.
• Only a daemon with a port is routed.
• Labels fold to lowercase letters, digits and -, by the same rules. A
  collision routes neither side, so mise withholds both URLs and warns.
• A hostname that will not fit in 253 bytes with the configured TLD is refused.

The scheme, TLD and port come from /etc/pitchfork/config.toml and
~/.config/pitchfork/config.toml with PITCHFORK_PROXY_* taking precedence,
parsed as pitchfork parses them, including its case-insensitive boolean
spellings. With no pitchfork configuration at all, mise assumes pitchfork's
defaults, so a URL exists before the proxy is enabled.

Adoption

Experimental, with the rest of [daemons]. Hostname routing needs the pitchfork
release that carries #880; the generated config says so in a comment. An older
supervisor starts the daemons normally and does not serve the hostnames.

Set proxy = false on a custom daemon that does not speak HTTP. A
hand-written [daemons.redis] with a port would otherwise get an https://
hostname and a REDIS_URL pointing at it, which is not what a Redis client
expects. The database presets already do this; the docs say so where the keys
are introduced.

Known divergence

The project component agrees with pitchfork when the project root is the
checkout root and mise has registered the primary checkout. Pitchfork resolves
an explicit namespace from the primary checkout's own configuration or its
registered external configs, so a worktree-only project, or a monorepo root
below the checkout, can still differ. Worth settling alongside #880.

Validation

• cargo test --bin mise daemons — 88 pass. Unit coverage for the primary and
  worktree hostname shapes, a nested monorepo root, worktree_label read from
  the checkout's own config, a portless daemon, proxy = true, proxy = false,
  a declared label, every collision shape, a hostname too long for its TLD, the
  environment and boolean spellings pitchfork accepts, an import not claiming a
  local daemon's variables, a preset export not being replaced, and the
  generated pitchfork config carrying the keys.
• mise run test:e2e e2e/cli/test_daemons passes, including assertions that
  mise env contains API_URL with no worktree component in the main checkout
  and with one in a worktree, that worktree_label in the worktree's
  pitchfork.toml changes it, that a portless daemon gets none, and that the
  generated config carries proxy and proxy_tls.
• cargo clippy --workspace --all-features --all-targets -- -D warnings,
  mise run lint and mise run render are clean.
• e2e/cli/test_daemons_pitchfork fails in my sandbox on an assertion about
  shell session counts. It fails identically on feat(daemons): set a fixed namespace and run daemons from another project #13339's branch without this
  change, so it is not from this work.

Depends on

#13339 and #13347 have landed on main. #13342 is still open, so this branch
merges it; rebase onto main once it lands.

Fixes that belong to #13342 but landed here

Three defects in the port work gated this PR, so they were fixed on this branch
rather than left red. Recording them here so the history is findable if #13342
is read on its own:

• Two daemons in one project could claim one port. ports::resolve derives
  the port from the project root alone, so two instances of one preset share a
  base and land on the same number, and two explicit ports can simply be equal.
  Mise pins what it resolves and sets bump = false, so the second daemon fails
  to bind at start with nothing naming the first. The claims are checked once
  every daemon is built, which is what covers the preset path, and the load
  fails naming both daemons and the port. Keyed by the canonical root, since
  that is what the port was derived from.

  This is a behaviour change: a project declaring two Postgres presets with no
  port override used to load and break at start, and now does not load. Settled
  in review as the right trade, since the daemon cannot run either way and
  check_port_conflicts already errors across projects.

• The conflict check saw only the daemons named directly. Pitchfork starts a
  daemon's dependencies with it, so their ports are bound by the same command. A
  task passed its required daemons, the shell hook passed its auto = ["start"]
  names, and mise daemons start passed what the selectors matched, so a
  dependency could collide with another project unannounced. Each now passes the
  dependency closure it already computes, including for a root reached only
  because something depends on it, which arrives with no recorded ids.

• A dry run validated more than the run would. The real run narrows
  validate_tasks to the dependency closure for a foreign root so an unrelated
  daemon of theirs cannot fail a mise run; the dry_run branch validated that
  root's whole set. It now narrows the same way.

One finding was left for #13342: ports::tests::nested_project_roots_inherit_their_checkout
asserts two random tempdir paths land in different slots out of 511, so it fails
about one run in 511.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added mise daemons urls to display stable daemon URLs, ports, proxy modes, and statuses, with JSON output support.
  • Added cross-project daemon imports with dependency-aware startup and project-scoped selection.
  • Added automatic, persistent port allocation for linked Git worktrees.
  • Added stable hostname routing with configurable namespaces, worktree labels, proxy settings, and TLS modes.

• Documentation

  • Expanded guidance for daemon configuration, imports, ports, worktrees, and hostname routing.

• Bug Fixes

  • Improved daemon validation, dependency handling, namespace updates, and port conflict reporting.

---

Note

Medium Risk
Experimental daemon loading, env exports, and pitchfork registration change behavior (collisions, duplicate ports, dependency port checks); misconfiguration could break multi-worktree stacks until users adjust proxy settings.

Overview
Adds stable per-worktree HTTP URLs for project daemons by deriving pitchfork proxy hostnames at config load and exporting <NAME>_URL next to <NAME>_PORT, so services can reference neighbours without port math.

New per-daemon proxy and proxy_tls settings (schema-validated, forwarded to pitchfork); postgres/redis presets default to proxy = false. Introduces mise daemons urls and extends mise daemons ls --json with host, url, proxy, and root.

Daemon loading now detects hostname and same-project port collisions (warns or fails load), withdraws contested URLs, and includes dependency daemons in port conflict checks on start, hooks, and tasks. Docs, usage spec, man page, and e2e coverage follow.

^{Reviewed by Cursor Bugbot for commit 1d15512. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[jdx]

Both prerequisites have landed and the branch has absorbed their tips, so this is the last one standing. One gate medium is current and I agree with it: the pitchfork-version notice in runtime.rs:676 fires whenever set.labels is non-empty, and build() populates labels for every root, so a project whose daemons are all proxy = false or portless is told hostname routing is in use when nothing got a host. Gate on whether any daemon's urls::apply() produced a host. Merge after that and a final rebase onto main, which now contains #13339 and #13342 as squashes.

AI-assisted review (Claude Code, claude-fable-5-1).

[cursor]

Stale Bugbot comment from a previous run.

[jdx]

The notice is now gated on whether any daemon actually got a host, not on
set.labels. Two more gate mediums came with it: preset_keys counted an
imported preset's exports, which never reach this environment, so a local
daemon lost a variable to a clash that does not happen here; and the stack and
project page URLs skipped the length check a daemon's own hostname gets. Each
fix has a test that fails when the fix is reverted.

Chasing the third one turned up a real divergence from #880 that I had
previously argued was deliberate parity, wrongly. primary_from_worktree_gitdir
refuses a common dir not named .git, so pitchfork gives a worktree of a bare
repository a label of its own rather than naming the project after the
directory holding the bare repos. mise named it after that directory, and was
exporting a hostname pitchfork would never route. It now resolves the case the
same way: api.main.localhost, no worktree component. The PR body and
docs/daemons.md record it.

On the rebase: I merged main instead, and I would rather you overrule me than
have me force-push over a doubt. git rebase origin/main replays 103 commits,
and it conflicted on the third one, in eight files across the daemons feature.
Those are #13339's and #13342's own commits meeting themselves as squashes on
main. Resolving that by hand is how a fix gets silently reverted, and main is
one commit ahead touching only src/github.rs and src/http.rs. I verified
the merge's tree byte for byte against git merge-tree before pushing. Say the
word if you still want the linear history and I will do it.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: 2.1.270.

[cursor]

Stale Bugbot comment from a previous run.

[github-actions]

Instruction counts

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: env on jdx-perf-v1-ubuntu24.04-x64-mise-rust1.97.1-img5263c143, hook-env on jdx-perf-v1-ubuntu24.04-x64-mise-rust1.97.1-img5263c143, ls on jdx-perf-v1-ubuntu24.04-x64-mise-rust1.97.1-img5263c143, registry on jdx-perf-v1-ubuntu24.04-x64-mise-rust1.97.1-img5263c143, startup on jdx-perf-v1-ubuntu24.04-x64-mise-rust1.97.1-img5263c143

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{1d1551273d48 vs 3fed64c07135 · measured on the runner, not pushed to the history.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 083ff2c. Configure here.}