Skip to main content
After this guide, a change you tested locally is live for every end user, recorded as a numbered agent version you can diff and roll back to. lua push uploads a version and changes nothing for end users; lua version create snapshots the agent; lua version promote <n> makes that snapshot live and is also the rollback path. For one primitive on its own, use the lua deploy shortcut under Options you may need. Verified against lua-cli 3.33.0. Before you begin
  • A compiled project: lua compile --ci exits 0. Tests pass per Test an agent before you release.
  • No server drift: lua status --json --ci shows every primitives[].diffs[].status as synced, ahead, or not deployed, and no orphans[] entry with critical: true. For a behind entry, see If it isn’t working. lua sync --check reports the same drift and exits 1.
  • A model on your LuaAgent if the server has one: lua push all and lua push agent push the agent configuration, and a LuaAgent with neither model nor a model resolver clears the server’s model. lua sync --check prints Model drift detected when they differ (About models).
  • Workflows pushed separately, since lua push all skips them: run lua push workflow --ci --force --name <workflow-name> first (Workflows).
1

Push every primitive

lua push all compiles, bumps the patch version of every versioned primitive (skills, webhooks, triggers, jobs, preprocessors, postprocessors, devices, device triggers, voices), upserts MCP servers, pushes the agent configuration (a new persona version, model, model settings), and uploads a source backup. Nothing goes live except the agent configuration: a pushed persona and model are served from the agent’s next message.
--force is required for all, and --auto-deploy is a no-op on push all. A failed primitive does not change the exit code: the command exits 0 and lists it on stderr under ⚠️ <n> component(s) failed to push:. In a script, fail on that line.
The push first rewrites version in lua.skill.yaml from the server’s active version, so a hand edit does not survive; to pick a number, push that primitive alone with lua push <type> --ci --force --name <name> --set-version 1.2.0 (lua push reference).
2

Create an agent version

An agent version records every primitive’s pushed version plus the persona and model; it starts as staged.
The command prints ✓ Created v<n> (staged). Run `lua version promote v<n>` to deploy. and, with nothing new since the last version, No changes since the latest version, so there is nothing to snapshot. --auto-push pushes first; --commit-hash <sha> records the commit.
3

Review what will change

Compare the staged version with the active one.
Output
lua version show <n> prints one version in full; --json gives machine-readable output (lua version reference).
4

Promote the version

Promotion swaps the live version atomically, without a confirmation prompt, and prints ✓ Promoted v<n>. Previous active: v<m>.
Every end user gets the promoted version on their next message, while a workflow run already in flight finishes on the version it started on. Promote only a version you reviewed with lua version diff.
5

Verify

Confirm the active marker moved, note the time, send one production message on a fresh thread, and check that nothing was logged since under agent_error or as an error under skill, where a throwing tool lands. lua logs has no time or environment filter, so the check bounds both types by timestamp.
Output
The * marks the active version; both jq -e lines exit 0 when nothing was logged after $since (Read logs and debug an agent).

​
Options you may need

​
Roll back to the previous version

Promote the version that was active before; lua version list shows it as superseded. A promote restores every code primitive version and the model, and touches nothing else: not the persona, environment variables, knowledge, features, channels, MCP activation, governance and model settings, devices, data the bad version wrote, or runs in flight (what an agent version snapshots).
A workflow rolls back with lua workflows deploy <workflow-name> -v <previous-version>, and the persona with lua deploy persona --set-version <n> --force.

​
Ship one webhook, job, processor, or trigger

lua deploy <type> with webhook, job, preprocessor, postprocessor, or trigger makes one pushed version live at once: on an agent under versioning it creates and promotes a new agent version that differs from the active one only in that primitive, prints its number, and writes the deployed version into lua.skill.yaml.
--set-version takes a semver or latest. lua workflows deploy <workflow-name> -v latest does the same for a workflow. MCP servers have no versions; activate or deactivate one with lua mcp activate <server-name> and lua mcp deactivate <server-name> (lua mcp reference).

​
Deploy a skill or the persona

lua deploy skill --name <skill> --set-version <v> serves that version from the agent’s next turn, on any agent, but the next lua version promote resets every skill to the version pinned in the promoted agent version. For a durable change, push, lua version create, lua version promote; for an immediate rollback of one skill, lua deploy skill --set-version <old>. A pushed persona is already live; lua deploy persona --set-version <n> --force switches the served persona to an earlier version at once, versioned agent or not, and a promote does not change it. An agent with no agent version yet is not under versioning, so every lua deploy <type> goes live at once, as lua version status says. lua deploy all --force (newest version of everything; --name and --set-version ignored) behaves the same per type and exits 0 even when it lists ⚠️ <n> deployments failed: (lua deploy reference).

​
If it isn’t working

The server’s active version is newer than the version in lua.skill.yaml, after a release from another machine or the admin dashboard. Run lua sync --pull to update local files from the server’s source backup (it refuses if you changed files since your last backup; --force overwrites them), then start again. lua version status prints the same warning with the affected rows.
The server has an active preprocessor or postprocessor that no longer exists in your code, and it keeps running on every message. Run the cleanupCommand from the same entry, for example lua preprocessors delete --preprocessor-name "<name>", then push again.
Either a later lua version promote reset the skill to the version pinned in that agent version, or --set-version latest picked the most recently created version rather than the one you meant; lua version status shows the active version per skill. Push, lua version create, and lua version promote <n> make the change durable. Exit codes 9, 10, and 11 on any release command are credential and network problems, listed on Errors and exit codes.

​
Next steps

Go-live checklist

What to check before you promote.

About releases and versions

Primitive versions, agent versions, statuses, and where lua deploy fits.

Automate releases in CI

The same commands in GitHub Actions with an approval gate.

Back up and restore agent source

What a push backs up and how to restore.

lua version reference

create, list, show, diff, promote, status, delete.