Skip to main content
Looking for the release model as a whole — how lua push, lua deploy, and lua version fit together? Start with The release flow, end to end below.

​
Overview

lua version manages agent versions — atomic snapshots of your agent’s complete deployed state (skills, webhooks, jobs, processors, MCP servers, persona, and model) that you can inspect, diff, and switch between instantly.

​
Why versions?

A lua push updates individual primitives (a skill, a webhook, a persona) one by one. An agent version pins the exact combination of everything at a moment in time: which version of every skill, what model, which persona text, which MCP servers and how they were configured. Promoting a version swaps the whole agent state atomically — all of it changes at once, with no in-between state where some primitives are old and some are new. Rolling back is just promoting an older version.
lua version promote is the recommended rollback path. It is instant, atomic, and requires no re-uploading of files. See lua version promote below and the deprecation notice on lua source rollback.

​
The release flow, end to end

Three commands, three distinct jobs:
  1. lua push <primitive> stages code. It mints a new immutable version of that primitive — a skill, webhook, job, processor, trigger, persona, voice, MCP config, or model change — but activates nothing. Nothing your users see changes yet.
  2. lua version create freezes a release candidate. It snapshots the latest pushed version of every primitive into a single agent version.
  3. lua version promote <N> activates that agent version. Every primitive switches at once — no mixed-version window where, say, a new skill is live against an old persona. This push → create → promote sequence is the recommended release flow.
Execution guarantee: if a promote (or deploy) reports success, that exact code serves the very next invocation of the agent. Allow up to roughly a minute for edge caches to catch up globally.

​
Where lua deploy fits

lua deploy <primitive> (documented in full on the Skill Management page) is the older, single-primitive release command and remains fully supported:
  • Once an agent has promoted at least one agent version, lua deploy performs a scoped promote: the platform automatically creates and promotes a new agent version identical to the current active one, except for the primitive you just deployed. The deploy is live immediately, and your agent-version history stays consistent — no gap where a primitive changed outside the version timeline. These auto-created versions show up in lua version list with a deploy … message so you can tell them apart from versions you created explicitly.
  • For agents that have never created or promoted an agent version, lua deploy activates the primitive directly, the same way it always has.
Either way, use lua version promote when you want to switch several primitives together atomically; use lua deploy for a fast, single-primitive fix.
Sandbox testing (lua chat / lua test) never touches what’s live — it always runs against your local or pushed-but-not-promoted state, never the active agent version. Conversely, deactivating a webhook (or any primitive) stops it serving immediately, independent of version history.

​
The three version numbers

When you run lua version create --auto-push, the output shows three different counters. They track separate things: These counters are independent. Pushing a single skill increments that skill’s primitive version and creates a new source backup, but does not create a new agent version. Only lua version create creates a new agent version.

​
Statuses

Every agent version has one of four statuses:
“staged” does not mean “staging environment.” A staged agent version is unrelated to your push deploy target (staging vs production) and unrelated to git’s staging area. Here, “staged” simply means “snapshotted, awaiting promote.”

​
Commands

​
lua version create

Snapshots the agent’s current pushed state as a new staged version.
If nothing has changed since the last snapshot, the command exits with:
On success:

​
lua version list

Prints a table of agent versions with columns VERSION, STATUS, CREATED, BY, and MESSAGE. The active version is starred.

​
lua version status

Shows, per primitive, which version is pinned by the currently active agent version versus which version is sitting locally or already pushed to the server. Anything pushed but not yet part of an active (or promoted) agent version is flagged so you can see at a glance what’s waiting to go live.
Reach for this before a release to confirm exactly what a lua version create would capture, or after a release to confirm nothing was left behind.

​
lua version show

Shows the full snapshot for a version: per-type primitive counts, model, persona version, creator email, message, and recorded commit hash (if any). Accepts either 2 or v2 as the version argument.
lua version show reports what is on the server for the agent at the time of the snapshot — not what is in your local project directory. A skill that exists server-side but has been removed from your local workspace is still part of the agent and will appear in the snapshot.

​
lua version diff

Shows what changed between two versions: added, removed, and changed primitives by name and version. Persona is compared by content, so re-pushing identical persona text shows (unchanged). MCP configuration changes name the specific fields that changed. Model changes are included. Accepts 2 or v2 for both arguments.

​
lua version promote

Instantly activates a version. The previously active version becomes superseded. Promoting the already-active version is a graceful no-op.
There is no confirmation prompt — promotion is instant and the previous state is preserved as superseded, so you can always promote back.

​
lua version delete

Soft-deletes a version. Deleted versions remain listed and inspectable with lua version show, but can no longer be promoted.
Guard-rails:
  • You cannot delete the active version. Promote a different version first.
  • You cannot delete the only remaining version.

​
Typical workflows

​
Release

​
Rollback

​
Audit

​
Git integration

When you have run lua git connect, every lua version create automatically commits your project and tags the commit lua/v<N>, where N is the new version number. The commit hash is recorded in the version snapshot and visible in lua version show. See the Git Command page for setup instructions, auto-push configuration, and troubleshooting.