---
slug: agents/rollback
title: Rollback
kind: howto
surface: agents
summary: How to return an Aetherfy agent to an earlier deployment with afy rollback — reading deployment history, the bare-integer version argument, which versions are valid targets, and why a rollback skips the build step.
sources:
  - aetherfy-cli:cmd/rollback.go
  - aetherfy-cli:cmd/deployments.go
  - aetherfy-control-plane:api/routes/deployments.py
  - aetherfy-control-plane:models/deployment.py
  - dashboard/pages/api/controlplane/deployments.js
---

# 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 an image you already
built, 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:

```bash
afy deployments my-agent
```

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

```bash
afy rollback my-agent
```

Then roll back to a specific version:

```bash
afy rollback my-agent 3
```

Aetherfy re-deploys version 3's image. The deployment it replaces moves to the
`rolled_back` state, which is terminal — it is visible in history but will not
change again.

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

Only versions that were **successfully built** can be rolled back to. In
practice that means the two states below:

| State | Valid target |
|---|---|
| `active` | Yes |
| `superseded` | Yes |
| `failed` | No — nothing was built to re-deploy |
| `queued`, `building`, `deploying` | No — not finished |
| `rolled_back` | No |

`superseded` is the state you will usually target: it means the deployment built
and ran successfully and was later replaced by a newer one. That is exactly the
"last known good" version.

## Why a rollback on Aetherfy is fast

`afy rollback` **skips the build step entirely**. Aetherfy re-deploys the image
from the target version directly rather than rebuilding from source.

| Path | Build step | Source of the image |
|---|---|---|
| `afy deploy` | Yes — uploads and builds | Your current directory or repository |
| `afy rollback` | No | The image already stored for the target version |

Two consequences follow. A rollback is faster than a deploy, because the slow
part is skipped. And a rollback is reproducible in a way that re-deploying old
source is not — it ships the exact bytes that previously ran, with no dependency
resolution that could pick up different versions this time.

## Watching or detaching from an Aetherfy rollback

By default `afy rollback` watches the rollback until it completes. To return
immediately instead:

```bash
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](/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 tier 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](/platform/regions).