> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # Releases and versions > How a pushed primitive version, an agent version, and a deploy relate, what a version snapshots, and how backups and drift checks fit around them A release is the moment end users start getting different code. Lua separates uploading a change from releasing it: `lua push` uploads a version of a primitive and changes nothing for end users, `lua version create` snapshots the agent as one numbered agent version, and `lua version promote ` makes that snapshot live atomically. The same command, pointed at an older version, is the rollback. ## How a change reaches production Each primitive you push gets its own semver version. `lua push skill --name orders --set-version 1.2.0` uploads exactly that version; with `--force` and no `--set-version`, the CLI bumps the patch number for you; with neither, it asks. `lua push` with no type (or `lua push all --force`) is the stage-all form: it patch-bumps and uploads every registered skill, webhook, trigger, job, processor, device, device trigger, and voice, upserts your MCP servers, uploads the agent configuration (another [persona](/concepts/persona) version, the [model](/concepts/models) and its settings), and stores a source backup. Workflows are the exception: they are pushed only by `lua push workflow --name `. MCP servers have no versions at all; a push replaces the server's definition by name. None of the primitive versions is live yet (the persona and model in the agent configuration are the exception: they are served from the next message). `lua version create -m ""` records which version of each primitive is the latest pushed one and files the result as a staged agent version with the next integer number. `lua chat --agent-version -m "…"` previews the staged version in production, in its own thread. `lua version promote ` switches production to that snapshot in one step: every primitive in it becomes the active version at the same time, and the previously active agent version becomes superseded. Superseded versions stay promotable, which is why `promote` is also the rollback. ```bash theme={null} lua push all --force lua version create -m "Add order lookup" lua chat --agent-version 4 -m "Where is order A-1001?" lua version promote 4 ``` An agent version has one of four statuses: `staged` (created, not serving), `active` (serving; at most one per agent), `superseded` (was active, replaced), and `deleted` (soft-deleted with `lua version delete`). A version records who created it (`createdBy`) and when it was promoted (`promotedAt`), not who promoted it. `lua version list` shows them, `lua version show ` prints what a version contains, `lua version diff ` compares two, and `lua version status` compares your local versions with the active one to show what is pushed but not live. `lua deploy --name --set-version --force` is the single-primitive shortcut. For a webhook, job, trigger, preprocessor, or postprocessor it creates and promotes an agent version scoped to that primitive, so the change appears in `lua version list` like any other; the CLI also writes the deployed version into `lua.skill.yaml` and prints the promoted agent version, which the per-primitive spellings (`lua webhooks deploy`, `lua jobs deploy`) don't. For a skill, `lua deploy skill --set-version ` serves that version from the agent's next turn on any agent, because the runtime reads each skill's active version directly rather than through the snapshot; but the next `lua version promote` resets every skill to the version pinned in the promoted agent version, so a skill deployed without a new agent version is reverted by the next promote. For a durable change, push, `lua version create`, `lua version promote`; for an immediate rollback of one skill, `lua deploy skill --set-version `. For the persona, `lua deploy persona --set-version ` switches the served persona to that version at once, versioned agent or not (see [persona](/concepts/persona)). An agent with no agent version yet is not under versioning, so every `lua deploy ` goes live at once; `lua version status` says so. `lua deploy all --force` deploys the latest version of every deployable primitive and ignores `--set-version`. A workflow goes live with `lua workflows deploy -v `, which also creates and promotes a scoped agent version; a run already in flight finishes on the version it started on, so a deploy or promote affects new runs only. ## What an agent version snapshots An agent version names the version of each skill, webhook, job, preprocessor, postprocessor, trigger, and workflow, the persona version, the model code, the agent's default voice, and the MCP servers attached to the agent. Promoting restores the primitive versions and the model; agent versions record which persona version was current, but `lua version promote` does not change the served persona, so add `lua deploy persona --set-version ` when a rollback must bring the persona back. It doesn't cover `modelSettings`, batching, governance, or the agent's routing description, which change on push; MCP server activation, which is `lua mcp activate`; or environment variables, knowledge, features, and channels, which are managed outside versions and are left as they are by a rollback. Devices and device triggers are outside it too: a pushed device or device-trigger version goes live at push time when you pass `--auto-deploy` to `lua push device` or `lua push device-trigger`. ## Agent versions and source backups An agent version is a set of pointers to server-side primitive versions. A source backup is your project files. `lua push backup` uploads the files that changed (`lua push all` does this for you), `lua pull` restores the latest backup to disk, and `lua pull --version ` restores the files that agent version `n` was created from, so a rollback can bring the code back too. `lua source list` shows backup history; `lua source rollback --version ` restores an older backup by writing it as the next backup. `lua.skill.yaml` records the last backup hash and time. Keep your own git history as well. ## When to use which command * Iterating in the sandbox: no release command at all; `lua chat` runs local code. * Shipping a coordinated change across several primitives: `lua push all --force`, `lua version create`, `lua version promote `. * Shipping one fixed webhook or job without touching anything else: `lua deploy --name --set-version latest --force`. * Something is wrong in production: `lua version promote `; it takes effect immediately. For one skill, `lua deploy skill --set-version `; if the persona is the problem, `lua deploy persona --set-version `. * Checking whether local code, pushed versions, and production agree: `lua sync --check` (exit 1 on drift; it also registers server records for local primitives, so it isn't purely read-only) and `lua status --json`, whose `diffs[].status` is `synced`, `ahead`, `behind`, or `not deployed` per primitive. ## Limits * Primitive versions must be `x.y.z`; `lua push` rejects anything else with `Invalid version format`. * `lua version create` needs a source backup; run `lua push` first or pass `--auto-push`. Creating a version when nothing changed since the last one is reported, not an error. * An agent keeps at most 100 versions in `staged`, `active`, or `superseded`; delete old ones to create more. * `lua version promote` asks no confirmation. The active version cannot be deleted, and neither can the last remaining one. * `--set-version` is ignored by stage-all pushes and by `lua deploy all`. * Hand-editing `version` in `lua.skill.yaml` has no effect: `lua push` and `lua sync` overwrite it with the server's active version before reading it. Use `--set-version` or `--force` instead. ## Next steps Push, create a version, promote, verify, and roll back. Recover source and agent state. Every action, flag, and error code. The single-primitive shortcut in full.