Publish an App on Flower Hub¶

Have you built an exciting federated app? Now it’s time to share it with the world! Contributing your federated learning app to Flower Hub allows you to share your work with the community, receive feedback, and enable others to build on top of your contributions.

There are no restrictions on the type of federated apps you can publish. Whether you’ve developed:

  • A new federated learning algorithm

  • A novel real-world application

  • A federated agent

  • An implementation accompanying a research paper

  • A benchmark

  • A tool that enhances the federated learning ecosystem

We welcome your contribution!

Build Your App¶

If you’re unsure what to contribute, start by exploring the available apps on Flower Hub, and see if you can add a new app that is not yet present or if you can improve an existing one. A good starting point is @flwrlabs/quickstart-pytorch, which provides a simple example of a Flower app structure.

Simulation vs. Deployment¶

Your app should run in both Simulation and Deployment runtimes without requiring code changes.

To achieve this, implement separate data-loading logic for each mode while keeping the training logic identical.

One way to distinguish between Simulation and Deployment is using context.node_config inside your ClientApp. If the keys "partition-id" and "num-partitions" are present, the app is running in Simulation mode.

Example:

@app.train()
def train(msg: Message, context: Context):
    """Train the model on local data."""

    batch_size = context.run_config["batch-size"]

    if (
        "partition-id" in context.node_config
        and "num-partitions" in context.node_config
    ):
        # Simulation Engine: partition data on the fly
        partition_id = context.node_config["partition-id"]
        num_partitions = context.node_config["num-partitions"]
        trainloader, _ = load_sim_data(
            partition_id, num_partitions, batch_size
        )
    else:
        # Deployment Engine: load demo or real user data
        data_path = context.node_config["data-path"]
        trainloader, _ = load_local_data(data_path, batch_size)

    # Training logic continues identically for both modes

Tip

Recommendations:

  • For Simulation, use Flower Datasets to partition data on the fly.

  • For Deployment, generate demo data using the CLI command flwr-datasets create (see the deployment data guide for details).

Note

The app’s README should clearly document the following:

  • For Simulation, specify how many virtual SuperNodes are expected and whether modifications to the Flower Configuration are required.

  • For Deployment, explain how to generate synthetic data using flwr-datasets create. If the app relies on externally provided data, describe how users can obtain it and how it should be formatted before running the app.

Update App Metadata¶

Before publishing your app, ensure that its metadata is complete and accurate. This information is defined in pyproject.toml and is used by Flower Hub to display and identify your application.

Under [project], provide:

  • name — the app’s unique name

  • version — the current release version

  • description — a short summary of the app

  • license — the applicable software license

Under [tool.flwr.app], specify:

  • publisher — your Flower account username

Example:

[project]
name = "my-federated-app"
version = "0.1.0"
description = "Federated training for medical image classification."
license = "Apache-2.0"

[tool.flwr.app]
publisher = "your-username"  # Must match your Flower account username

License Field Formats¶

Flower Hub accepts [project].license in the following forms:

# SPDX identifier (string)
license = "Apache-2.0"

# Inline text
license = { text = "Apache-2.0" }

# File reference (must be at the project root)
license = { file = "LICENSE" }
# or
license = { file = "LICENSE.md" }

Rules:

  • file and text cannot be set together.

  • If you use license.file, it must be exactly LICENSE or LICENSE.md.

  • The referenced license file must exist and be included in the files uploaded by flwr app publish.

Warning

The name and description are publicly visible on Flower Hub. Choose them carefully to ensure your app is clear, descriptive, and easy to discover. The name cannot be changed after the first publication, so make sure it is final before releasing your app.

Note

Flower Hub currently supports the following file formats: .py, .toml, and .md. As a special case for licensing, a root-level LICENSE file is also supported. Before publishing, ensure that all required files for your app (e.g., source code, metadata, README) are included in the app directory.

Support for additional file formats is planned for future releases.

Create a Flower Account¶

If you don’t already have one, create a Flower account at: https://flower.ai/.

Click Sign Up in the top-right corner and follow the instructions. Make sure the username is the same as the publisher name defined in your app’s pyproject.toml.

Publishing on behalf of an organization?¶

Since organization accounts are not yet officially supported, please:

  • Create a standard user account

  • Use your organization’s name as the username (e.g., flwrlabs)

  • Update your profile with the appropriate logo and description

Note

Organization accounts will be migrated once official organization support becomes available.

Publish Your App on Flower Hub¶

Apps are published using the Flower CLI.

First, ensure flwr is installed:

pip install flwr

Next, log in to your SuperLink connection that points to SuperGrid:

flwr login supergrid

This will open a browser window where you can authenticate using your Flower account.

Note

To login to SuperGrid it is expected that your Flower Configuration has a SuperLink connection named superlink.supergrid with the address supergrid.flower.ai. This connection should be present by default after intalling Flower. Read more about SuperLink connections and how to configure them in the Flower Configuration documentation.

After logging in, publish your app:

flwr app publish <your-app-path>

Note

flwr app publish uploads your project files (source + metadata), not a prebuilt .fab file. Flower Hub builds the FAB server-side from the uploaded project contents. This means publish upload rules and FAB packaging rules are related but not identical. For details on FAB packaging, see the Flower Framework CLI reference for flwr build: https://flower.ai/docs/framework/ref-api-cli.html.

🎉 That’s it! Your app is now live on Flower Hub.

You can view it at:

https://flower.ai/apps/<account_name>/<app_name>/

Publish a New Version of Your App¶

Published apps cannot be removed from Flower Hub. However, you can release updated versions of your app to introduce improvements, new features, or bug fixes.

To publish a new version:

  1. Make the necessary changes to your app’s source code.

  2. Update the version field under [project] in pyproject.toml.

For example, if the current version is 0.1.0, you might update it to:

  • 0.1.1 for a bug fix (patch release)

  • 0.2.0 for new features (minor release)

  • 1.0.0 for major changes

After updating the version number, publish the new release using the same command:

flwr app publish <your-app-path>

The new version will be published alongside previous versions, allowing users to reference and run specific releases as needed.

We encourage you to share your app with colleagues and on social media to help grow the Flower Hub ecosystem and make federated AI more accessible to everyone.