how-to-run-flower-locally.rst

og:description:	Learn how local flwr run uses a managed local SuperLink, how to inspect runs, stream logs, stop runs, and stop the background local SuperLink process.

Run Flower Locally with a Managed SuperLink

When you use a local profile in the :doc:`Flower configuration <ref-flower-configuration>` with options.* and no explicit address, flwr does not call the simulation runtime directly. Instead, Flower starts a managed local flower-superlink on demand, submits the run through the Control API, and the local SuperLink executes the run with the simulation runtime.

This is the default experience for a profile like the one created automatically in your Flower configuration:

[superlink.local]
options.num-supernodes = 10
options.backend.client-resources.num-cpus = 1
options.backend.client-resources.num-gpus = 0

If FLWR_HOME is unset, Flower stores this managed local runtime under $HOME/.flwr/local-superlink.

What Flower starts for you

On the first command that needs the local Control API, Flower starts a local flower-superlink process automatically. That process:

• listens on 127.0.0.1:39093 for the Control API
• listens on 127.0.0.1:39094 for SimulationIO
• keeps running in the background after your command finishes
• is reused by later flwr run, flwr list, flwr log, and flwr stop commands

You can override those default ports with the environment variables FLWR_LOCAL_CONTROL_API_PORT and FLWR_LOCAL_SIMULATIONIO_API_PORT.

Submit a run

From your Flower App directory, submit a run as usual:

$ flwr run .

Representative output:

Successfully built flwrlabs.myapp.1-0-0.014c8eb3.fab
Starting local SuperLink on 127.0.0.1:39093...
Successfully started run 1859953118041441032

Plain flwr run . submits the run, prints the run ID, and returns. If you want to submit the run and immediately follow the logs in the same terminal, use:

$ flwr run . --stream

List runs

To see all runs known to the local SuperLink:

$ flwr list

To inspect one run in detail:

$ flwr list --run-id 1859953118041441032

View logs

To stream logs continuously:

$ flwr log 1859953118041441032 --stream

To fetch the currently available logs once and return:

$ flwr log 1859953118041441032 --show

Representative streamed output:

INFO :      Starting FedAvg strategy:
INFO :          Number of rounds: 3
INFO :      [ROUND 1/3]
INFO :      configure_train: Sampled 5 nodes (out of 10)
INFO :      aggregate_train: Received 5 results and 0 failures
...

Stop a run

To stop a submitted or running run:

$ flwr stop 1859953118041441032

This stops the run only. It does not stop the background local SuperLink process.

Local runtime files and state

The managed local SuperLink keeps its files in $FLWR_HOME/local-superlink/:

• state.db stores the local SuperLink state
• ffs/ stores SuperLink file artifacts
• superlink.log stores the local SuperLink process output

These files persist across local runs until you remove them yourself.

Stop the background local SuperLink

There is currently no dedicated flwr command to stop the managed local SuperLink process. To stop it, first inspect the matching process and then terminate it.

macOS/Linux

Inspect the process:

$ ps aux | grep '[f]lower-superlink.*--control-api-address 127.0.0.1:39093'

Stop the process:

$ pkill -f 'flower-superlink.*--control-api-address 127.0.0.1:39093'

Windows PowerShell

Inspect the process:

PS> Get-CimInstance Win32_Process |
>>   Where-Object {
>>     $_.CommandLine -like '*flower-superlink*--control-api-address 127.0.0.1:39093*'
>>   } |
>>   Select-Object ProcessId, CommandLine

Stop the process:

PS> Get-CimInstance Win32_Process |
>>   Where-Object {
>>     $_.CommandLine -like '*flower-superlink*--control-api-address 127.0.0.1:39093*'
>>   } |
>>   ForEach-Object { Stop-Process -Id $_.ProcessId }

If you changed the local Control API port with FLWR_LOCAL_CONTROL_API_PORT, replace 39093 in the commands above.

Troubleshooting

If a local run fails before it starts, or if the managed local SuperLink does not come up correctly, inspect:

$FLWR_HOME/local-superlink/superlink.log

That log contains the output of the background flower-superlink process and is the first place to check for startup errors, port conflicts, or runtime failures.