reflow

From prompt to production

Tell your agent what should happen. Reflow handles the rest.

No drag-and-drop builder. No translating product logic into a maze of automation blocks.

Your agent can inspect your existing templates and workflows, build the journey, validate its graph, simulate every branch, and show you exactly what will happen before anything goes live.

Related MCP server: Nitrosend

Quick Start

Prerequisites

• Node.js 22 or newer

• pnpm 11+ and Docker Compose (local server only)

1. Install the CLI

npm install --global @socialrobot-io/reflow
reflow --version

The CLI connects to a Reflow server; it does not install the server.

2. Start the server

git clone https://github.com/socialrobot-io/reflow.git
cd reflow
pnpm install
pnpm dev

pnpm dev starts PostgreSQL and Temporal, applies migrations, and runs the API, worker, dispatcher, and dashboard. Configure either AUTH_RESEND_API_KEY and AUTH_EMAIL_FROM (a sender on a domain verified in that separate authentication Resend account), or the GitHub client credentials in .env.local, then open http://localhost:5173. On a fresh database the page creates the first administrator. Development reads REFLOW_SETUP_SECRET from .env.local or .env; if it is missing or shorter than 32 characters, pnpm dev generates a strong replacement in .env.local. Use that value on the setup page, not an old code.

After registration, the dashboard opens Integrations. The owner can choose Resend, while outbound Webhooks and Push are marked coming soon. The API key, verified sender, and webhook signing secret are managed in Integrations → Resend, not in deployment-wide workflow-delivery variables. Development also generates an integration encryption key in .env.local if needed.

To preview the dashboard with realistic workflow definitions, run pnpm demo:seed --list to see local workspace slugs, then pnpm demo:seed <workspace-slug>. This idempotent, local-only command connects to the development database on 127.0.0.1:5433, replaces the earlier placeholder fixtures, and adds three clearly labeled draft journeys, eight previewable email templates, and fake demo people at in-progress and completed steps. It never starts Temporal or queues email. Pass multiple slugs to seed each organization separately. It does not mark organization onboarding complete or connect Resend. See Local demo journeys for the product assumptions, event contracts, and complete paths.

Registration remains disabled by default. To allow new accounts in development, set ALLOW_REGISTRATION=true in .env.local and restart pnpm dev; the development launcher passes this setting through to the server.

Stop the application with Ctrl+C; stop its Docker services with pnpm dev:infra:down. If startup reports that port 5173 is already in use, another dashboard process is still running; stop that process and rerun pnpm dev. Development uses tsx watch rather than Node's native --watch, which avoids a known Node 24.18+ worker-thread conflict in the Temporal TypeScript SDK.

3. Log in with the CLI

reflow auth login --url http://localhost:3000
reflow call auth.whoami

The CLI completes OAuth Authorization Code with PKCE through the dashboard and stores short-lived access and rotating refresh credentials in a protected local file, never your password or browser cookie.

4. Connect an MCP client

Copy the checked-in examples/mcp/cursor.json to .cursor/mcp.json:

