flowstate

Flowstate

Write a workflow once, rehearse and test it on your machine, then run the same workflow durably on Temporal, governed by identity, policy, and secrets.

Flowstate is a typed, durable, debuggable workflow language and engine, for work that has to finish correctly despite crashes, network failures, and waits of hours or days. Business processes with people in the loop; long-lived entities that many callers address; agents that act under policy; provisioning that must be undone when a later step fails; data pipelines; incident runbooks; releases that roll out in stages. You describe the workload in a Flowfile, YAML for structure and CEL expressions for data and conditions. Flowstate validates it, compiles it into a typed Protobuf specification, and runs that specification either in-process for rehearsal or on Temporal, where every step is recorded and a run survives any process stopping.

Authors get a fast local loop: validation with line and column, tests on a virtual clock, a step debugger, and editor and agent integration. Operators get authenticated callers and approvers, policy over what workflows may reach and read, worker-side secret resolution, tenant isolation, and an audit trail.

Flowstate works alongside CI, services, and your existing Temporal usage rather than replacing them. Why Flowstate, and when not compares it with the alternatives, including the workloads it does not fit.

[!WARNING] Flowstate is early software. The capabilities described here are shipped and tested, but the interfaces are not yet stable: expect breaking changes, and see SUPPORT.md.

A Flowfile

A customer asks for a refund. This workflow totals the lines of the request and checks the total against a limit that belongs to the workflow rather than to whoever starts it, then tells the customer what happened. A payout, and a person in finance who must approve the large ones, are the next step; see examples/refund-request.

edition: v2026.4
name: refund-triage
inputs:
  order_id:
    type: string
    required: true
  lines:
    type: list(int)
    default: [1500, 4200]
vars:
  auto_limit_cents: 5000
steps:
  - id: total
    value: ${inputs.lines.sum()}
  - id: needs_review
    value: ${steps.total.value > vars.auto_limit_cents}
  - id: tell
    log:
      message: refund of ${steps.total.value} cents on ${inputs.order_id} (needs review ${steps.needs_review.value})
outputs:
  needs_review:
    value: ${steps.needs_review.value}
  total_cents:
    value: ${steps.total.value}

$ flow validate workflow.yaml
workflow.yaml: ok
$ flow run local workflow.yaml --input order_id=o-1 -o json | jq -c .runOutputs
{"needs_review":true,"total_cents":5700}

inputs.lines is the run's typed argument, a list of integers with a default. total and needs_review are step ids; reading ${steps.total.value} is how needs_review gets the total, and also what orders it after total. The outputs are the run's result. Every complete Flowfile in this README and the core guides is compiled and linted by the test suite.

edition: v2026.4
name: hello-world
steps:
  - id: hello
    log:
      message: hello world

$ flow test examples/approval-gate/

From file to durable run

flowchart LR
  subgraph author["1 · Author"]
    File["<b>Flowfile</b><br/>YAML + CEL"]
    Check["validate · compile · test"]
  end

  Spec["<b>Workflow protobuf</b><br/>typed and frozen"]

  subgraph execute["2 · Execute"]
    Local["local driver<br/>in process"]
    API["ConnectRPC API"]
    Temporal[("<b>Temporal</b><br/>durable history")]
    Worker["Flowstate worker"]
  end

  Registry["task registry<br/>built-ins + plugins"]
  Policy["identity · policy · secrets"]

  File --> Check --> Spec
  Spec --> Local
  Spec --> API
  API <--> Temporal
  Temporal <--> Worker
  Registry --> Local
  Registry --> Worker
  Policy -.-> |constrains| API
  Policy -.-> |constrains| Worker

  classDef authoring fill:#DDF4FF,stroke:#0969DA,color:#1F2328
  classDef contract fill:#FFF1C2,stroke:#9A6700,stroke-width:3px,color:#1F2328
  classDef runtime fill:#DAFBE1,stroke:#1A7F37,color:#1F2328
  classDef durable fill:#FBEFFF,stroke:#8250DF,color:#1F2328
  classDef govern fill:#FFEBE9,stroke:#CF222E,color:#1F2328
  classDef neutral fill:#F6F8FA,stroke:#57606A,color:#1F2328
  class File,Check authoring
  class Spec contract
  class Local,API,Worker runtime
  class Temporal durable
  class Policy govern
  class Registry neutral

The Flowfile is how you write a workflow; the compiled flowstate.v1.Workflow is what runs. The local driver and the Temporal driver execute that one specification through the same step executor, and a shared conformance suite holds them to the same results. Temporal adds durable history, recovery, timers, signals, and Continue-As-New. The API server starts and observes runs through Temporal, and workers execute them. How Flowstate works explains each piece.

Quickstart

Install the CLI (Go 1.27 or newer):

$ go install github.com/picatz/flowstate/cmd/flow@latest

Scaffold a workflow with its test, check it, and run it locally:

$ flow init my-workflow
$ flow validate my-workflow/workflow.yaml
my-workflow/workflow.yaml: ok
$ flow test my-workflow
PASS  my-workflow/workflow.test.yaml: the greeting uses the input it was given
$ flow run local my-workflow/workflow.yaml
running locally
INFO hello, world
COMPLETED workflow my-workflow

Run it durably. flow server dev starts a Temporal development server, the Flowstate API server, and a worker from one command on loopback; the first launch downloads the Temporal CLI. In another terminal:

$ flow server dev

$ flow run my-workflow/workflow.yaml

flow run always means the server and never falls back to running locally. Follow and act on runs with flow watch, flow get, flow timeline, flow signal, flow cancel, and flow list.

Get started takes this further in twenty minutes: a refund-approval workflow, its tests, the debugger, and a durable run that survives a restart while it waits for an approval.

What you can build today

Fetching plugins from a registry, hosted plugins, consuming MCP servers as capabilities, chat-based approvals, and a general LLM task are directions, not shipped features. Vision records them.

Integrate it

• API. Every server operation is an RPC on flowstate.v1.WorkflowService, defined in proto/flowstate/v1/service.proto. Call it as JSON over HTTP with curl, with the generated Go client, or with a client you generate for another language. See the API guide.
• Plugins. A worker launches plugin executables you name and learns their typed tasks from them; validation, completion, and generated docs read the same schema. A plugin is trusted code, not a sandbox.
• Go embedding. pkg/flowstate/embed compiles Flowfiles, registers Go functions as tasks, and runs workflows in-process or on a Temporal worker your program owns.
• Agents. flow mcp gives an MCP client the language guide, the task catalog, validation, tests, a scripted debugger, local rehearsal, and the control plane. See Using Flowstate from an agent and the generated MCP tool reference.

Find your way

Development

Contributors start with CONTRIBUTING.md; coding agents start with AGENTS.md. Both apply the same gate:

$ go run ./tools/gate   # checks reachable from the current diff
$ make check            # full CI-parity suite

Read the architecture invariants before changing the engine.

License

MIT