Skip to main content
Glama

deploy_template

Deploys a starter app from a catalog template, applying environment and deploy overrides, then returns the follow-up call to wait for service readiness.

Instructions

Use when: you want a starter app. Asynchronous — follow with wait_for_service.

    Resolves ``template_id`` (see ``list_app_templates``), clones its
    catalog repo server-side, and deploys it under ``name``. ``env`` and the
    deploy overrides layer over the template's defaults.
    The response carries ``summary``, ``hints``
    (never empty) and ``next_step`` — the structured follow-up call — since
    a 201 here means the build was accepted, not that the app is up.

    An existing Dockerfile retains precedence over ``build_settings``.
    Omission preserves overrides; a null field resets to repository/default.
    ``dry_run=True`` previews without writes,
    building or storing secrets. ``public_env`` passes public build-time
    variables (shown in clear in a dry run; secret references are refused);
    secret mounts are unsupported.

    If the template declares ``[ai.*]`` bindings, each is injected at launch
    as ``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the ``default`` binding also
    sets ``OPENAI_BASE_URL/OPENAI_API_KEY/OPENAI_MODEL`` — point the app's
    OpenAI SDK at these; no code change needed. WARNING: the ``secrets`` values you pass
    here transit this agent's transcript in plaintext; for high-value keys
    prefer ``nerdit secrets set`` from the CLI and deploy without ``secrets``.
    

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "template_id": "<template_id>",
      "name": "<name>"
    },
    "name": "deploy_template"
  }
}

Input Schema

NameRequiredDescriptionDefault
envNoRuntime env for the container. A value that is exactly ``${secrets[.shared].KEY}`` or ``${vars[.shared].KEY}`` resolves at launch; an unset one fails the deploy (``deploy.env_ref_unresolved``), one embedded in text is refused (``deploy.invalid``). Other values are literal; null deletes the key on redeploy. ``set_secret`` overrides an ``env`` key of the same name.
gpusNoGPUs to reserve for the container (0 = none). Omit to use the template's default, else the repo's ``[deploy].gpus``.
nameYesApp name (lowercase DNS label). A new name creates the app; an existing one redeploys it in place.
portNoPort the container listens on: the only port published and health-checked. Omit to use the template's default, else the repo's ``[deploy].port``, else 8000.
startNoStart command run inside the built image (shell syntax). Omit to use the template's default, else the repo's ``[deploy].start`` or the buildpack default.
healthNoHTTP health path probed on ``port`` (e.g. ``/health``); the app is ``healthy`` once it answers 2xx. Omit to use the template's default, else the repo's ``[deploy].health``.
vendorNoGPU vendor to reserve when ``gpus`` > 0 (``nvidia`` or ``amd``); omit to let the daemon choose on a fresh deploy — a redeploy keeps the vendor already recorded.
dry_runNotrue = validate and return the plan (what would change) with zero writes; nothing is built, deployed or audited as a change.
secretsNoWrite-only secrets for the template's required secret inputs; stored server-side right AFTER the app row is written (the row is the authorization point) and before the first launch, so a failed secret write leaves the app created. Only key names are ever read back. Omit when the template declares none.
template_idYesTemplate id from ``list_app_templates`` (its ``id`` field).
build_settingsNoBuild overrides, same keys as ``[deploy.build_settings]`` in ``nerdit.toml``: ``preset`` (node/nextjs/python/dockerfile), ``install``, ``build`` (``false`` skips compilation), ``start``, ``node_version``, ``package_manager``, ``subdir``, ``public_env`` (build-time variables baked into the bundle, never secrets). Commands run inside the build container.
idempotency_keyNoCaller-chosen key: a retry with the same key replays the first result instead of acting twice. Omit and a fresh key is minted per call, so each call acts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.2
    • changedInput schema / properties / env / description
      Previous value: -"Runtime env for the container: values are literal strings, never resolved (a ``${secrets.*}`` reference is passed through as text); a null value deletes that key on redeploy. Secrets go through ``set_secret``, which overrides an ``env`` key of the same name at launch."New value: +"Runtime env for the container. A value that is exactly ``${secrets[.shared].KEY}`` or ``${vars[.shared].KEY}`` resolves at launch; an unset one fails the deploy (``deploy.env_ref_unresolved``), one embedded in text is refused (``deploy.invalid``). Other values are literal; null deletes the key on redeploy. ``set_secret`` overrides an ``env`` key of the same name."
  2. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations at all, the description carries the full burden and does so: it declares the operation asynchronous (201 means build accepted, not app up), names the response fields summary/hints/next_step, and gives merge semantics (omission preserves overrides, null resets to repository/default). It also discloses a real side effect risk — secrets values transit the agent transcript in plaintext, with an alternative (nerdit secrets set) — plus the constraint that secret mounts are unsupported and that dry_run writes, builds, and stores nothing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the when-to-use clause and the async caveat, with the security warning placed last where it still gets read. It is dense and long, and a few clauses (Dockerfile precedence, AI binding injection) restate ground the schema already covers, but for a 12-parameter deploy with no annotations the length is largely justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-parameter mutation with no annotations and no output schema, the description covers async semantics, follow-up call, merge behavior, dry-run guarantees, and a security advisory. Gaps remain around authorization requirements and what state the app is left in when a non-secret failure occurs mid-deploy, but nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a 3 is the baseline; the description earns above that by adding cross-parameter layer semantics not captured per-field: env and deploy overrides layer over the template's defaults, and an existing Dockerfile retains precedence over build_settings. The public_env and AI-binding injection notes (NERDIT_AI_<NAME>_URL/_KEY/_MODEL, OPENAI_BASE_URL fallback) further explain how one parameter's values reach the running app.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb chain — resolves template_id, clones the catalog repo server-side, deploys under name — which is far more concrete than the tool name alone. It does not explicitly contrast itself with close siblings like deploy_git or deploy_app, so an agent must infer that this path is template-based rather than repo-based.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use when: you want a starter app" states the trigger, and it explicitly routes to the follow-up tool (wait_for_service) since the call is asynchronous. It also flags dry_run=True for preview. It stops short of naming when to prefer deploy_git/deploy_app instead, so the sibling boundary is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.