: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.
.. meta::
    :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:

.. code-block:: toml

    [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:

.. code-block:: shell

    $ flwr run .

Representative output:

.. code-block:: text

    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:

.. code-block:: shell

    $ flwr run . --stream

***********
 List runs
***********

To see all runs known to the local SuperLink:

.. code-block:: shell

    $ flwr list

To inspect one run in detail:

.. code-block:: shell

    $ flwr list --run-id 1859953118041441032

***********
 View logs
***********

To stream logs continuously:

.. code-block:: shell

    $ flwr log 1859953118041441032 --stream

To fetch the currently available logs once and return:

.. code-block:: shell

    $ flwr log 1859953118041441032 --show

Representative streamed output:

.. code-block:: text

    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:

.. code-block:: shell

    $ 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:

.. code-block:: shell

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

Stop the process:

.. code-block:: shell

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

Windows PowerShell
==================

Inspect the process:

.. code-block:: powershell

    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:

.. code-block:: powershell

    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:

.. code-block:: text

    $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.