{
  "mcpServers": {
    "reflow": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Do not add a static Authorization header. Reflow publishes OAuth discovery metadata; compatible clients register with PKCE, show the requested scopes, and save their own grant. Operators can revoke the grant from Connected apps. For production, replace the URL with https://your-reflow.example/mcp. Redirect allowlists are described in Authentication.

Usage

Create the first journey with MCP

Give your MCP-capable agent this prompt:

Create an activation welcome journey for new users: welcome them, give them 24 hours to activate, remind them once if they don't, and stop messaging them as soon as they activate.

Hook it up to the app, reuse our existing setup and style, test it, and show me the result before anything goes live.

The agent can inspect, author, validate, and simulate, but must ask before publishing or enrolling a real contact. For the explicit CLI path with template files, graph JSON, publishing, and the 20-second event/timeout test, follow the welcome + nudge tutorial.

Send product events

reflow call event.emit --input '{
  "enrollmentId": "ENROLLMENT_ID",
  "eventId": "product-activation:ACTIVITY_ID",
  "eventType": "product.activated",
  "data": { "plan": "pro" }
}'

Keep eventId stable across retries. Production applications call the same event.emit operation over HTTP with a scoped machine credential, and MCP clients use event_emit. Complete CLI, HTTP, and MCP examples are in Sending product events.

Trigger a journey from product code

import { ReflowSdk } from '@socialrobot-io/reflow-sdk';

const reflow = new ReflowSdk({
  url: process.env.REFLOW_URL,
  workspaceId: process.env.REFLOW_WORKSPACE_ID,
  apiKey: process.env.REFLOW_API_KEY, // user-bound key with the send scope
});

await reflow.trigger({
  workflowVersionId: 'WORKFLOW_VERSION_ID',
  contact: { email: 'user@example.com' },
  idempotencyKey: 'activation-welcome:user@example.com',
});

The SDK upserts the contact and starts an idempotent enrollment. Keep the API key server-side; browser bundles must call your own backend endpoint.

Operate Reflow

reflow workflow show --name "Activation welcome"
reflow call enrollment.list
reflow call message.list

The operations console at http://localhost:5173 shows journey graphs, live enrollments, timelines, messages, OAuth consent, and connected apps.

Architecture

See Architecture for the full design.

Configuration

Server variables, documented in .env.example:

CLI and SDK environments use REFLOW_URL plus REFLOW_TOKEN or REFLOW_API_KEY; the SDK also reads REFLOW_WORKSPACE_ID.

Validation and simulation work without Resend. Before a real enrollment can send email, connect the organization's Resend account in the dashboard and confirm a test send. Domain verification and webhook setup are covered in Resend setup.

API

Every operation is defined once and exposed three ways: HTTP POST /v1/operations/<operation>, an MCP tool with dots converted to underscores, and the generic reflow call CLI command.

MCP also serves reflow://operations, reflow://workflow/schema, and reflow://workflow/actions, plus the design-workflow authoring prompt and the first-party agent skill. The full contract is in Operations and MCP contract.

Project Structure

apps/
├── dashboard/        # React operations console and OAuth UI
└── server/           # Hono API, Better Auth, Temporal workers, Resend adapter
packages/
├── contracts/        # Shared operation and journey schemas
├── cli/              # @socialrobot-io/reflow CLI
├── sdk/              # @socialrobot-io/reflow-sdk for server actions and UI backends
└── mcp-ext-skills/   # MCP skills extension shim
docs/                 # Architecture, authentication, deployment, operations, events guides
examples/             # welcome-nudge tutorial and MCP client configs
migrations/           # PostgreSQL migrations
scripts/              # Dev orchestration, deployment, workflow bundling
skills/               # First-party agent skill
tests/                # Repository validation suite

Tech Stack

Deployment

Before enabling public signups, review the production readiness assessment.

Point a hostname at a Linux server with Docker and ports 80/443 available, then run:

./scripts/deploy.sh reflow.example.com admin@example.com

The script generates deployment secrets, builds the stack, configures Caddy TLS, runs migrations, and performs idempotent admin setup. See Deployment for Coolify, external ingress, backups, and production topology.

CI runs the same make check gate on every push and pull request.

Contributing

Contributions follow the standard fork, branch, commit, pull request workflow. Before opening a PR, run the complete release gate:

make check

It runs repository validation, linting, typechecks, backend and dashboard tests, Temporal replay checks, all builds, Compose validation, and an npm package dry run. Read CONTRIBUTING.md for the full rules, and update the docs and agent skill when behavior changes. The CLI release process is documented in Releasing.

Reflow is early. If you try it, open an issue and tell us where setup hurt, which journey actions you need next, and whether the MCP flow felt natural.

License

Reflow is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).