Releases

A release is a named, semver’d snapshot of an agent that you can ship, talk about, and roll back to. Releases live at ~/.cast/agents/<name>/.cast/releases/.

Listing releases

cast releases email-assistant

Output:

Agent: email-assistant
Current release: 1.6

Releases:
─────────────────────────────────────────────────────────────
  1.0   5/9/2026 6:26:28 PM    Initial release
  1.5   5/9/2026 9:35:20 PM    Added email processing
  1.6   5/12/2026 1:08:33 PM   Updated model + permissions
─────────────────────────────────────────────────────────────

releases.json is the manifest; the tarballs (1.0.tar.gz, 1.5.tar.gz, …) sit alongside it. agent.yaml’s version: "1.6" always points at the current release.

Creating a release

cast release email-assistant 1.7
cast release email-assistant 1.7 --message "Switched model + tightened permissions"

release does six things:

Validates the semver format (MAJOR.MINOR.PATCH).
Snapshots the current working tree into releases/<version>.tar.gz.
Updates agent.yaml with version: "<version>".
Writes a row to releases.json with timestamp, message, and auto-generated changelog.
Records the release in the releases table of cast.db.
Auto-generates a changelog from the changes since the previous release and groups them by category (Features / Improvements / Config).

The --message flag overrides the auto-generated message. If the version you’re about to release corresponds to a breaking change (e.g. you removed a required tool), Cast prompts for confirmation.

Suggested versions

When you open release in the TUI, Cast suggests the next semver based on the kind of change that was last made:

Change kind	Bump	Why
`model:` only	patch (1.5.0 → 1.5.1)	config change
`instructions` only	minor (1.5.0 → 1.6.0)	behaviour change
Added MCP / tool	minor	new capability
Removed required tool	major (1.5.0 → 2.0.0)	breaking
Tightened permissions	patch	config change

You can always type a different version; the suggestion is just a starting point.

Deploying a release

cast deploy email-assistant --version 1.7 --provider railway

deploy extracts the 1.7.tar.gz over the working tree before building the deployment image. The resulting deployment’s deployed_version is recorded as 1.7 in the database. A unique deployment SHA is also generated and printed:

Deployed email-assistant with deployment SHA: abc123
Connect with: cast connect abc123

Upgrading a live deployment

cast upgrade abc123 --version 1.7        # by deployment SHA
cast upgrade email-assistant --version 1.7    # most recent
cast upgrade email-assistant                  # defaults to latest release

upgrade redeploys with the new tarball. The deployment record is updated in place; the SHA stays the same. Volume mounts (which hold the agent’s memory) are preserved across upgrades.

Multi-deployment

The same agent can be deployed to multiple providers simultaneously, each with its own SHA and its own deployed_version. cast registry <name> shows them all:

Local Agent Registry: email-assistant
─────────────────────────────────────────────────────────────
  SHA       PROVIDER        VERSION  DEPLOYED               URL
  abc123    railway         1.6      5/12/2026 1:08 PM     https://email-assistant.up.railway.app
  def456    fly             1.5      5/9/2026  9:35 PM     https://email-assistant.fly.dev
  ghi789    digitalocean    1.6      5/12/2026 1:08 PM     http://203.0.113.42:8080
─────────────────────────────────────────────────────────────

cast upgrade and cast shutdown both accept a SHA to target a specific deployment, falling back to the most-recent deployment when given an agent name.