> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karta.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Releases

> Immutable, versioned snapshots of an agent - built once, activated by an atomic pointer flip, rolled back the same way.

A **release** is a versioned, validated snapshot of your agent's
code - the sub-agents, skills, tools, and context files at one commit.
Releases are the unit the [deploy loop](/deploy/deploy-loop) builds,
activates, serves, and rolls back.

## Properties

* **Immutable and versioned.** Every publish produces a new release (`v1`,
  `v2`, and so on) tied to a commit SHA. A version is never overwritten.
* **Lifecycle is explicit.** A release moves through `pending`, `building`,
  `active`, `failed`, or `superseded`.
* **Activation is a pointer flip.** Going live moves the agent's active release
  pointer atomically. Rollback moves that pointer back to an earlier release.
* **Tenant-isolated.** Each organization has its own active release for an
  agent slug.
* **Zero-interruption cutover.** In-flight sessions finish on the release they
  started on; the next session picks up the new active release.
* **Native harness layout.** The packaged artifact keeps the harness's own
  native layout - no Karta-specific manifest beyond an optional
  [`karta.toml`](/build/karta-toml) for build hints.

## How a release is built

<Steps>
  <Step title="Publish">
    Your laptop, CI, dashboard, or `git push karta` publishes the agent
    project. The first publish creates the agent; later publishes add versions.
  </Step>

  <Step title="Validate">
    Karta validates the package, parses `karta.toml` when present, checks size
    and archive shape, and allocates the next release version.
  </Step>

  <Step title="Select run mode">
    The project selects how the release runs: a `Dockerfile`, a declared
    `buildpack`, or the file tree directly. See
    [`karta.toml`](/build/karta-toml#build-kind-resolution).
  </Step>

  <Step title="Activate">
    On a successful production build, Karta flips `current_release` atomically,
    marks the prior active release `superseded`, and records an audit event.
    Re-activating the current release is a no-op.
  </Step>
</Steps>

## What starts on which release

| Work             | Release selection                                               |
| ---------------- | --------------------------------------------------------------- |
| New session      | Uses the agent's current active release.                        |
| Existing session | Continues on the release it started on.                         |
| Rollback         | Moves the active pointer; new sessions use the rollback target. |
| Preview          | Tracks a pull request separately from production.               |

## Preview releases

A pull request records its own ephemeral, auto-expiring **preview release**, so
each PR is tracked as a distinct release before it reaches production.

<CardGroup cols={2}>
  <Card title="The deploy loop" icon="rocket" href="/deploy/deploy-loop">
    Ship, serve, consume, end to end.
  </Card>

  <Card title="Releases & rollback" icon="code-branch" href="/deploy/releases-and-rollback">
    Deploy and roll back with the CLI and API.
  </Card>
</CardGroup>