Rollback
When to roll back an Aetherfy agent
Rolling back returns an Aetherfy agent to an earlier deployment. Reach for it when a deployment built and shipped successfully but behaves wrongly in production, and you want the previous version back before you diagnose anything.
A rollback on Aetherfy is not a code change. It re-deploys a version you already shipped, so it neither reads your working tree nor touches your repository. Fix the code afterwards and deploy forward normally.
Listing Aetherfy deployment history
Before rolling back, look at what versions exist:
afy deployments my-agentAetherfy lists deployments newest-first with four columns:
| Column | Contains |
|---|---|
| Version | The version number — this is what you pass to afy rollback |
| State | queued, building, deploying, active, completed, failed, superseded, or rolled_back |
| Created | When the deployment was created |
| Error | The failure reason, for deployments that failed |
When the newest deployment failed, the Aetherfy CLI helps you directly: it
suggests the rollback command using the newest version that is still active or
superseded, so you do not have to work out a safe target yourself.
Rolling back an Aetherfy agent
Run afy rollback with no version to have Aetherfy print the deployment history
so you can choose:
afy rollback my-agentThen roll back to a specific version:
afy rollback my-agent 3Aetherfy re-deploys version 3, exactly or rebuilt from its source (see below). Once
the rollback is live, the deployment it replaced moves to the rolled_back state (a
deploy or redeploy leaves the one it replaces superseded instead). Both are terminal,
stay visible in history, and can themselves be rolled back to.
The version argument Aetherfy accepts
The version is a bare integer. A v prefix is rejected:
| Command | Result |
|---|---|
afy rollback my-agent 3 | Valid |
afy rollback my-agent v3 | Rejected — “Version must be a positive integer” |
Which Aetherfy deployments are valid rollback targets
A version can be rolled back to while Aetherfy still has its image or its code archive. What happens depends on which one is left:
| What the version still has | What a rollback does |
|---|---|
| Its image | Re-deploys that image exactly. No build. |
| Only its code archive | Rebuilds the version from that archive and rolls back to the result. The response and afy rollback say “rebuilt from source; dependencies may differ from the original”. |
| Neither | Refused (DEPLOYMENT_ROLLBACK_TARGET_INVALID), with a message saying both are gone |
Images of older versions do not last: the image registry keeps an image only while a machine uses it, so a version that has not run for a while usually has only its archive. Aetherfy keeps the code archives of the ten most recent successful deployments of each agent, plus the one your agent is running, and deletes older ones. A version past that, whose image is also gone, can no longer be rolled back to. A failed build keeps no archive.
can_rollback on each deployment in the API, and the rollback button in the
dashboard, answer exactly this question, so read them rather than inferring from
the state. superseded or rolled_back is the state you will usually target: it
means the deployment built and ran successfully and was later replaced.
An archived agent cannot be rolled back: its app no longer exists, and the API
refuses with AGENT_ALREADY_ARCHIVED. Restore it first with afy restore <agent>,
then roll back. Every version of an archived agent reads can_rollback: false.
What an exact rollback and a rebuilt one guarantee
An exact rollback skips the build step entirely, so it is faster than a deploy and ships the exact bytes that previously ran.
A rebuilt rollback runs a build from the stored archive, so it takes as long as a deploy, and dependency resolution happens again: an unpinned dependency can resolve to a newer release than the one the version originally ran with. Pin your dependencies if you need a rebuilt rollback to match.
| Path | Build step | Source of what is deployed |
|---|---|---|
afy deploy | Yes — uploads and builds | Your current directory or repository |
afy rollback, image present | No | The image already stored for the target version |
afy rollback, image gone | Yes | The target version’s stored code archive |
Watching or detaching from an Aetherfy rollback
By default afy rollback watches the rollback until it completes. To return
immediately instead:
afy rollback my-agent 3 --detach--detach / -d returns as soon as the rollback is accepted. Check the outcome
afterwards with afy deployments my-agent, or watch the agent’s output with
afy logs my-agent — see /agents/runs-and-logs.
Partially successful multi-region deployments on Aetherfy
On a plan with multi-region placement, a deployment can succeed in some regions and not others. Aetherfy reports that as DEGRADED, together with a count of how many regions are ready — rather than inventing a separate state for it.
A degraded result tells you the deployment is live but not everywhere you asked for. Rolling back is a reasonable response if the successful regions are serving a version you do not want live at all; otherwise, deploying forward once the underlying cause is resolved brings the remaining regions up.
Multi-region placement begins at the plan named Performance. On Free and Starter your Aetherfy account operates in a single region, so a deployment there either succeeds or fails and DEGRADED does not arise. See /platform/regions.