Skip to main content
Once your runbook passes local tests, shipping it is one command: 
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 — coding agents call ntro_workflow_create from the chat.

​
Prerequisites

  • An entity bound to a tenant (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

# 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, the workflow is anchored to the runbook’s slug — the same runbook can back many workflows across tenants and entities.

​
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 for the authoring walkthrough and 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): 
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: 
ntro workflow run nav-monthly \
  --tenant acme-fund \
  --entity acme-spv1 \
  --period 2026-03
workflow run returns a task ID. Use ntro run status 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

1

Test locally

ntro workflow test ./runbooks/nav-monthly --child ... --child ... — confirm HAPPY and REJECT_ALL both pass.
2

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

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

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.

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

Testing locally

Catch regressions before they ship.

Build runbooks

Concept walkthrough for authoring a runbook.

Register agents

Bring an external agent (Claude Managed, Copilot) into a runbook step.

Run inspection

ntro run status and friends — track what’s running and what’s pending.