From your agent
to a running workflow.

Run your first workflow

Create a development workspace with your invitation code and passkey. Save the recovery codes somewhere private. Install the package in an empty project, then authorize the CLI in your browser.

npm install https://runfabric.dev/downloads/runfabric-0.2.0.tgz
npx runfabric auth login
npx runfabric doctor

The hosted HTTP example fetches a public JSON record. It installs an explicit integration, publishes an immutable workflow version, starts a run and observes the result. Authorize admin to install the connection, write to publish, and read and run to operate it.

RUNFABRIC_EXAMPLES=./node_modules/@coralbeat/workflows/examples

npx runfabric integration create \
  --file "$RUNFABRIC_EXAMPLES/quickstart-http-profile.json"
npx runfabric validate "$RUNFABRIC_EXAMPLES/quickstart-http-workflow.json"
npx runfabric workflow create \
  --file "$RUNFABRIC_EXAMPLES/quickstart-http-workflow.json"

# Use the revision returned by create (1 for this new workflow).
npx runfabric workflow publish quickstart-http --revision 1
printf '%s\n' '{"id":1}' | npx runfabric run start quickstart-http \
  --input - --idempotency-key quickstart-http-1

# Replace RUN_ID with the id returned by run start.
npx runfabric run watch RUN_ID
npx runfabric run journal RUN_ID

Use a new idempotency key for a new run. Reuse the original key when retrying the same request after losing a response. The packaged README includes a script that captures revision and run IDs automatically.

Connect your agent

Use an OAuth-capable remote MCP client with this endpoint:

https://dev.runfabric.dev/mcp

The client discovers the authorization server, opens a project consent screen and receives a scoped token. The exact MCP resource is the URL above. API tokens use https://dev.runfabric.dev/v1; they are deliberately distinct audiences.

For a client that launches local MCP servers, first complete CLI login, then configure:

{
  "mcpServers": {
    "runfabric": {
      "command": "npx",
      "args": [
        "runfabric-mcp"
      ]
    }
  }
}

The stdio adapter uses your private CLI profile. It exposes the same tools for workflow drafts, validation, publishing, runs, approvals, integration profiles, schedules, webhooks and project keys. Machine-readable schemas come from runfabric schema; operating instructions come from runfabric skills.

To design a process, describe its outcome, available inputs, allowed integrations, review points and failure policy. Have the agent inspect existing definitions and connections, draft the graph, validate it and explain its paths before publishing. You can inspect and edit the same graph in the operations workspace.

The workflow model

A workflow has a mutable draft and numbered, immutable published versions. A run pins one published version, its input and an idempotency key. Editing a draft or publishing a newer version does not change an existing run.

The outer graph is acyclic. Loops are explicit nested structures with limits; screen position never controls execution order. JSON expressions reference values such as input.id and steps.fetch. Arbitrary JavaScript is not evaluated in the engine.

Get the current schema and bounds with npx runfabric schema. The validator is authoritative; the graph editor and your agent use the same workflow definition.

Connect the systems you use

An integration profile belongs to a project and has a stable activity kind, configuration and optional write-only credentials. The workflow supplies input. The profile selects the destination and authentication.

Use the integration screen or JSON through the CLI. Reads show configuration and whether credentials exist; they do not return secret values. Tests make a real call using the supplied input.

npx runfabric integration list
npx runfabric integration create --file profile.json
npx runfabric integration test PROFILE_ID --input input.json

HTTP path templates can use values such as /customers/{id}. Secret headers reference a credential name, for example {"header":"Authorization","secret":"apiKey","prefix":"Bearer "}. A workflow cannot choose an arbitrary destination or substitute another profile’s secrets.

The reusable integration runtime is exported from @coralbeat/workflows/integrations. Local process support is a separate /integrations/local import. Extend the system with a new profile or an activity handler; providers do not require new graph node types.

Put an agent inside a workflow

