Quickstart

This page runs a flow that needs no API key, then adds a model. It uses the published npm packages. To run from a clone instead, see installation.

Prerequisites

Node.js 22 or later, with npm or pnpm.

Run a flow

Create the config file

In an empty directory, create milford.config.yaml. It lists the flows to load and the token that callers must send.

milford.config.yaml

flows:
  - { file: ./flows/hello.json }
server:
  port: 8080
  auth: { tokens: ["${MILFORD_TOKEN}"] }

Create a flow

A flow is a graph of nodes. This one takes a name and returns a greeting.

flows/hello.json

{
  "id": "hello",
  "nodes": [
    { "id": "in", "type": "input" },
    { "id": "greet", "type": "prompt", "config": { "template": "Hello {{input.name}}!" } },
    { "id": "out", "type": "output" }
  ],
  "edges": [{ "from": "in", "to": "greet" }, { "from": "greet", "to": "out" }]
}

Start the server

MILFORD_TOKEN=change-me npx @milfordai/server milford.config.yaml

MILFORD_TOKEN=change-me pnpm dlx @milfordai/server milford.config.yaml

The server loads and checks every flow before it listens, and prints the number of flows it loaded.

Run the flow

curl -s localhost:8080/v1/flows/hello/run \
  -H "authorization: Bearer change-me" \
  -d '{"input": {"name": "Ann"}}'

The response holds the result of every node and the flow output, here "Hello Ann!".

Add a model

A decision node asks a provider a typed question and returns a value your graph can branch on. Add a provider to milford.config.yaml:

providers:
  - { id: main-llm, type: anthropic, apiKey: "${ANTHROPIC_API_KEY}", model: claude-sonnet-5 }

Then add a decision node to a flow. A low-confidence answer becomes none_of_these:

{ "id": "team", "type": "decision", "config": {
    "provider": "main-llm", "kind": "choice",
    "prompt": "Which team should handle this message?",
    "options": ["billing", "technical", "sales"],
    "state": "{{input.text}}", "minConfidence": 0.6 } }

Edges with a when condition route on the answer. See decisions and flows. Switching the provider to an OpenAI-compatible server or a local classifier is a config change.

Use the library instead

npm install @milfordai/core @milfordai/providers

pnpm add @milfordai/core @milfordai/providers

import { createEngine, defaultRegistry, flow } from "@milfordai/core";
import { registerProviders } from "@milfordai/providers";

const engine = createEngine({
  registry: registerProviders(defaultRegistry()),
  providers: [{ id: "main", type: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-sonnet-5" }],
  flows: [
    flow("summarize")
      .node("sum", "llm", { provider: "main", preset: "summarize", prompt: "{{input.text}}" })
      .node("out", "output")
      .edge("sum", "out")
      .build(),
  ],
});
if (!engine.ok) throw new Error(engine.error);

const result = await engine.value.run("summarize", { text: "..." });

createEngine and run return results instead of throwing. Check ok before you read value.

Next steps

Flows

How the executor walks a graph.

Providers

OpenAI-compatible, Anthropic, Jev and your own classifier.

MCP

Expose flows as tools to LLM clients.

Deployment

Docker, limits and offline use.

Get started

Concepts

Building blocks

Guides

Reference

API reference

Prerequisites

Run a flow

Add a model

Use the library instead

Next steps

Flows

Providers

MCP

Deployment

​Prerequisites

​Run a flow

​Add a model

​Use the library instead

​Next steps

Flows

Providers

MCP

Deployment

Prerequisites

Run a flow

Add a model

Use the library instead

Next steps