Skip to main content
Glama

deploy

Builds and runs a local app folder, exposing it at a URL, or rolls back to the previous image. Asynchronous—follow with wait_for_service.

Instructions

Use when: the source is a local folder. Asynchronous — follow with wait_for_service.

    Deploys that folder (build + run + URL), or rolls back with
    ``rollback=True``. The response carries ``next_step`` — a machine-shaped
    ``{tool, args, why}`` naming the very call to make next — because a 201
    here means "the build was accepted", never "the app is up".

    ``path`` is read by the process serving this tool, so it works only on
    the local ``nerdit mcp`` process; on a remote/HTTP connection it is
    refused with ``mcp.local_path_unavailable``. Use ``write_app_files`` +
    ``deploy_app`` there, or ``deploy_git`` / ``deploy_template``.
    ``rollback=True`` needs no path and works over either transport.

    If the app's ``nerdit.toml`` 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. ``dry_run=True``
    returns the build/config plan diff (env key names only, values never).

    ``nerdit.toml`` ``[deploy]`` keys — anything else is IGNORED and
    reported back in the response ``hints``: ``name``, ``port``, ``gpus``,
    ``start``, ``health``, ``health_type`` (``http``|``tcp``),
    ``memory_limit``, ``cpu_limit``, ``volumes``, ``release``, ``cutover``,
    ``auto_deploy``, ``edge_auth``, ``forward_authorization``, ``build_settings``.
    Generated Node builds run
    ``scripts.build`` automatically;
    override it through ``[deploy.build_settings]`` or use a Dockerfile.

    ``release`` runs once inside the new image before traffic moves; if it
    fails the deploy settles ``failed`` and the image reverts, never the data —
    whatever the migration already committed stays, so write idempotent
    migrations. ``cutover`` null = zero-downtime swap
    when eligible, false = same-port swap.
    On a successful non-dry-run deploy the
    response carries ``summary`` (app/status/version/public_url; ``summary.public_url`` is the
    preferred address: trusted domain, then hosted, then local), ``hints``
    (ordered one-liners, never empty) and ``next_step`` (the structured
    follow-up call); a ``dry_run`` plan and a ``rollback`` response carry
    none of the three — read a plan's advisories from its ``warnings``. On a
    node in ``path`` proxy mode the local URL serves the app at ``/<name>/``,
    so a frontend reached there must be built with that base path (never for
    a hosted or domain URL, which serve at the root; the hint is omitted when
    one exists); in ``subdomain`` mode it is served at the root of its own
    hostname and needs none — read ``capabilities.proxy.mode``.

    ``build_settings`` overrides
    preset/install/build/start/node_version/package_manager/subdir/public_env.
    ``preset`` selects node/nextjs/python/dockerfile; null resets to
    repository/default detection.
    An existing Dockerfile retains precedence.
    Omit it to preserve saved overrides; a null field resets to repository/default,
    and ``build: false`` skips compilation.
    ``public_env`` passes public build-time variables (shown in clear in a dry
    run; secret references are refused). Secret mounts are unsupported;
    runtime env is unchanged.

    SANDBOX: by DEFAULT containers run with all Linux capabilities dropped
    (``cap_drop=["ALL"]``) and no-new-privileges — both are operator settings
    (``[containers].drop_all_caps`` / ``[containers].no_new_privileges``), so
    read the live profile in ``capabilities.sandbox`` rather than assuming: an
    operator may have relaxed it. Under that default, an image whose entrypoint
    does root work — ``chown``/``chmod`` of its own runtime dirs, dropping
    privileges via ``setuid``/``setgid``, writing ``/var/run`` — dies before
    your app ever starts. Stock ``nginx`` is the classic trap. Use a non-root
    image and a non-root ``USER`` that owns the files it writes: for a static
    site, ``nginxinc/nginx-unprivileged`` (listens on **8080**, so set
    ``port=8080``) or any tiny static server. A crash from this reports
    remediation code ``image_needs_privileges`` in ``diagnose_service``. PORT
    CONTRACT: the container MUST listen on the declared ``port`` (the tool
    argument, else ``nerdit.toml`` ``[deploy].port``, else **8000**) — that is
    the only port the daemon publishes and health-checks, so listening anywhere
    else fails the health probe with a healthy-looking container. A port below
    1024 is NOT the reason a root entrypoint is needed: every container runs on
    the docker bridge in its own network namespace (never host networking),
    where Docker sets ``net.ipv4.ip_unprivileged_port_start=0``, so binding 80
    needs no capability and no root — the chown/setuid work does.
    

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "deploy"
  }
}

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 ``[deploy].gpus``, else the count already recorded on a redeploy, else 0.
nameNoApp name (lowercase DNS label); an existing name redeploys it in place. Omit to use the folder's ``nerdit.toml`` ``[deploy].name``, else the folder's own name. Required with ``rollback=True``.
pathNoPath to the app folder ON THE DAEMON HOST (``~`` expanded); its contents are zipped and uploaded. Required unless ``rollback=True``. Usable ONLY from the local ``nerdit mcp`` process: over a remote/HTTP connection to a daemon it is refused with ``mcp.local_path_unavailable``, since it would read that host's disk and not yours — send the source with ``write_app_files`` + ``deploy_app`` instead.
portNoPort the container listens on: the only port published and health-checked. Omit to use ``nerdit.toml`` ``[deploy].port``, else the port already recorded on a redeploy, else 8000.
startNoStart command run inside the built image (shell syntax). Omit to use ``[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 keep ``[deploy].health`` (or the existing app's probe on redeploy).
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.
rollbackNotrue = re-point the service at its previous image instead of building: only ``name`` and ``idempotency_key`` are read, no folder is zipped and every other argument is ignored. Refused together with ``dry_run``.
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.6/5.0
Behavior5/5

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

No annotations are provided, and the description carries the full behavioral burden well: it states the operation is asynchronous and must be followed by wait_for_service, that a 201 means accepted not running, how path behaves over transport, what rollback does, how release failures affect data, and sandbox/port failure modes. This is unusually rich operational context beyond the schema.

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?

The description is long, but it is front-loaded with the core when-to-use rule and organized into clear operational paragraphs. Some details repeat the schema or could be deferred, but for a 12-parameter deployment tool with no annotations, most sentences earn their place.

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

Completeness5/5

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

There is no output schema, and the description still explains response fields, next_step behavior, dry_run/rollback response differences, and key failure modes. It also covers transport limitations, environment injection, build settings, sandbox constraints, and the port contract, making it complete enough to call correctly.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already documents all 12 parameters in detail. The description adds some cross-parameter context, such as rollback needing no path and working over either transport, but most parameter-level information duplicates the schema.

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

Purpose5/5

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

The description names a specific operation and scope: it deploys a local app folder (build + run + URL), or rolls back with rollback=True. It also distinguishes itself from siblings such as deploy_app, deploy_git, and deploy_template, so an agent can identify the right tool without opening the schema.

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

Usage Guidelines5/5

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

It gives an explicit selection rule: use when the source is a local folder, and use write_app_files + deploy_app over remote/HTTP connections. It also explains rollback usage and names deploy_git / deploy_template as alternatives, leaving little to inference.

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