An agent step can iterate through model responses and call explicitly allowed HTTP or MCP tool profiles. It uses the customer’s model broker and credentials. Each tool resolves its own profile’s credentials; the broker does not receive the tool’s secret.

This example uses an OpenAI-compatible broker. Replace the model, key and tool profile ID with values from your project, then save the file privately and install it through the CLI.

{
  "name": "Research assistant",
  "activityKind": "research.assist",
  "kind": "agent",
  "config": {
    "baseUrl": "https://openrouter.ai/api/v1",
    "allowedOrigins": [
      "https://openrouter.ai"
    ],
    "model": "YOUR_BROKER_MODEL_ID",
    "credentialSecret": "broker_api_key",
    "systemPrompt": "Research the request using only the allowed tools. Cite the tool results.",
    "toolProfileIds": [
      "YOUR_HTTP_OR_MCP_PROFILE_ID"
    ],
    "maxTurns": 4,
    "maxToolCalls": 3,
    "maxCompletionTokens": 512,
    "timeoutMs": 60000,
    "maxOutputBytes": 65536
  },
  "credentials": {
    "broker_api_key": "YOUR_PROVIDER_KEY"
  },
  "enabled": true
}

Call research.assist from an activity node with input such as {"prompt":"Research this company…"}. The loop is bounded by turns, tool calls, completion tokens, elapsed time and output size. A tool request outside the allowlist is rejected.

Run history records the activity outcome; the activity journal records model and tool phases with secrets redacted. Provider costs remain with your broker account. Runfabric supplies no model credit in this release.

Start work on a schedule or event

A trigger binds to an exact workflow ID and published version. Change that binding deliberately after publishing an update.

Schedules

{
  "name": "Weekday briefing",
  "workflowId": "morning-briefing",
  "workflowVersion": 1,
  "cron": "0 9 * * 1-5",
  "timezone": "Europe/London",
  "input": {
    "team": "operations"
  },
  "enabled": true
}

Schedules accept five-field cron with an IANA timezone, or an interval in seconds. A minute clock records due occurrences and dispatches runs. Long missed backlogs are bounded; this is not a subsecond scheduler. Pause a schedule to stop new occurrences.

Webhooks

{
  "name": "New lead",
  "workflowId": "qualify-lead",
  "workflowVersion": 1,
  "verification": "hmac",
  "enabled": true
}

Create with runfabric webhook create --file webhook.json and save the returned secret. Send JSON to /v1/hooks/WEBHOOK_ID with a unique x-runfabric-delivery-id. For HMAC, send x-runfabric-signature: sha256=HEX_DIGEST, where the digest is HMAC-SHA256 over the exact request bytes using the secret. Shared-secret mode uses x-runfabric-secret.

Repeating the same delivery ID and body reuses its durable record. Reusing the ID with different content returns a conflict. Delivery acceptance is asynchronous; inspect delivery history for the resulting run ID and failure information.

npx runfabric schedule occurrences SCHEDULE_ID
npx runfabric schedule pause SCHEDULE_ID
npx runfabric webhook deliveries WEBHOOK_ID
npx runfabric webhook rotate WEBHOOK_ID

Inspect, approve and recover

The web workspace shows the executable graph, published versions, current runs, parked approvals and individual step outcomes. Your agent can inspect the same information through the CLI or MCP.

npx runfabric workflow list
npx runfabric run list
npx runfabric run inspect RUN_ID
npx runfabric run journal RUN_ID
npx runfabric run cancel RUN_ID --reason "Superseded by a new request"

Activities use a lease and attempt fence. A late worker cannot complete a newer attempt. Read and explicitly idempotent activities can follow bounded retry policy; an uncertain external write is recorded as unknown and requires reconciliation with external evidence. A lost response is never proof that a remote effect did not happen.

Approvals require approve or admin. Hosted decisions are attributed to the authenticated principal or key. Cancellation stops future dispatch and signals active handlers where possible; it cannot undo a completed external action.

