Releases and deployments

A release in Roboflare is an immutable description of a robot application build. A deployment is the command that ships a release to one robot or a fleet. Both are versioned, idempotent, and auditable.

Three tables

artifacts ─< releases ─< deployments ─< deployment_events

• artifacts — the binary. kind is one of container_image, app_tarball, mcu_firmware, or full_image_ab. Only the first two are wired in v0. Stored by SHA-256 and size, with an opaque storage_url (MinIO presigned in self-host, R2 in hosted).
• releases — one artifact + semver + notes + manifest_json. Immutable; you publish a new release rather than mutate an old one.
• deployments — one release + target. target_kind is "robot" or "fleet". Each row carries a required idempotency_key.
• deployment_events — append-only status log. queued → dispatched → applied | failed | rolled_back.

Idempotency is required

POST /api/deployments
Idempotency-Key: 0c9f1a2b-...
Content-Type: application/json

{
  "release_id":   "...",
  "target_kind":  "robot",
  "target_id":    "..."
}

The control plane stores the key alongside the org. Replaying the same key returns the existing deployment instead of creating a duplicate. This makes retry-on-network-error safe, which matters when you're deploying to flaky cellular robots.

Fleet targets fan out

A target_kind: "fleet" deployment creates one child deployment per robot in the fleet. Each child has its own row, its own event log, and its own status. This is intentional: one robot stuck offline shouldn't block the rollout to its peers, and you need a robot-specific history to know which device last rolled back.

Scheduling

Pass "scheduled_at": "2026-06-01T03:00:00Z" to defer dispatch until a maintenance window. The Worker's scheduled handler runs on a cron tick and dispatches due rows.

Rollback

The agent's OTA executor (Docker by default, symlink fallback) watches the new application process for 30 seconds after restart. If it exits in that window, the agent restarts the previous image and reports rolled_back. There is no probe URL, no staged rollout, no half-state — v0 keeps the rule loud and obvious.

To roll back manually, deploy the previous release again. The new deployment is a normal row, fully audited, with its own events.

The agent never updates itself

The OTA path updates only the robot application. The agent runs under systemd with Restart=always. A future agent self-update is a deliberate, separate feature — not piggybacking on app OTA. This rule keeps a botched app push from bricking the device.