Skip to main content

Federations

A federation is a collaboration between multiple organizations that train a shared model without sharing raw data. Each organization keeps its data on its own devices. During training, devices train locally and send only weight updates to the server — never raw data.

Roles​

The organization that creates the federation is the owner. Organizations that join are members. Both contribute devices and data to training.

Create a federation​

octomil federation create "healthcare-consortium" \
  --description "Cross-hospital federated learning for radiology models"

Invite partner organizations​

The owner invites by organization ID:

octomil federation invite healthcare-consortium \
  --org org_abc123 \
  --org org_def456

Share the federation name out-of-band (email, Slack). Partners need the name to join.

Join a federation​

Each invited organization runs:

octomil federation join healthcare-consortium

Status changes from invited to active. Only active members can train and access shared models.

Verify the roster​

octomil federation members healthcare-consortium
Members of healthcare-consortium (fed_a1b2c3d4):
  org_7f8a9b0c  Acme Health         owner    active
  org_abc123    Metro General        member   active
  org_def456    Valley Medical       member   invited

Share a model​

The model must exist in the owner's registry. Sharing makes it available to all active members:

octomil federation share radiology-v1 --federation healthcare-consortium

Pull and deploy the shared model​

Members pull the model and deploy to their fleet:

octomil pull radiology-v1 --format onnx
octomil deploy radiology-v1 --rollout 100% --group production

The owner deploys to their own fleet the same way. Once deployed, devices can participate in training.

Roles summary​

ActionOwnerMember
Create federationoctomil federation create—
Invite organizationsoctomil federation invite—
Join federation—octomil federation join
Share modeloctomil federation share—
Deploy shared modeloctomil deployoctomil deploy
Start trainingoctomil train start—
Monitor trainingoctomil train statusoctomil train status
Deploy trained modeloctomil deploy --version 2.0.0octomil deploy --version 2.0.0
Set privacy budgetoctomil team set-policyoctomil team set-policy

Concepts​

Shared model — A model linked to a federation via octomil federation share. Visible to all active members for deployment and training. The owner retains full control over the model definition and version history.

Training data — Data that each device trains on locally. Octomil does not host or transfer training data. Only weight updates leave the device.

Federation-scoped aggregation — The server collects weight updates only from active member devices. Per-organization contribution counts are tracked.

Privacy in federations — Each member sets its own differential privacy budget. One member exhausting its budget does not prevent others from continuing. See the Privacy guide.