[Feature Request] No per-project SuperLink config support after migration from legacy `pyproject.toml` federations

[CatherineHSU39]

Type

Feature

Description

Framework: flwr Python framework
Component: cli, config
Discovered in: flwr Python package (framework/py/flwr/)
Related files:

• framework/py/flwr/cli/flower_config.py
• framework/py/flwr/cli/config_migration.py
• framework/py/flwr/cli/constant.py

---

Summary

Since [tool.flwr.federations] in pyproject.toml was deprecated in favour of the global
~/.flwr/config.toml, there is no longer a way to configure per-project SuperLink / simulation
settings (e.g. num-supernodes, client-resources) without directly editing the shared
global config file. The legacy system implicitly supported per-project configuration; the new
system does not provide an equivalent.

---

Current Behavior

1. On the first flwr run, if ~/.flwr/config.toml does not exist, it is created with
   hardcoded defaults:

   [superlink]
   default = "local"
   
   [superlink.supergrid]
   address = "<supergrid-address>"
   
   [superlink.local]
   options.num-supernodes = 10
   options.backend.client-resources.num-cpus = 1
   options.backend.client-resources.num-gpus = 0

2. If pyproject.toml contains a legacy [tool.flwr.federations] section, the settings are
   migrated once to ~/.flwr/config.toml and the original section is commented out in
   pyproject.toml with a migration notice.

3. After migration, any further edits to the (now commented-out) pyproject.toml section are
   silently ignored — config.toml is never re-read from pyproject.toml.

4. All Flower projects on the same machine share the same ~/.flwr/config.toml, so changing
   simulation settings for one project silently affects all others.

---

Steps to Reproduce

1. Create two Flower apps that require different simulation settings, e.g.:
   • App A needs num-supernodes = 5, num-cpus = 2
   • App B needs num-supernodes = 50, num-cpus = 0.5
2. Run flwr run for App A — ~/.flwr/config.toml is created/used with whatever the current
   global [superlink.local] settings are.
3. To run App B with different settings, the user must manually edit ~/.flwr/config.toml,
   remember to revert it before switching back to App A, and repeat every time.
4. There is no project-local override mechanism to avoid this.

Planned Implementation

One or more of the following improvements would resolve the friction:

1. Per-project config override — Support a project-local config.toml (e.g. in the
   project root) that is merged over the global
   ~/.flwr/config.toml, similar to how many tools support local + global config layering.
2. Named connection per project — Allow pyproject.toml to declare a preferred
   SuperLink connection name (not the full connection config) so that different projects can
   point to different named entries in the shared ~/.flwr/config.toml.
3. CLI flag — Provide a --config / --connection-config flag on flwr run to point to
   an alternative config file for that invocation.
4. Documentation — At a minimum, clearly document the recommended workflow for developers
   who work on multiple projects with different simulation resource requirements.

Additional Context

• The commenting-out of pyproject.toml after migration is misleading: it looks like the
  settings were "saved", but any future edits to that section have no effect.
• The one-time migration path in config_migration.py (_comment_out_legacy_toml_config)
  effectively removes the user's only familiar touchpoint for per-project config without
  providing a direct replacement.
• Relevant code paths:
  • init_flwr_config() (flower_config.py:153)
    — only writes defaults when config.toml is absent; never syncs from pyproject.toml.
  • migrate() (config_migration.py:171)
    — one-shot migration, called on every flwr run but no-ops once the legacy section is
    gone.
  • DEFAULT_FLOWER_CONFIG_TOML (constant.py:103)
    — hardcoded defaults written on first initialisation.

[WilliamLindskog]

@CatherineHSU39 thanks for opening this!

We'll get back to you as soon as possible on this.

[rwilliamspbg-ops]

This is a critical friction point. Forcing a global ~/.flwr/config.toml effectively treats all federated workloads on a single machine as having identical hardware and scaling requirements, which is rarely the case in research or production.

In the Sovereign-Mohawk-Proto (SMP) project, we addressed this exact "config drift" by moving away from static global files in favor of Project Policy Manifests.

How a Policy-Driven approach (like SMP's) solves this:

Dynamic Resource Binding: Instead of manual edits, SMP uses a Route-Policy Bridge to inject project-specific settings (like num-supernodes or GPU allocations) during the handshake. This allows "App A" and "App B" to coexist on the same machine without constant config.toml rewrites.

Hardware-Rooted Enforcement: By leveraging SMP's TPM 2.0 attestation, we ensure that the simulation settings aren't just suggested—they are cryptographically verified against the host’s actual capabilities. This prevents the "silent failure" scenarios mentioned in the description.

Versioned Configuration: Treating simulation settings as a part of the project repository (as SMP does with its Python SDK integration) ensures that your scaling parameters evolve alongside your model code, rather than being left behind in a commented-out pyproject.toml.

Recommendation for Flower:
Supporting a local config.toml override (Option 1) is a great short-term fix. However, adopting a Manifest-based injection system would allow Flower to support more complex multi-tenant environments where security and resource isolation are paramount.

I’d be happy to share more on how we implemented the Policy Engine in SMP if the maintainers are looking at long-term architectural shifts for SuperLink configuration.