Skip to main content

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

​
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:
  • 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.
  • Nothing is created unless the deploy can succeed. Required connections are checked before anything exists: a deploy whose required capabilities can’t be satisfied fails up front with the same connections-unsatisfied error the deploy flow renders — no agent is created, nothing is billed, and nothing appears on your agent roster. And a capability you’ve already satisfied deploys without re-connecting — reuse is the default, not a special case (see Connections).
  • 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:
  • 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.
  • model — the model the agent runs on. Omit it and a freshly deployed agent takes the template’s model (when your workspace allows it); an agent that already has a model keeps it. Send "" for your workspace default, or any approved model code. The choice is yours from then on: template updates never change it.
  • allowCreatorUpdates — off by default; opt in only if you want the creator to push future versions to this install (see 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:
--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 or --env-vars.

​
After install: the template’s first run

Some templates declare a post-install first run — something the agent does the moment it’s installed, before you’ve said a word to it. It’s part of what you consent to: the confirm screen shows it as “After install, the agent will: …”, quoting the template’s own instruction. Right after a successful deploy (or install onto an existing agent), the agent performs it — typically introducing itself, checking the connections you granted, or running its own setup (a PR-review template, for example, wires provider webhooks on every repo you administer and reports back). A first run has up to two parts, in order: a setup tool the platform executes directly (deterministic — no conversation involved), then a first turn where the agent acts on the template’s instruction. What to expect:
  • It runs once. A given instruction runs at most once per install — re-installing, or updating to a version that keeps the instruction unchanged, doesn’t repeat it. An update that changes the instruction runs the new one once.
  • It never blocks or breaks the install. The install returns as soon as the agent is live and its automations are armed; the first run happens in the background (on a one-call deploy, only after your access to the new agent is registered). A setup-tool failure is recorded on the install rather than failing it.
  • You can see how the setup went. GET /agents/:agentId/templates reports setup as running, ok, or failed for a template that declares a setup tool; the desktop shows the same next to the install. A failed setup tool can be re-run with POST /agents/:agentId/templates/:templateId/setup/retry — the retry runs only the tool, never a second first turn.
  • It acts as you. Both parts carry your identity — the setup tool runs with your connections, and anything user-scoped the turn does (an inbox card, a memory note) lands with you, the installer.

​
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

Some templates declare a pre-removal cleanup. Like the post-install first run, it’s shown to you before you commit: the uninstall confirmation reads “Before removal, the agent will: …”, quoting the template’s own copy. The cleanup runs before anything is torn down — while the template’s skills, connection bindings, and trigger URLs still work — so the agent can undo external state the install created (deregister provider webhooks, close out third-party resources) and say goodbye. Three guarantees:
  • It runs as you, the person uninstalling — with your connections, the same as the install did.
  • It can never block removal. Cleanup is best-effort: a deterministic cleanup tool is given a bounded run, a goodbye turn a bounded grace, and then teardown proceeds regardless.
  • You see the outcome. The uninstall result reports whether cleanup ran and whether it succeeded — a failed cleanup is visible, never silent, and never turns into a failed 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 — including the platform-written LUA_TRIGGER_URL__* trigger-URL variables — while 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.
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.