> ## 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. # Agent templates > Published, versioned blueprints of a whole agent that other organizations install, update with consent, and monitor An agent template is a published, versioned copy of a working agent: one promoted [agent version](/concepts/releases-and-versions) frozen together with the sections an installer fills in. It exists so a tuned agent can be reproduced for many clients or sites and kept in sync as it improves, without copying source between projects. ## How a template is published and installed Publishing freezes a source agent's promoted version (its skills, webhooks, jobs, preprocessors, postprocessors, triggers, workflows, and model settings) into a template version, together with an env contract and the seven authored sections of the `template:` block in `lua.skill.yaml`. Voices and device triggers are not frozen: a source agent that has either is refused with `UNSUPPORTED_SOURCE`. The sections: * `connections` declare what the agent plugs into as capabilities ("a CRM"), each satisfiable by any listed platform and marked required or optional. * `personaTemplate` carries the persona with `{{variables}}`, a typed declaration per variable, and whether the installer may edit the rendered text. * `triggerPresets` give each schedule and event trigger an on/off default and the parameters the installer may change. * `paramsMeta` types the install-time parameters: display name, default, allowed values, and when a field is shown. * `onInstall` names a tool to run as the installer right after install and/or one instruction for a single background agent turn. * `onUninstall` does the same before teardown, best-effort. * `installPolicy` (`perWorkspace`) limits an installer to one install (`single`) or allows any number (`multiple`). The env contract is declared at publish with `--env-contract KEY=description` (`KEY?=description` for optional) and lists variable names, never values; an install that lacks a required variable is refused with the missing names. Installing materializes the template as a working agent, either one created for the install or an agent you already run. The installer supplies the per-install answers: environment values, persona variables, connections, and which triggers to arm. The CLI answers environment values only (`--env-vars`) and arms the recommended trigger defaults; persona variables, connection choices, and trigger overrides come from the desktop install form or the REST install body, so a template whose persona has a required variable without a default cannot be installed from the CLI. Connections you have already granted are reused; only gaps are requested, and when two connections could satisfy a capability you are asked which to use. A template never writes an existing agent's environment values, channels, or name, and an agent that already has a persona keeps it; the full list is under [What installers agree to and keep](/marketplace/lints-and-consent#what-installers-agree-to-and-keep). Installing promotes a normal agent version, so `lua version promote ` on that agent is the rollback. Visibility is `private` (your organization only) or `public`. Each version of a public template is reviewed before anyone else can install it and carries a status of `pending`, `approved`, or `rejected`. An organization can also set a policy on what its members may install: a template is allowed, requires approval (the install is queued as a request), or is blocked with `POLICY_BLOCKED`. Updates are consent-based. An install opts in with `--allow-creator-updates`; publishing a version then applies it to every consenting install that is behind (for a public template, once the version is approved), and `--skip-auto-apply` holds a version back for a manual `apply`. Each version carries a hash of its consent surface (connections and their scopes, trigger instructions, shipped workflows, and required environment keys); when that hash changes, the update is refused per install with `RECONSENT_REQUIRED` until the installer reviews and accepts it, whether or not they opted in. Fleet rollouts use `lua marketplace template apply --template-id --all-installed --force` (or `--agents ` or `--file ` for a subset), at most 500 targets per run; one failed target marks the run failed and the command exits 1. `lua marketplace template status` shows who runs which version, and `lua marketplace template health --window-days ` reports workflow health per install. ## Agent templates, marketplace skills, and project scaffolds Three things are called "template" and only one is this page. An agent template is a whole agent. A [marketplace skill](/marketplace/skills) is one reusable skill you install into an agent you already have; it is versioned with semver and managed with `lua marketplace skill`. The [project scaffold](/get-started/project-structure) is the set of files `lua init` generates: a starting point for source, not a published artifact. WhatsApp message templates, the pre-approved outbound message formats, are unrelated. ## When to use it * You build the same agent for many clients: publish once, install per client, and roll improvements out with `apply`. * A client operator must run the agent without engineers: the install flow asks only for values and connections, and everything else is managed. * Use a marketplace skill instead when you want to add one capability to an existing agent. * Use `lua init --from-agent-id ` instead when you want an independent copy you will edit, with no link to the source. ## Limits | Item | Value | | --------------------------------------- | ------------------------------------------------------------------------------- | | `onInstall` / `onUninstall` instruction | 1 to 2000 characters, plain text | | Template versions | Sequential integers per template | | `installPolicy.perWorkspace` | `single` or `multiple` (default) | | `health --window-days` | 1 to 90; default 7; larger values are clamped to 90 | | `apply` targets | 500 per run | | `apply` polling | Every 3 seconds for 30 minutes, then exit 1 while the run continues server-side | ## Next steps Draft, author the sections, publish, and roll out. Install, connect, update, and uninstall as the installer. Every field of the `template:` section. Status and health across every install.