> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrades

> How Cyberun versions ship and how operators apply them — release cadence, the patch / minor / major boundary, and what major releases mean for licenses.

Cyberun releases on three independent streams. Operators apply
upgrades by pulling the new artifact, replacing the running
binary or container image, and restarting. Cross-stream
compatibility is governed by the major version.

## Release streams

| Stream | Tag pattern    | What ships                                                                                                                       |
| ------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Cloud  | `vX.Y.Z`       | The cloud-side binaries: API server, agent gateway, license service.                                                             |
| Agent  | `agent/vX.Y.Z` | The headless agent binary. Distributed through the public install scripts.                                                       |
| CLI    | `cli/vX.Y.Z`   | The `cyberun` command-line client, installed from `releases.cyberun.cloud/cli/install.sh`. See [Cloud → CLI](/cloud/guides/cli). |

These streams release at their own cadence — Cyberun pushes
fixes to the agent without forcing a control-plane upgrade, and
vice versa. The **major component** (the leading `vN`) is the
compatibility boundary.

## Versioning policy

* **Patch (`v1.2.3` → `v1.2.4`)**: bug fixes only. Drop-in
  replacement. No license change, no schema migration.
* **Minor (`v1.2.x` → `v1.3.0`)**: additive features, new optional
  capabilities, schema additions handled automatically. Drop-in
  replacement.
* **Major (`v1.x.x` → `v2.0.0`)**: anything that breaks an existing
  contract or requires a license to be re-issued. Always carries
  release notes that call out the migration steps and the
  schema-change posture.

Operators should keep the major version aligned across the three
streams (cloud `vN.*`, agent `vN.*`, CLI `vN.*`) so
the license channel stays coherent. Mixed-major deployments are
not supported.

## Cloud-side upgrade

For container deployments — the recommended shape — the upgrade is
the standard "pull, deploy, observe" loop:

1. Read the release notes. Major versions explicitly call out
   migrations and license-renewal triggers.
2. Pull the new image tag for each of the three components
   (API server, gateway, license service).
3. Roll the deployment (rolling restart per orchestrator
   convention). The cloud-side processes are stateless at the
   process level — running multiple replicas during the roll is
   safe.
4. Verify: the license service still validates the deployment;
   the API server's running version matches what you pulled.

Zero-downtime control-plane upgrade procedures, including
schema-migration coordination across replicas, are in development
as part of the public deployment guide. Until that lands, the
recommended pattern is "brief planned maintenance window, full
rolling restart, verify".

## Agent upgrade

Each agent host can be upgraded independently by re-running the
installer script:

```sh theme={null}
# Linux / macOS — rootless re-run; no sudo, comfyui is the default tool
curl -sL https://releases.cyberun.cloud/agent/install.sh | bash -s -- \
    --api-key ak-…
```

The installer drops in the new binary and re-applies the service
definition; ComfyUI and the model cache are preserved. On macOS the
launchd agent reloads immediately; on Linux restart the service
(`systemctl --user restart cyberun-agent-<tool>`) to pick up the new
binary.
A fleet-wide upgrade tool is in development; until then, treat
agents as cattle and re-run the installer through your
configuration-management tool (Ansible, Salt, Chef, …).

## Schema migrations

The cloud-side binaries handle additive schema changes
automatically on startup. Destructive or backfill-heavy changes
ride explicit migration hooks gated on the major-version boundary
— never inside a patch or minor.

A formal schema-migration runbook (zero-downtime patterns, online
backfill, rollback) is in development. Until it ships, partner
deployments planning a major-version upgrade get a
deployment-specific runbook from Cyberun in advance.

## License interaction across majors

The license carries an embedded major-version boundary. A
`v1.x` license keeps working across every `v1.y.z` release — patch
and minor upgrades don't trigger renewal. Crossing a major
(`v1` → `v2`) deliberately rotates the platform's fingerprint
salt and the embedded major; the existing license fails validation
on the new major and a fresh license is issued for `v2`.

This is intentional: major releases are the commercial seam where
new entitlements, new quotas, or new compatibility guarantees take
effect. Coordinate the license refresh with the upgrade window —
[reach out](mailto:sales@cyberun.cloud) before tagging a major-upgrade
window.

## Backup and DR

The backup story (what state to capture, restore procedures,
multi-region replication, RTO/RPO targets) is in development as a
standalone page. Today partners receive a deployment-specific
backup runbook covering: relational DB snapshots, object-store
replication policy, license-key custody.

## See also

* [Architecture](/platform/architecture) — what each component
  upgrades affect.
* [Requirements](/platform/requirements) — the external
  dependencies whose own upgrade cadence you coordinate against.
* [License administration](/platform/license) — full license
  lifecycle.
* [Agents](/platform/agents) — the install / re-install script
  reference.