deploy_template
Deploy a starter app from a template ID and app name, then call wait_for_service to follow the asynchronous build.
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``.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 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. | |
| gpus | No | GPUs to reserve for the container (0 = none). Omit to use the template's default, else the repo's ``[deploy].gpus``. | |
| name | Yes | App name (lowercase DNS label). A new name creates the app; an existing one redeploys it in place. | |
| port | No | Port 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. | |
| start | No | Start 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. | |
| health | No | HTTP 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``. | |
| vendor | No | GPU 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_run | No | true = validate and return the plan (what would change) with zero writes; nothing is built, deployed or audited as a change. | |
| secrets | No | Write-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_id | Yes | Template id from ``list_app_templates`` (its ``id`` field). | |
| build_settings | No | Build 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_key | No | Caller-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. |