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

# Deploying Templates

> Deploy an agent template in minutes: reuse your connections, confirm your automations, operate and update the install

## Two ways to get a template running

* **One-call deploy** — the consumer path. Pick a template from the catalog and deploy: a fresh agent is created for you and the template installed onto it in one call. You never need to know what "an agent" is first.
* **Install onto an existing agent** — the advanced path, for an agent you already run (behind a picker in the app, or `lua marketplace template install` from the CLI). Installing onto a shared/org agent requires org-admin rights on that agent.

Either way, the deploy flow only asks for what's genuinely missing: connections you've already granted are reused silently, and a fully-satisfied deploy goes straight from overview to confirm.

This page follows the installer's side of **Standup Sidekick** — a template that captures your wins during the day, nudges you before standup on a schedule, and optionally posts to Slack. Its creator's side is the running example in [Publishing Templates](/marketplace/publishing-templates).

## One-call deploy

`POST /marketplace/templates/:id/deploy` creates a fresh agent in your default org (pass `orgId` to target another org you belong to, and `displayName` to name the agent), installs the template's version onto it, promotes the first agent version, and registers you as the agent's admin. The response tells you exactly what went live:

```json theme={null}
{
  "agentId": "…",
  "agentVersion": 1,
  "status": "installed",
  "armedTriggers": ["standup-nudge"],
  "blockedTriggers": [
    { "key": "post-to-slack", "reason": "optional connection declined" }
  ],
  "personaSkipped": false
}
```

* **Idempotency** — send an `Idempotency-Key` header. A retry with the same key returns the original outcome and **never creates a second agent**, so a timed-out request is always safe to resend.
* **Rollback on failure** — if the install fails after the agent was created, the agent creation is rolled back; a retry starts clean.
* **"Live from minute one" means workspace chat.** A freshly deployed agent has no external channels (WhatsApp, email, Slack as a *channel*) until you connect them — templates that need one declare it, and your install shows a setup checklist ("connect WhatsApp to go live") instead of a false green.

## Installing onto an existing agent

The install request carries everything the deploy flow collected:

```json theme={null}
{
  "version": 3,
  "envValues": { "STANDUP_HOUR": "9" },
  "connectionSelections": {
    "notify": { "type": "slack", "connectionId": "conn_x" }
  },
  "triggerOverrides": {
    "standup-nudge": { "enabled": true, "params": { "preset.seconds": 600 } }
  },
  "personaVars": { "COMPANY_NAME": "Acme", "TONE": "brief and encouraging" },
  "allowCreatorUpdates": false
}
```

