> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ntropii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy to production

> Deploy a runbook + bind it to an entity in a single ntro workflow create --path command. CLI for humans, MCP for coding agents.

Once your runbook passes [local tests](/deploy-and-run/testing-locally), shipping it is one command:

```bash theme={null}
ntro workflow create \
  --path ./runbooks/nav-monthly/ \
  --tenant acme-fund \
  --entity acme-spv1 \
  --schedule "0 8 5 * *" \
  --timezone Europe/London
```

`ntro workflow create --path` does runbook deploy **and** workflow binding in a single move:

1. **Deploy** — uploads the runbook bundle (workflow\.py, activities.py, models.py, skill.md + frontmatter) to the worker. The worker registers the workflow type with Temporal.
2. **Bind** — creates a workflow row that points at the deployed `runbookSlug` and the entity it should run for, optionally on a schedule.

Both pieces are also available via [MCP tools](/tooling/mcp-server) — coding agents call `ntro_workflow_create` from the chat.

## Prerequisites

* An entity bound to a tenant ([Configure environment](/get-started/configure-environment)).
* Local tests passing for the runbook (`ntro workflow test`).
* A runbook bundle at `./runbooks/<slug>/` containing `runbook.md` (with frontmatter) and `templates/`.

## Deploy + bind

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Deploy runbook + create workflow + schedule
    ntro workflow create \
      --path ./runbooks/nav-monthly/ \
      --tenant acme-fund \
      --entity acme-spv1 \
      --schedule "0 8 5 * *" \
      --timezone Europe/London

    # Update runbook code only (no --entity = no workflow row)
    ntro workflow create \
      --path ./runbooks/nav-monthly/ \
      --tenant acme-fund

    # Pin the workflow to the version deployed by THIS command
    # (without --pin, the workflow follows whatever's currently on the worker)
    ntro workflow create \
      --path ./runbooks/nav-monthly/ \
      --tenant acme-fund \
      --entity acme-spv1 \
      --pin
    ```

    The CLI parses the runbook bundle, uploads it, and (when `--entity` is set) creates a workflow row. Per [N-80](https://linear.app/byng/issue/N-80), the workflow is anchored to the runbook's `slug` — the same runbook can back many workflows across tenants and entities.
  </Tab>

  <Tab title="From a coding agent (CLI shell-out)">
    ```text theme={null}
    "Deploy runbooks/nav-monthly to acme-fund, bind it to acme-spv1
    on a monthly-5th-of-month schedule."
    ```

    Claude Code (or any coding agent with shell access) runs the same `ntro workflow create --path` command. Output appears inline in the chat.
  </Tab>

  <Tab title="MCP (coding agent)">
    Use the `ntro_workflow_create` tool from the [MCP server](/tooling/mcp-server). The agent calls it with `runbookSlug + entityId + schedule`, gets back the workflow id, and can then trigger a smoke run via `ntro_workflow_run`.
  </Tab>
</Tabs>

### The runbook bundle contract

A runbook directory must contain:

* `runbook.md` — YAML frontmatter (slug, version, config schema) + the LLM-facing skill body.
* `templates/workflow.py` — `@runbook.defn` class subclassing `NtroWorkflow`.
* `templates/activities.py` — `@activity.defn` functions for the deterministic side effects.
* `templates/models.py` — Pydantic models for activity inputs / returns.
* Optionally a `templates/requirements.txt` to pin any additional pip packages the runbook needs.

See [Build runbooks](/workflows/runbooks/overview) for the authoring walkthrough and [skill definitions](/workflows/runbooks/skill-definitions) for the frontmatter contract.

## Versioning and rollback

Runbook versions are read from `runbook.md` frontmatter at deploy time. Each `ntro workflow create --path` call uploads a fresh version under `/workflows/<slug>/<version>/` on the worker — older versions stay on disk.

The workflow row carries an optional `runbookVersion`:

* **Unpinned (default)** — `runbookVersion: null`. Each task dispatches to whichever version is currently latest on the worker. New deploys take effect for new tasks immediately.
* **Pinned (`--pin`)** — `runbookVersion: "0.1.0"`. Tasks dispatch only to that exact version; newer deploys don't affect this workflow until you re-pin.

To roll back, re-pin to the older version (after re-uploading it if you've already overwritten on the worker):

```bash theme={null}
ntro workflow create \
  --path ./runbooks/nav-monthly@0.0.9/ \
  --tenant acme-fund \
  --entity acme-spv1 \
  --pin
```

In-flight tasks continue on the version they started with.

## Triggering a run after deploy

`ntro workflow create` makes a workflow *available*. To execute it, trigger a run:

```bash theme={null}
ntro workflow run nav-monthly \
  --tenant acme-fund \
  --entity acme-spv1 \
  --period 2026-03
```

`workflow run` returns a task ID. Use [`ntro run status`](/tooling/ntro-cli#ntro-run-inspect-executions) to follow it, or watch in the Tenant UI.

A coding agent can do the same via the `ntro_workflow_run` MCP tool.

## A typical first deploy

<Steps>
  <Step title="Test locally">
    `ntro workflow test ./runbooks/nav-monthly --child ... --child ...` — confirm `HAPPY` and `REJECT_ALL` both pass.
  </Step>

  <Step title="Deploy + bind">
    `ntro workflow create --path ./runbooks/nav-monthly/ --tenant <staging-tenant> --entity <test-entity> --schedule "0 8 5 * *" --pin`. Note the workflow id returned.
  </Step>

  <Step title="Trigger a smoke run">
    `ntro workflow run nav-monthly --tenant <staging-tenant> --entity <test-entity> --period 2026-03 --wait`. The `--wait` flag polls until the run completes.
  </Step>

  <Step title="Promote to production tenants">
    Run the same `ntro workflow create --path` against each production tenant + entity. The same runbook bundle backs all of them; each gets its own workflow binding.
  </Step>
</Steps>

## What's deferred

Two pieces of the Notion plan's "Deploy & Run" section are not in this version of the docs:

* **Observer & diagnostics** — the in-flight monitoring and exception handling that watches running workflows for anomalies. The system exists; the docs are still being written.
* **Private infrastructure** — guidance on deploying Ntropii Tenant on your own AKS / Vercel / etc. for data sovereignty.

Both join the docs when their underlying systems harden enough to be customer-documented.

## Related

<CardGroup cols={2}>
  <Card title="Testing locally" icon="flask" href="/deploy-and-run/testing-locally">
    Catch regressions before they ship.
  </Card>

  <Card title="Build runbooks" icon="code" href="/workflows/runbooks/overview">
    Concept walkthrough for authoring a runbook.
  </Card>

  <Card title="Register agents" icon="server-cog" href="/workflows/agents/register">
    Bring an external agent (Claude Managed, Copilot) into a runbook step.
  </Card>

  <Card title="Run inspection" icon="magnifying-glass" href="/tooling/ntro-cli#ntro-run-inspect-executions">
    `ntro run status` and friends — track what's running and what's pending.
  </Card>
</CardGroup>