Deploy an update

Ship a new release to one robot or a whole fleet, with automatic rollback on failure.

A release is an immutable artifact (today: a container image or app tarball) plus a semver tag and notes. A deployment targets a release at either a single robot or a fleet, with a required idempotency key. The agent on the robot is what actually swaps the application.

1. Build and tag your robot app

Container path (v0 default):

docker build -t robot-app:1.2.3 .
docker save robot-app:1.2.3 -o robot-app-1.2.3.tar

Tarball path (for non-Docker robots):

tar czf robot-app-1.2.3.tar.gz -C build .

2. Push the release

rf releases push ./robot-app-1.2.3.tar --tag 1.2.3

Behind the scenes this calls POST /api/releases with the semver, notes, and an artifact descriptor. The control plane creates an artifacts row (kind container_image by default) and a releases row pointing to it.

List releases to confirm:

rf releases list

3. Deploy

To a single robot:

rf deploy <release-id> --robot <robot-id>

Or to a whole fleet — every robot in the fleet gets its own child deployment record so rollout history is robot-specific:

rf deploy <release-id> --fleet <fleet-id>

Add --watch to follow the event log until the deployment reaches a terminal status:

rf deploy <release-id> --fleet <fleet-id> --watch

Every POST /api/deployments requires an Idempotency-Key header. Replaying the same key returns the original deployment instead of creating a duplicate. rf deploy generates a fresh UUID per call; pass --idempotency-key <uuid> to make a retry safe.

You can also schedule a deployment for later by passing --scheduled-at 2026-06-01T03:00:00Z. The Worker's scheduled handler dispatches due rows on its cron tick.

4. Watch the rollout

Each deployment has an append-only event log. rf deploy --watch polls it for you. To inspect after the fact, hit the API directly:

curl https://api.roboflare.com/api/deployments/<deployment-id>/events \
  -H "Authorization: Bearer $RF_TOKEN"

You'll see status transitions: queued → dispatched → applied (or failed / rolled_back).

Automatic rollback

The agent watches the new container for 30 seconds after restart. If the new process exits inside that window, the agent restarts the previous image and reports rolled_back. No staged rollouts, no health probes — the rule is intentionally simple in v0.

Roll back manually

Take any previous successful deployment and re-deploy that release. The deployment events table preserves the audit trail.

Read Releases for the data model behind artifacts, releases, and deployments — including target semantics and the scheduled-deployment dispatcher.