Upgrade safely

nautilo upgrade is the day-two replacement path for Compose profiles. nautilo deploy is not: deploy has no automatic backup and no rollback. For Railway, use the separate protected upgrade and resume guide.

Plan without mutation

nautilo profile list
nautilo status --profile circle-server
nautilo release plan --profile circle-server

release plan previews the default server-only artifact and compatibility preflight. It is read-only. There is no release apply; upgrade owns the mutation. Replace circle-server throughout with the intended deployment profile and compare its instance identity with your deployment receipt before upgrading.

Select the release

Bare upgrade verifies the signed stable Server channel and selects its exact immutable runtime digest before the transaction begins:

nautilo upgrade \
  --profile circle-server \
  --backup-dir /path/to/operator-controlled-backups

Transactional safety does not by itself prove that an explicitly selected artifact is current. To move to a specific reviewed release, provide its canonical immutable reference:

nautilo upgrade \
  --profile circle-server \
  --image ghcr.io/agentsea/nautilo-runtime@sha256:<64-lowercase-hex-digest> \
  --backup-dir /path/to/operator-controlled-backups

The default replaces only nautilo-server. Use --full only when the release explicitly requires a full-stack replacement. --from-sources and --image are mutually exclusive.

Transaction boundary

The guarded path drains work, stops the Server, creates and verifies a full recovery bundle, applies the selected artifact, runs runtime acceptance, and then completes maintenance. On apply or acceptance failure it restores the bundle and prior image and proves health before clearing maintenance.

Verify and recover

After success, compare deployment identity with the immutable artifact and prove owner sign-in plus the application contract you upgraded for. If automatic rollback fails or rollback health fails, treat the target as critical: preserve the bundle, prior-image identity, logs, and maintenance state, then use backup and restore.

Application rollback does not mean an arbitrary database schema reversal. The verified full bundle is the recovery authority for data state.