> ## 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

> Publish, install, and roll out full agent configurations across a fleet

## 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`](/cli/skill-management) and [`lua version promote`](/cli/version-command) 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.

<Note>
  Looking for the single-tool equivalent? See [Skills](/marketplace/creator-guide) — a skill is one reusable tool; a template is an entire agent.
</Note>

### 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`](/cli/env-command).
* **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.

```bash theme={null}
# Declare the contract when publishing a version
lua marketplace template publish \
  --template-id tpl_abc \
  --env-contract "STRIPE_KEY=Stripe secret key for the checkout skill" \
  --env-contract "SUPPORT_EMAIL?=Fallback contact address"

# Satisfy it at install time
lua marketplace template install \
  --template-id tpl_abc \
  --env-vars "STRIPE_KEY=sk_live_xxx" \
  --force
```

`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

<Steps>
  <Step title="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.

    ```bash theme={null}
    lua marketplace template create \
      --name support-bot \
      --display-name "Support Bot"
    ```

    Add `--visibility public` to make it publicly discoverable, or `--description` for a longer blurb.
  </Step>

  <Step title="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.

    ```bash theme={null}
    lua marketplace template publish \
      --template-id tpl_abc \
      --changelog "Initial release: FAQ skill + escalation webhook"
    ```

    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.
  </Step>

  <Step title="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](#rolling-out-updates-to-a-fleet) it.
  </Step>
</Steps>

## Installing a template

```bash theme={null}
lua marketplace template install \
  --template-id tpl_abc \
  --env-vars "STRIPE_KEY=sk_live_xxx" \
  --force
```

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](#consent-and-fleet-updates) 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:

```bash theme={null}
lua version promote <previous-version-number>
```

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`.

```bash theme={null}
# A named set of agents
lua marketplace template apply \
  --template-id tpl_abc \
  --agents agent_1,agent_2,agent_3 \
  --force

# Every agent that has already installed this template
lua marketplace template apply --template-id tpl_abc --all-installed --force

# A larger list from a file, one agent ID per line
lua marketplace template apply --template-id tpl_abc --file targets.txt --force
```

`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):

```
Apply run failed (run_xyz)
AGENT ID   STATUS     LOCAL VERSION  ERROR
agent_1    applied    v4
agent_2    applied    v5
agent_3    failed     v3             Missing required environment variables: STRIPE_KEY
```

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).

<Tip>
  **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.
</Tip>

### Consent and fleet updates

`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

```bash theme={null}
# Which agent runs which version, and when it was applied
lua marketplace template status --template-id tpl_abc

# All published versions of a template
lua marketplace template versions --template-id tpl_abc

# The exact manifest a specific version distributes
lua marketplace template view --template-id tpl_abc --version 3
```

`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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Publish it as a template">
    ```bash theme={null}
    lua marketplace template create \
      --name merchant-support \
      --display-name "Merchant Support Bot"

    lua marketplace template publish \
      --template-id tpl_merchant \
      --changelog "v1: order lookup, refunds, nightly inventory sync" \
      --env-contract "ORDER_API_KEY=Per-merchant order-provider API key" \
      --env-contract "REFUND_WEBHOOK_SECRET=Signing secret for the refund webhook"
    ```
  </Step>

  <Step title="Onboard each new merchant">
    For every new merchant, create their agent, then install the template with that merchant's own credentials:

    ```bash theme={null}
    lua marketplace template install \
      --template-id tpl_merchant \
      --env-vars "ORDER_API_KEY=mk_live_...,REFUND_WEBHOOK_SECRET=whsec_..." \
      --allow-creator-updates \
      --force
    ```

    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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    lua marketplace template publish \
      --template-id tpl_merchant \
      --changelog "v2: shipping-delay notices, refund webhook fix"

    # Canary against a couple of merchants first
    lua marketplace template apply \
      --template-id tpl_merchant \
      --agents agent_merchant_12,agent_merchant_47 \
      --force

    # Then the rest of the consenting fleet
    lua marketplace template apply --template-id tpl_merchant --all-installed --force
    ```
  </Step>

  <Step title="Check the fleet, and roll back one merchant if needed">
    ```bash theme={null}
    lua marketplace template status --template-id tpl_merchant
    ```

    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:

    ```bash theme={null}
    lua version promote <n>   # run against that merchant's agent
    ```
  </Step>
</Steps>

## Related

* [Marketplace Command reference](/cli/marketplace-command)
* [Version Command](/cli/version-command) — the underlying agent-version mechanics `install`/`apply` build on
* [Environment Variables Command](/cli/env-command) — setting per-agent env values
* [Publishing Skills](/marketplace/creator-guide) / [Installing Skills](/marketplace/installer-guide)