Skip to content
Anlyon
Esc
↑↓navigate↵open⌘Jpreview
On this page

Immutable versions & rollback

Ship agent configuration as immutable versions, promote to production with confirmation, and roll back with a pointer move.

An agent is a logical identity scoped to an environment. Its configuration ships as immutable, append-only versions. Editing an agent does not mutate a version. It creates a new one. That immutability is what makes promotion and rollback safe and boring.

How versioning works

  • Every edit creates a new version. Version numbers increment per agent under a uniqueness guard, so history is one ordered sequence.
  • A single published pointer marks the live version in each environment.
  • Earlier versions are kept. A rollback moves the pointer to one of them.

Promotion

Promoting publishes a version into a target environment. It creates or appends an immutable version there, moves the published pointer, and does not copy secret values. Configuration references secrets by name, and each environment resolves its own. A production promotion picks up production’s secrets, not staging’s.

Promotion into a protected environment requires an explicit confirmProtected acknowledgement, so promoting into it is a stated choice. An environment is protected when you mark it so. See Protected production.

Rollback is a pointer move

Because every version is retained, rolling back is not a rebuild or a restore-from-backup. It moves the published pointer to a previous version, and that version is still there to point at.

v1  published ─┐
v2             │   promote v3 → pointer moves to v3
v3  published ─┘   incident → roll back → pointer moves to v1

Every version between is still there. You can move the pointer forward again the same way.

What a rollback restores

A version restores the configuration Anlyon holds. It does not restore the world outside. It does not undo a request already dispatched. An upstream API may have changed its behaviour since, and secrets resolve per environment by name, so production keeps using production’s current credential.

Within Anlyon, how much it restores depends on what the version pins. A version’s config.actions maps an action name to an immutable action version id:

{ "actions": { "refund": "acv_01JABCDEF" } }

Roll back to that version and refund runs the definition it named, not whatever the action has since been edited to. A version that pins nothing restores the pointer and the prompt, and its tools run at their current definitions.

When the pin is read, and what happens if it cannot be resolved

Two things about the timing are worth stating plainly, because they decide what a rollback does to work that is already running:

  • The pin is read at each invocation, from the agent’s published version at that moment. It is not frozen when the run started. A run is a thread of attribution, not a sealed execution context. So rolling an agent back mid-run takes effect on that run’s next action call, and a call already in flight finishes on the definition it started with. If you need a run to be immune to a promotion happening underneath it, do not start it until the promotion has landed.
  • A pin that cannot be resolved fails the call. If an agent version names an action version that no longer exists (an import, a repaired row, an action deleted and recreated), the invocation returns 409 ACTION_VERSION_PIN_UNRESOLVED naming the agent, the action and the missing version. Anlyon does not substitute the action’s current definition: silently running a different definition is exactly what pinning exists to prevent, and a warning in our logs is not an answer to “did my rollback take effect”.

Pinning is opt-in. A version whose config.actions names nothing pins nothing, and its invocations run each action’s current definition. That is what every call does until you start pinning.

Deleting an action archives it rather than destroying it, so versions an agent pins stay resolvable and the invocation history survives. The archived action keeps its name. Creating a new action under that name in the same environment answers 409 CONFLICT, so use a new name.

Why this is the safe default

  • A bad prompt or tool change in production is a pointer move away from the earlier definitions, not an emergency redeploy. The rollback does not undo an effect already dispatched.
  • Promotion is recorded. The version it creates in the target environment carries who created it.
  • Promotion does not copy secret values between environments, so it does not carry a staging credential into production.

Was this page helpful?