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

# Upgrading sysg

# Upgrading `sysg`

Run the normal installer again to upgrade to the latest release:

```bash theme={null}
$ curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh
```

## Live re-execution

Starting with `0.56.0`, compatible releases use **live re-execution**: the
running supervisor replaces its process image in the same PID while retaining
its service processes, process groups, control socket, log pipes, project modes,
and lifecycle state.

The installer performs the upgrade in this order:

1. Download the release into its versioned slot.
2. Verify its version, executable metadata, protocol, and handoff schema.
3. Ask the resident supervisor whether its runtime is safe to transfer.
4. Re-execute the supervisor and verify that the same PID reports the target version.
5. Update the `sysg` symlink and `active-version` file.

The PATH target is not changed if any step fails. A foreground log attachment
may reconnect while the supervisor image changes, but its project and service
processes continue running.

## Compatibility

Live re-execution requires a strictly newer release with the same live-reexec
protocol and handoff schema. Version boundaries do not determine compatibility:
`0.57.1` can live-upgrade to `0.58.0` while both advertise the same contract.
A downgrade or a protocol/schema change requires a stopped supervisor.

Contract-based compatibility begins with `0.57.1`. Residents from `0.56.0`
through `0.57.0` enforce the original same-major/minor rule, while earlier
residents do not support live re-execution. Upgrading from `0.56.x` to `0.57.x`
therefore requires one stopped-supervisor transition:

```bash theme={null}
$ sysg stop --supervisor
$ curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh
```

<Warning>
  `sysg stop --supervisor` stops every registered project. After installation,
  restart each required project from its manifest.
</Warning>

The installer reports [`SG0502`](/how-it-works/dialog/codes#sg0502) and leaves
the existing PATH target unchanged when the resident and target cannot hand
off safely. The target remains installed, so stopping the supervisor and
rerunning the same installer activates it.

## Safe handoff requirements

The supervisor waits for a stable ownership boundary. It refuses the upgrade
while a project is booting, a restart or deployment is active, a cron command is
running, or dynamic child processes cannot be transferred. It also verifies
that loaded manifests have not changed and that every managed output pipe can
be inherited.

The refusal is non-destructive. Let the reported operation finish, then rerun
the installer.

## Failure and rollback

The previous versioned binary remains installed until the replacement has
restored supervision. Failures before `exec` produce
[`SG0504`](/how-it-works/dialog/codes#sg0504) and the resident supervisor resumes
normally. If the replacement cannot restore the handoff, systemg attempts to
re-execute the previous binary and reports
[`SG0505`](/how-it-works/dialog/codes#sg0505).

Upgrade diagnostics are documented from
[`SG0501`](/how-it-works/dialog/codes#sg0501) through
[`SG0505`](/how-it-works/dialog/codes#sg0505).