Exhausted hosted dispatch failures have a project-scoped error record. Inspect GET /v1/dispatch-errors and request a retry with POST /v1/dispatch-errors/ID/retry using work or admin. A retry re-enrolls durable project work; it does not invent a successful activity result.

Compose Runfabric with the SDK

Sentient and other applications can compose the same product API without embedding the engine or calling providers from their UI. The branded client defaults to the dev API; the portable WorkflowClient requires an explicit base URL.

import { RunfabricClient } from "@coralbeat/workflows/runfabric";

const client = new RunfabricClient({
  baseUrl: "https://dev.runfabric.dev",
  apiKey: process.env.RUNFABRIC_API_KEY,
});
const run = await client.startRun({
  workflowId: "quickstart-http",
  version: 1,
  input: { id: 1 },
  idempotencyKey: crypto.randomUUID(),
});
for await (const state of client.watchRun(run.id)) {
  console.log(state.state.status);
}

Methods cover definitions, versions, runs, project keys, integrations, schedules, webhooks and journals. Requests have bounded timeouts and response sizes and accept cancellation signals. For a first-party browser, use RunfabricBrowserClient with a project ID and the product session cookie.

Keep Project Keys on your server when composing another product. A Runfabric project is its own tenant boundary; it does not silently create or replace a Human or Organization in Sentient.

Access and credentials

Humans sign in with a passkey and receive an HttpOnly secure session. Recovery codes restore access if the passkey is lost; save them outside this browser. Interactive agents use Authorization Code with PKCE, explicit project consent and rotating refresh credentials.

Create scoped keys for unattended CI or local workers. Worker keys can restrict allowed activity kinds. Keys are shown once; expiration and revocation are checked on use. Browser sessions are separate from machine keys.

OAuth grant revocation, project-key revocation and sign out are available from Agent access. Provider credentials are stored encrypted in the control plane and excluded from workflow definitions and public profile reads. See the security and architecture guide for the trust boundaries.

Run on infrastructure you control

The portable engine is a Node.js 24 HTTP service with PostgreSQL 16 persistence. It accepts DATABASE_URL; migrations are explicit and ordered. Engine, SDK, validation, worker and integration source are included in the Apache-2.0 package.

The hosted development product additionally uses Cloudflare for static delivery, product identity, encrypted integration configuration, webhook/schedule dispatch and hosted workers. Its origin runs in the dedicated GCP development environment. Self-hosting the engine alone does not supply the hosted login or control plane.

A user-owned worker can run HTTP, MCP or local CLI profiles. Install reviewed executable paths and argument arrays, supply secrets through a private file, and start:

npx runfabric work start --profiles ./profiles.json --secrets ./secrets.json
# One polling pass for a short-lived worker:
npx runfabric work start --profiles ./profiles.json --once

Local workers use fixed configured commands with shell execution disabled. They claim only matching activity kinds and heartbeat while running. See the package README and examples in the download for local engine setup.

Command and artifact reference

npx runfabric --help shows exact arguments. JSON files or stdin carry structured inputs. All interfaces use the product’s shared contract rather than separate CLI semantics.

• Installable package v0.2.0
• Full package README and quickstart
• Agent skill
• Origin HTTP OpenAPI reference
• Example workflow and HTTP profile
• Apache-2.0 license and notice
• Agent-readable entry points

What this development release covers

This release provides a working durable graph engine, product login, CLI/MCP/SDK access, configured integrations, bounded agent steps, webhooks, schedules and a visual operations workspace.

It does not claim full n8n feature parity. There is no n8n workflow import, arbitrary hosted code node, marketplace of prebuilt vendor connectors, billing, production SLA, any/quorum parallel join, unbounded recursion or version-pinned child workflow runs. Connect compatible systems through HTTP/MCP or a worker you control.

Development signup is invitation-gated and capacity-limited. Runtime expansion, execution time and output sizes are bounded. Long history is retained in durable storage; no automatic retention deletion policy is advertised. Read live capabilities before depending on a limit.