Skip to Content
Raw

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-agent

Aetherfy lists deployments newest-first with four columns:

ColumnContains
VersionThe version number — this is what you pass to afy rollback
Statequeued, building, deploying, active, completed, failed, superseded, or rolled_back
CreatedWhen the deployment was created
ErrorThe failure reason, for deployments that failed

When the newest deployment failed, the Aetherfy CLI helps you directly: it suggests the rollback command for the last good version, the newest earlier version that went live (active, superseded or rolled_back) and that Aetherfy can still roll back to, so you do not have to work out a safe target yourself. When there is no such version it suggests nothing. A failed run is not a failed deployment and produces no suggestion.

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-agent

Then roll back to a specific version:

afy rollback my-agent 3

Aetherfy 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.

A rollback restores that release’s own code and configuration, with today’s secrets

A release is its code and the configuration it was deployed with: every field of its aetherfy.yaml, recorded at that deploy. A rollback, like a redeploy, runs the target release exactly as it was configured then, its memory, always-on, idle timeout, regions, schedule and spawn included. It never reads your current aetherfy.yaml, and never keeps settings from the release it replaces.

It does not restore old secrets. Secrets are never part of a release: an image carries none, and a rollback, like every new deployment, reads the agent’s secrets as they are now, once, before any machine is created. If you rotated a key since that release, the rolled-back version runs with the new key. To run with an old value, set it again with afy secrets set before rolling back.

Two consequences follow:

  • On a frozen account, a rollback to a bigger configuration is growth. While the account is frozen (SOFT_CAP_EXCEEDED or DUNNING_FROZEN), a rollback goes through only if the target release reduces cost and grows nothing against what is live now, like any other deploy. See Deploying while growth is frozen.
  • A release from before Aetherfy recorded configurations cannot be restored. A rollback, redeploy or move of one is refused with 422 RELEASE_CONFIG_NOT_ON_RECORD: “Version N’s configuration isn’t on record; deploy it again from its source.”

The version argument Aetherfy accepts

The version is a bare integer. A v prefix is rejected:

CommandResult
afy rollback my-agent 3Valid
afy rollback my-agent v3Rejected — “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 hasWhat a rollback does
Its imageRe-deploys that image exactly. No build.
Only its code archiveRebuilds 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”.
NeitherRefused (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.

An exact rollback creates a version with no archive of its own: it runs the code of the version you rolled back to, so that version’s archive is the one Aetherfy uses whenever it has to rebuild it, whether for afy redeploy, a later rollback to it whose image is gone, a type: job run whose image is gone, or afy restore. That archive is kept while the version is the one your agent is running.

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.

PathBuild stepSource of what is deployed
afy deployYes — uploads and buildsYour current directory or repository
afy rollback, image presentNoThe image already stored for the target version
afy rollback, image goneYesThe 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 a workspace has a single region, so a deployment there either succeeds or fails and DEGRADED does not arise. See /platform/regions.

Last updated on