* `connectionSelections` — which of your connections satisfies each declared capability (reused or freshly connected).
* `triggerOverrides` — which automations to arm, with your values for any installer-editable parameters.
* `personaVars` — your answers for the persona's `{{variable}}` slots. If the template's persona is marked editable, you may instead submit an edited resolved prompt, which is stored verbatim.
* `allowCreatorUpdates` — off by default; opt in only if you want the creator to push future versions to this install (see [Updates](#updates)).

Two persona rules protect the agent you already have: **an existing persona is kept** — overwriting it with the template's is an explicit opt-in, never a default — and everything else about your agent that the template doesn't manage (your own skills, env values, channels, name) is untouched.

From the CLI, the equivalent for fleet and development work:

```bash theme={null}
lua marketplace template install \
  --template-id tpl_standup \
  --env-vars "STANDUP_HOUR=9" \
  --allow-creator-updates \
  --force
```

<Note>
  `--skip-env-check` no longer does anything: the env-contract check is always enforced server-side. The flag is accepted for old scripts but only prints a deprecation warning. Satisfy the contract with [`lua env`](/cli/env-command) or `--env-vars`.
</Note>

## Connections: reuse what you already have

Before asking you for anything, the deploy flow reconciles the template's declared capabilities against the connections you (and your org) already hold:

* **Already connected** → skipped silently and bound. "3 of 4 already connected" renders before you do anything — often it's all of them.
* **Multiple matches** → if more than one of your connections could satisfy a capability (a personal Google Calendar *and* the org's, say), you're asked which to use — never auto-picked. The choice matters: the agent will act using that account's access.
* **Missing, required** → a connect chip. Pick a platform from the capability's list (any one satisfies it — "a CRM" can be Salesforce *or* HubSpot), grant access once, and the flow advances. Install is blocked until every required capability is satisfied.
* **Missing, optional** → offered, never blocking. Decline it and the parts of the agent that depend on it stay safely inactive — the install response lists them as blocked, and you can connect later.
* **Connected but with too little access** → a read-only grant never silently binds to a template that writes; you're asked to reconnect with more access instead of hitting failures at runtime.

Reusing a connection never moves or copies your grant — it binds *this agent's* use of it. Personal connections bind only to your own agents; shared/org agents use org-shared connections. If a bound connection is later revoked or its owner leaves the org, the dependent parts of the agent stop safely and you're prompted to reconnect or rebind — never a half-broken agent silently erroring.

**Rebinding later** (switching a capability to a different connection) is a re-run of the install at your same version with a new selection — it doesn't change the template version and doesn't touch your other settings.

## Automations: nothing arms silently

The template's triggers arrive as **presets** — recommended defaults, shown with what each one does and, for schedules, the next run times in *your* timezone. The rules, in your terms:

* **A fresh install arms exactly what you confirmed.** Deploy ends with an explicit confirmation listing the automations going live. Anything you didn't confirm is installed disabled. Anything event-driven or outbound defaults to off until you say so.
* **Editable parameters are validated, not clamped.** If the creator allowed "nudge every N minutes", your value is checked against the declared bounds — whole minutes only, so `90` seconds is rejected with a clear field error before anything is created.
* **Toggling later doesn't need a version change.** Re-submitting your same installed version with an override for one trigger changes just that trigger — settings you don't mention carry forward unchanged, never reset.
* **Creator updates never arm anything new.** New or renamed triggers in an update land disabled awaiting your confirmation, and a trigger you paused stays paused — even on a creator-pushed update.
* **Schedules run on your clock.** A template authored in Stockholm doesn't run at Stockholm time for you — the schedule's timezone is yours, shown explicitly at confirm.

## Operating the install

Your installed-templates view shows, per install:

* **Installed version and update availability** — the installed version, plus one action: *Update to latest* (once approved). Version browsing and rollback are creator/org-admin surfaces, not something you manage.
* **Automation health and next runs** — each trigger's armed state, health, and upcoming fire times. An armed schedule that isn't actually firing is flagged, not silent.
* **Connection binding health** — which connection backs each capability and whether it's healthy, paused, or needs reconnecting.
* **Outcomes** — the template's declared units of work, counted by the platform from real side effects: "342 follow-ups sent this month", never self-reported by template code.
* **Executions** — run history for the template's jobs and triggers, same as any of your agent's own.

## Updates

Accepting an update is one action, and it's previewed first: the changelog, what's added/removed/changed, any **scope or connection changes** (which always require your fresh consent, even if you opted into creator updates), and which of your armed automations survive.

What survives an update, guaranteed:

* **Your persona edits.** If you tuned the agent's persona after install, the update skips the persona write and says so — "re-apply template persona" is a separate explicit action.
* **Your schedule tweaks.** An interval you changed from 5 to 10 minutes is re-applied over the new version's preset. If the new version's allowed range no longer permits your value, the update blocks with a field error asking for a new value — never a silent replace.
* **Your armed set.** Triggers keep the state you left them in; genuinely new triggers land disabled.
* **Your bindings and values.** Existing connection bindings and param values carry forward; only genuinely new requirements prompt you.

If you never opt into creator updates, nothing changes on your agent until you accept an update yourself. If you do opt in, only **code-only** improvements flow automatically — anything that changes what the template can access or is instructed to do comes back to you for consent.

## Uninstall

Uninstalling removes what the install brought and nothing else:

**Removed:** every primitive the template manages (its skills, jobs, webhooks, triggers), its connection bindings (the agent's *use* of your connections — your underlying grants are never touched), its event subscriptions, and **only the env keys this install introduced** — pre-existing keys, and keys another install also relies on, are kept. A new clean agent version is promoted.

**Kept:** the persona (it became the agent's identity at deploy; yanking it would break a running agent mid-conversation — reset it separately if you want), your own local skills and primitives, your channels, and your env values that predate the install.

```bash theme={null}
lua marketplace template uninstall --template-id tpl_standup --force
```

Deleting the whole agent runs the same teardown for every template on it — no orphaned grants or schedules survive the agent they served.

## Org template policy

Orgs govern what their members deploy. The policy has an allow/deny list, an approval mode, and a catalog on/off toggle for members.

**As a member:**

* A template your org blocks shows as *blocked by your org* up front — the deploy flow is suppressed, not failed at submit.
* In **approval mode**, your deploy submits as a request instead of executing. Your answers are kept; when an org admin approves, the deploy runs as *you* — with your connections, re-validated at execution, so a connection you revoked while it sat in the queue fails safely rather than deploying stale.
* Once you've installed something, your own updates and rebinds don't re-enter the approval queue — unless the update changes what the template can access, which requires consent anyway.

**As an org admin:**

* Set the policy: allowed/denied templates, approval mode, and whether members see the catalog at all. An admin's own deploys self-approve without queueing.
* Review pending install requests from the org installs view; a request from a since-deactivated member is voided, never executed.
* See every template install across the org's agents — filterable by template, by owner, by status. The pre-offboarding question "what has this person's identity bound, org-wide?" is one query, and when someone leaves, rebind prompts for their bindings route to you rather than a deactivated account while an agent sits dark.

## Related

* [Agent Templates](/marketplace/agent-templates) — the model: what a template contains, lifecycle, consent
* [Publishing Templates](/marketplace/publishing-templates) — the creator's side
* [Marketplace Command reference](/cli/marketplace-command)
* [Environment Variables Command](/cli/env-command)