Skip to main content
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 <n> 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 version, the model and its settings), and stores a source backup. Workflows are the exception: they are pushed only by lua push workflow --name <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 "<message>" 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 <n> -m "…" previews the staged version in production, in its own thread. lua version promote <n> 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.
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 <n> prints what a version contains, lua version diff <a> <b> compares two, and lua version status compares your local versions with the active one to show what is pushed but not live. lua deploy <type> --name <name> --set-version <ver|latest> --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 <v> 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 <old>. For the persona, lua deploy persona --set-version <n> switches the served persona to that version at once, versioned agent or not (see persona). An agent with no agent version yet is not under versioning, so every lua deploy <type> 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 <name> -v <ver|latest>, 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 <n> 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 <n> 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 <n> 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 <n>.
  • Shipping one fixed webhook or job without touching anything else: lua deploy <type> --name <name> --set-version latest --force.
  • Something is wrong in production: lua version promote <previous>; it takes effect immediately. For one skill, lua deploy skill --set-version <old>; if the persona is the problem, lua deploy persona --set-version <n>.
  • 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

Releasing

Push, create a version, promote, verify, and roll back.

Backups and restore

Recover source and agent state.

lua version

Every action, flag, and error code.

lua deploy

The single-primitive shortcut in full.