# Versions and statuses

Version labels, the status lifecycle from draft to retired, and how status differs from the enablement that routes traffic.

Every deploy creates a version. A version has a label you choose, a status the platform moves it
through, and, separately, the tenants enabled for it. Knowing which of the three you are changing
keeps rollouts predictable.

- **Label** is the `version` in `agent.yaml`, such as `0.4.0` or `v2`. It is yours; it does not
  have to be sequential.
- **Status** is the lifecycle: `draft` → `production`, with `rejected`, `deprecated`, and
  `retired` as side exits. Status gates whether a tenant may serve the version.
- **Enablement** is which tenants actually serve it. Status alone routes nothing.

## Statuses

| Status | Meaning | Can serve traffic |
|---|---|---|
| `draft` | Registered and built, not yet promoted. The default after `tanomis agent deploy` registers the version, before enablement. | No |
| `production` | Promoted. Tenants may be enabled for it. | Yes, where enabled |
| `rejected` | Reviewed and refused. It never serves. A rejected first version does not pin the agent's identity mode. | No |
| `deprecated` | Still serveable for tenants already on it, so a rollback can return to it, but not a target for new enablement. | Yes, where already enabled |
| `retired` | Withdrawn from service. History is preserved. | No |

`tanomis agent statuses` prints the lifecycle your environment enforces, including the transitions each
status allows and any operator-added custom statuses. Trust it over this table if they differ.

```bash title="Terminal"
tanomis agent statuses
tanomis agent versions support-copilot --tenant "$TANOMIS_TENANT"
```

## Status is not traffic

| Command | Changes status | Changes enablement |
|---|---|---|
| `tanomis agent deploy --tenant T` | Registers a draft, promotes it as part of the deploy | Enables T for the new version |
| `tanomis agent promote --version V` | `draft` → `production` | No |
| `tanomis agent enable --version V --tenants A,B` | No | Enables A and B |
| `tanomis agent rollout --version V --tenants A` | Promotes if needed | Enables A, as baseline or canary |
| `tanomis agent disable --tenants A` | No | Removes A's enablement |

Promotion changes the global status only. If you want a tenant to serve a version, enable it for
that tenant, or use `rollout`, which does both for exactly the tenants you name.

## Labels

The label comes from `version` in the manifest. Use a scheme your team can read in a rollout table:
semantic versions when your agent has an API to other systems, dated labels when it does not. The
platform identifies versions by an immutable id underneath; the label is for people.

Deploying with a label that already exists on the agent registers a new immutable version with the
same label. Avoid it: it makes `versions --by-tenant` ambiguous to read.

## Where to go next

- [Deploy a version](/guides/deploy/deploy-a-version): the stages of a deploy.
- [Roll out and roll back](/guides/deploy/rollout-and-rollback): canary, graduate, return.
- [Retire an agent](/guides/deploy/retire-an-agent): removing enablement and the agent itself.