Rollouts

Deploy model versions gradually to reduce risk. Start at 10%, observe metrics, then increase.

When to use

• Deploying a new model version to production devices
• Rolling out a federated-trained model after experiments
• Any deployment where you want a safety net before full release

Quick start

CLI

octomil deploy radiology-v1 --version 2.0.0 --rollout 10%

Rollout created: rol_x7y8z9
Model: radiology-v1 v2.0.0
Progress: 10% (12 of 124 devices)
Status: active

Python

from octomil import OctomilClient

client = OctomilClient(api_key="edg_...")

rollout = client.rollouts.create(
    model_id="radiology-v1",
    version="2.0.0",
    rollout_percentage=10,
    target_percentage=100,
    increment_step=10,
)
print(f"Rollout {rollout.id}: {rollout.percentage}%")

cURL

curl -X POST https://api.octomil.com/v1/models/radiology-v1/rollouts \
  -H "Authorization: Bearer edg_..." \
  -H "Content-Type: application/json" \
  -d '{
    "version": "2.0.0",
    "rollout_percentage": 10,
    "target_percentage": 100,
    "increment_step": 10
  }'

Advance the rollout

CLI

# Advance by one step (10% → 20%)
octomil rollout advance radiology-v1

# Jump to a specific percentage
octomil rollout set radiology-v1 --percentage 50 --reason "Metrics stable for 24h"

# Full rollout
octomil rollout set radiology-v1 --percentage 100

Python

client.rollouts.advance(model_id="radiology-v1", rollout_id=rollout.id)

client.rollouts.update_percentage(
    model_id="radiology-v1",
    rollout_id=rollout.id,
    percentage=50,
    reason="Metrics stable for 24h",
)

Pause, resume, rollback

# Pause — stops further device assignments
octomil rollout pause radiology-v1

# Resume
octomil rollout resume radiology-v1

# Rollback — reverts all devices to the previous version
octomil rollback radiology-v1 --to-version 1.0.0

Target a device group

Deploy to a specific cohort instead of the full fleet:

octomil deploy radiology-v1 --version 2.0.0 --rollout 10% --group staging

Status lifecycle

pending → active → paused → completed
                 ↘ rolled_back

Options

Option	Default	Description
--rollout	100%	Initial rollout percentage
--target-percentage	100%	Final percentage to reach
--increment-step	10	Percentage increase per advance
--group	all devices	Target a specific device group
--auto-rollback	per policy	Automatically roll back if error threshold exceeded

Recipes

Canary → staged → full:

octomil deploy my-model --version 2.0.0 --rollout 5%
# wait 1 hour, check metrics
octomil rollout set my-model --percentage 25 --reason "Canary clean"
# wait 4 hours
octomil rollout set my-model --percentage 100 --reason "Staged rollout passed"

Blue/green with instant rollback:

octomil deploy my-model --version 2.0.0 --rollout 100%
# if something goes wrong:
octomil rollback my-model --to-version 1.0.0

Gotchas

• Device assignment is deterministic — a device gets a stable yes/no for a given rollout percentage. Increasing from 10% to 20% adds new devices but doesn't reassign existing ones.
• Auto-rollback requires the policy flag — set octomil team set-policy --auto-rollback at the org level. Without it, rollbacks are manual only.
• Rollouts and experiments share traffic — if an experiment is running on the same model, the rollout percentage applies to the non-experiment traffic. Coordinate traffic allocation between rollouts and experiments to avoid conflicts.
• Paused rollouts still serve the current percentage — pause stops advancing, not serving. Devices already on the new version stay on it.

Troubleshooting

Devices not receiving the new version — Check: rollout is active (not pending or paused), device is in the target group, rollout percentage is high enough.

Cannot advance rollout — Target percentage already reached, or rollout is paused. Check with octomil rollout status radiology-v1.

Related

• Experiments — A/B test before rolling out
• Device Groups — target rollouts to specific cohorts
• Monitoring — track rollout health