Provision command

Running nvflare provision -h shows all available options.

usage: nvflare provision [-h] [-p PROJECT_FILE] [-g] [-e] [-w WORKSPACE]
                         [-c CUSTOM_FOLDER] [--add_user ADD_USER]
                         [--add_client ADD_CLIENT] [-s] [--force] [--schema]

options:
-h, --help                                               show this help message and exit
-p PROJECT_FILE, --project_file PROJECT_FILE                 file to describe FL project
-g, --generate                                             generate a sample project.yml and exit
-e, --gen_edge                                             generate a sample edge project.yml and exit
-w WORKSPACE, --workspace WORKSPACE                          directory used by provision
-c CUSTOM_FOLDER, --custom_folder CUSTOM_FOLDER    additional folder to load python code
--add_user ADD_USER                                             yaml file for added user
--add_client ADD_CLIENT                                       yaml file for added client
-s, --gen_scripts                                            generate helper scripts such as start_all.sh
--force                                                      skip Y/N confirmation prompts
--schema                                                     print command schema as JSON and exit

Running provision without any options and without a project.yml file in the current working directory will prompt to copy a default project.yml to the current working directory.

JSON mode

nvflare provision --format json returns only a JSON envelope on stdout. When the command generates a sample project file, the JSON data section includes structured guidance such as:

• message

• next_step

• suggested_command

This keeps JSON output machine-readable while still carrying follow-up instructions.

Certificate Identity Overrides

For mTLS deployments, each CellNet endpoint is authenticated against the peer certificate common name (CN). By default, the expected certificate identity is derived from the participant name or FQCN. If a participant intentionally uses a certificate CN that differs from its FLARE site name, set auth_identity in project.yml before provisioning.

For example, if the FLARE site is named site-1 but its certificate CN is server.example.com:

participants:
  - name: site-1
    type: client
    org: nvidia
    auth_identity: server.example.com

Provisioning uses this value to generate the corresponding startup-kit configuration, including peer identity mappings needed by the server and by job cells. A job cell such as site-1.<job_id> still authenticates with the parent site’s configured certificate identity.

Important

Endpoint-to-CN binding is enforced when an mTLS transport exposes the authenticated peer CN. Some active-side gRPC connections do not expose the peer CN to the Python driver, so NVFlare accepts those active connections and relies on passive-side endpoint validation plus the normal application-layer authentication checks.

Admin console cells use per-session endpoint names and authenticate the admin user by certificate/user identity on the admin listener. Keep admin application-layer authentication configured and protected.

auth_identity is loaded when a FLARE process starts. After rotating site certificates or changing certificate CNs, regenerate the startup kits as needed and restart the affected FLARE processes so the in-memory identity resolver uses the new certificate identity.

Warning

Do not edit startup/fed_client.json or startup/fed_server.json by hand in a signed startup kit. If startup/signature.json is present, the startup configuration is covered by the signature and manual edits invalidate that signature. Change project.yml and re-run provisioning so the startup configuration and signature are generated together.

Dynamic Provisioning

The options --add_user and --add_client allow for adding to an existing project. Both of these commands take a yaml file to define the additional participant to provision.

Sample user.yaml for --add_user:

name: new_user@nvidia.com
org: nvidia
role: project_admin

Sample client.yaml for --add_client:

name: new-site
org: nvidia
components:
  resource_manager:    # This id is reserved by system.  Do not change it.
    path: nvflare.app_common.resource_managers.gpu_resource_manager.GPUResourceManager
    args:
      num_of_gpus: 0
      mem_per_gpu_in_GiB: 0
  resource_consumer:    # This id is reserved by system.  Do not change it.
    path: nvflare.app_common.resource_consumers.gpu_resource_consumer.GPUResourceConsumer
    args:

After running nvflare provision with --add_user or --add_client followed by the name of the yaml file (nvflare.lighter.provision will look for the yaml file in the current directory), the new user or client will be included in the prod_NN folder.

To permanently include users or clients, please update the project.yml.

Note

To use multi-study features, set api_version: 4 in your project.yml and add a studies: section. See Multi-Study Support for details.