Why mise

PolyForge manages almost nothing itself. Version resolution, installation, PATH shimming, environment variables and task running are all mise’s job. PolyForge is the workspace convention layered on top.

That is a deliberate decision, and it is worth stating why.

One resolver instead of six

The alternative to a universal version manager is a stack of them: pyenv, nvm, rustup, sdkman, gvm, fvm. Each with its own shell hook, its own config file, its own upgrade story, and its own way of breaking after an OS update.

mise replaces all of them with one binary and one config format. For a workspace that is polyglot by definition, that collapse is the whole point — six managers is not six times the work, it is six times the surface area for something to go wrong on a fresh machine.

Declarative, in files you can read

A toolchain in mise is TOML:

.config/mise/conf.d/10-core-tools.toml

[tools]
python = "latest"
go = "latest"
rust = "latest"
node = "latest"

That is auditable, diffable and reviewable. There is no imperative setup script whose current state you have to infer from what it printed last time it ran.

Config that merges, in two directions

This is the property PolyForge is actually built on. mise merges configuration:

1. Within .config/mise/conf.d/ — every fragment loads, alphabetically.
2. Up the directory tree — a config in a parent applies to every child.

Together these give a base toolchain available workspace-wide plus per-language overrides that inherit rather than repeat. That mechanism is described in detail in the conf.d merge model.

What PolyForge adds on top

mise gives you tools. It does not give you a workspace. PolyForge adds:

• a layout — where each language’s projects live,
• a content model — what belongs in the tooling repo and what does not,
• three wrapper commands that are identical across platforms,
• a registry so your work follows you between machines.

Version pinning

Because mise owns resolution, pinning is a mise concern: change a constraint in the relevant conf.d fragment or a nested mise.toml, then run polyforge install. PolyForge never second-guesses the resolver.

The trade-off, honestly

Delegating this much means PolyForge inherits mise’s constraints. The clearest example: mise 2026.6.x does not support includes/import in config files, so PolyForge cannot express its modularity that way and uses the conf.d + tree-merge approach instead. Building on someone else’s guarantees means building only on the ones they actually make.

That is still the right trade. The alternative is maintaining a version manager, which is not what this project is for.