Skip to main content

​
What an agent template is

An agent template is a published, versioned snapshot of an agent’s entire deployable manifest: its skills, webhooks, jobs, preprocessors, postprocessors, triggers, and model — everything lua push and lua version promote manage together as one agent version. Publishing a template freezes one agent’s promoted version into a reusable blueprint. Installing a template materializes that blueprint’s primitives onto a different agent and promotes a new version there. It’s the same mechanism you’d use to release your own agent, applied to someone else’s agent (with their consent), or to your own fleet of near-identical agents.
Looking for the single-tool equivalent? See Skills — a skill is one reusable tool; a template is an entire agent.

​
What a template never touches

Installing or applying a template never changes:
  • Persona — the target agent’s system prompt / instructions stay exactly as they were.
  • Environment variable values — templates declare which variables must exist (the env contract, below); actual values are always set per-agent via lua env.
  • Channels / connected numbers — WhatsApp numbers, Slack workspaces, phone numbers, etc. are per-agent and never move.
  • Agent name or metadata — the target agent keeps its own identity.
A template is purely a bundle of behavior — what the agent can do — never identity or secrets.

​
The env contract

A template version can declare an env contract: a list of variable names the template’s primitives expect, each with a description and a required/optional flag — never values. At install (or fleet apply) time, the CLI checks the target agent for each required variable, either already set via lua env or supplied inline with --env-vars. Missing required variables block the install with a clear list of what’s missing; pass --skip-env-check to bypass the check if you’re setting values separately.
KEY=description marks a variable required; KEY?=description marks it optional. If you omit --env-contract entirely when publishing a new version, it inherits the previous version’s contract unchanged.

​
Publishing a template

1

Create the template from your agent

Run this from a project connected to the agent you want to turn into a template. Templates are private by default — only your organization can find and install them until you choose otherwise.
Add --visibility public to make it publicly discoverable, or --description for a longer blurb.
2

Publish a version

A template with no published version can’t be installed. Publishing freezes the manifest from an agent version — by default, whichever version is currently active on the source agent.
Use --source-version <n> to freeze a specific promoted version instead of whatever’s currently active — useful if you’re iterating on the source agent and want to publish a known-good point, not your latest in-progress changes.
3

Iterate

Keep improving the source agent as normal (lua push, lua version create, lua version promote). When you’re ready to ship the improvements to everyone who installed the template, publish a new version and apply it.

​
Installing a template

This materializes the template’s primitives onto the current agent (whichever agent your project is connected to) and promotes a new agent version there, with a message like Applied Support Bot v3. Everything the template manages is now live; everything else about your agent — persona, env values, channels, name — is untouched. Add --version <n> to install a specific published version instead of the latest, and --allow-creator-updates if you want the template’s creator to be able to push future versions onto this agent via their own apply (see Consent below). This is off by default — installing a template never gives its creator ongoing write access unless you explicitly grant it.

​
Rollback is just version promotion

Because installing a template is really just promoting a new agent version, rolling back needs nothing template-specific:
Re-installing an older template version (lua marketplace template install --template-id tpl_abc --version 2 --force) is also a legitimate rollback — it re-materializes that version’s manifest and promotes it as the new active version.

​
Rolling out updates to a fleet

Template creators can push a version out to many agents at once with apply — the fleet-operations counterpart to install.
apply runs asynchronously on the server — the CLI starts the run, polls it, and prints a per-target result table when it finishes (pass --no-wait to get the run ID back immediately and check on it later):
Any failed target — including one that was skipped for missing env values or a lack of consent — marks the whole run failed and makes the CLI exit non-zero, so a partial rollout doesn’t look like a clean success in CI. The successful targets in the same run are unaffected; only the failed ones need attention (and a re-run of apply is safe to retry).
Canary first. Before rolling a version out to your whole fleet, apply it to a handful of agents with --agents and check the result table (and the agents themselves) before running --all-installed. There’s no separate “canary” flag — it’s the same command, aimed at a smaller target list.
apply only ever reaches an agent that installed the template and opted in with --allow-creator-updates at install time. An agent that installed without opting in is simply skipped by apply — from the creator’s side, that agent doesn’t appear as a distinct failure reason, so a creator can’t use apply’s results to probe which agents installed their template without consent. If you want a template’s creator to keep shipping you updates, install (or re-install) with --allow-creator-updates.

​
The managed-primitives rule

Everything a template installs or applies is managed by it going forward: the next apply overwrites any local edits you made to those specific primitives, and removes any that the new version dropped. Anything else on the agent — including primitives you added yourself that the template never touched — is left alone. If you’ve hand-modified a template-managed skill and don’t want the next apply to overwrite it, either stop consenting to creator updates (don’t set --allow-creator-updates) or fork the skill under a different name outside the template’s manifest.

​
Fleet visibility

status prints the fleet’s install ledger — every agent that has this template installed, which version, and when it was last applied. There’s no fleet-wide rollback command: roll an individual agent back with lua version promote <n> run against that agent directly (the same rollback path as any other agent version).

​
Walkthrough: onboarding merchants from one template

A common shape: you build and tune a single merchant’s support agent by hand, then use it as the starting point for every merchant you onboard afterward — and keep them all current as you improve it.
1

Build and tune the reference agent

Stand up one merchant’s agent the normal way: skills for order lookup and refunds, a webhook for their order-status provider, a job that syncs inventory nightly. Push, create a version, promote it, and use it in production until you’re happy with it.
2

Publish it as a template

3

Onboard each new merchant

For every new merchant, create their agent, then install the template with that merchant’s own credentials:
Each merchant’s agent now runs the same skills, webhook, and job — with their own persona (set separately) and their own credentials. --allow-creator-updates opts them into future fleet rollouts; a merchant who wants to freeze their configuration and manage updates manually can leave it off.
4

Ship an improvement to everyone at once

You add a shipping-delay-notice skill and fix a bug in the refund webhook on the reference agent, then publish v2 and roll it out:
5

Check the fleet, and roll back one merchant if needed

If one merchant’s agent needs to go back to v1 while the rest stay on v2, that’s a normal per-agent version promotion — it doesn’t affect the template or any other merchant: