Flowstate

Flowstate is a durable, policy-governed workload engine. You write a workload in YAML with CEL expressions. It compiles to a typed protobuf specification, frozen at that boundary, and runs on Temporal's durable execution engine through one of two drivers that must agree on everything observable: rehearse in-process while you write it, then hand the same file to a worker and it survives crashes, redeploys, and waits that outlast the process that started them.

It is not a CI system. CI is one workload shape among many. The engine targets anything that has to finish correctly despite crashes, network failures, and long waits: data pipelines, provisioning and orchestration, operational runbooks, agentic pipelines with approval gates, and scheduled maintenance work.

A deploy that waits for a human to approve it, however long that takes. Nothing holds a thread open for the wait, because the wait is state on Temporal rather than a worker. This is a compact variant of examples/approval-gate, which carries the fully annotated version:

edition: v2026.2
name: approval-gate
description: Wait for a human to approve a deploy, then act on what they decided.

inputs:
  version:
    type: string
    required: true
    example: v1.4.2
    must: this.matches(r'^v?[0-9]+\.[0-9]+\.[0-9]+$')
  environment:
    type: string
    required: true
    example: production
    must: 'this in ["staging", "production"]'
  expected_approver:
    type: string
    required: true
    example: sre-lead@example.com

# Who may deliver `deploy-approved`. The server checks the sender's attested
# identity against this before the workflow ever sees the signal: a team the
# author named, narrowed per run to one approver, who must not be the person
# who started the run.
signals:
  deploy-approved:
    allow:
      - subject: ${"https://issuer.example.com#" + inputs.expected_approver}
        claims:
          team: release-managers
    distinct_from_starter: true

steps:
  - id: request
    log:
      message: ${"requesting approval to deploy %s to %s".format([inputs.version, inputs.environment])}

  # The gate. It resolves to one of three outcomes, named once, on the step
  # that produced the data. Three and not two, because a payload carrying no
  # decision at all is neither an approval nor a rejection.
  - id: approval
    wait_for_signal:
      name: deploy-approved
      timeout: 24h
      outputs:
        outcome: >-
          ${has(payload.approved)
            ? (payload.approved ? "deployed" : "rejected")
            : "expired"}
        sender: ${sender}

  - id: deploy
    if: ${steps.approval.outcome == "deployed"}
    log:
      message: ${"deploying, approved by %s".format([steps.approval.sender.identity.subject])}

  - id: rejected
    if: ${steps.approval.outcome == "rejected"}
    log:
      message: ${"%s declined the deploy".format([steps.approval.sender.identity.subject])}

  - id: expired
    if: ${steps.approval.outcome == "expired"}
    log:
      message: nobody decided in time

Two things carry the weight here. First, authorization lives in signals:, not in the steps: FlowstateServer.Signal refuses a signal from an unattested, wrongly claimed, or mismatched sender before Temporal ever sees it, so the workflow's own logic is left with the one question that belongs to it (did the approver say yes). Second, steps.approval.sender is not something the approver typed into a payload. It is who the server authenticated the signal as, and no caller can set it. A payload is evidence; a sender is identity.

One honest caveat before you copy this into production: whoever can edit the Flowfile can also widen or delete its signals: block. Binding that requires deployment-side policy the file's author does not control, tracked in #187.

Rehearse it in this process, with no Temporal and no server. flow test runs the example's own test file with stubbed signals and a virtual clock (the 24h timeout lapses in well under a second), and it checks each scripted signal's sender: through the same function the server calls:

$ flow test examples/approval-gate/
PASS  examples/approval-gate/workflow.test.yaml: a sender satisfying signals: deploys
PASS  examples/approval-gate/workflow.test.yaml: an approved payload from a sender signals: refuses never reaches the gate
PASS  examples/approval-gate/workflow.test.yaml: an approved payload is still refused without an attested sender
PASS  examples/approval-gate/workflow.test.yaml: an explicit rejection is honored
PASS  examples/approval-gate/workflow.test.yaml: nobody answers, and the gate lapses at its own timeout
PASS  examples/approval-gate/workflow.test.yaml: a version that is not semver is refused before the first step runs
PASS  examples/approval-gate/workflow.test.yaml: an environment outside the known set is refused before the first step runs
PASS  examples/approval-gate/workflow.test.yaml: a signal carrying no decision is not a rejection

Bad arguments are refused before the first step runs, on the must: rules the inputs declare:

$ flow run local examples/approval-gate/workflow.yaml \
    --input version=latest --input environment=production \
    --input expected_approver=sre-lead@example.com
ERROR
input "version" must satisfy `this.matches(r'^v?[0-9]+\.[0-9]+\.[0-9]+$')`; got
latest
arguments are given with --input name=value or --input-file inputs.json

Hand the same file to a server backed by Temporal (Quickstart below), and approve it from another terminal with flow signal <id> deploy-approved --data '{"approved": true}'. One note if you try that against the Quickstart's dev setup: --insecure-no-auth makes every caller the same anonymous principal, and this gate pins a specific approver who must not be the starter, so it will refuse you (which is the gate working). Rehearse it with flow test above, or run the server with --auth-policy and two real identities (docs/DEPLOYMENT.md). A worker restart while it waits changes nothing, because nothing local was holding the wait. Both drivers render a finished run through one renderer, so a local rehearsal and a durable run answer with the same final document.

That contrast is the whole pitch: write once, rehearse locally, run durably. See docs/ARCHITECTURE.md for the layer model and the invariants the implementation holds to, and docs/VISION.md for where this is going. Putting it somewhere real, especially somewhere multiple tenants share? Read docs/DEPLOYMENT.md first.

flowchart LR
  Flowfile["Flowfile (YAML + CEL)"] -->|"flow validate, flow compile"| Spec[["Workflow (frozen protobuf)"]]
  Spec --> Local["flow run local (in-process)"]
  Spec --> Worker["flow worker"]
  Worker <--> Temporal[("Temporal")]
  Local --> Answer(("one GetResponse"))
  Temporal --> Answer

  classDef ir stroke-width:2px;
  class Spec ir;

An author writes a Flowfile. flow validate and flow compile turn it into a Workflow protobuf: the durable artifact, and the only thing either driver executes. Nothing about a run's behavior is decided from the YAML again. flow run local interprets that spec in-process; flow worker interprets the identical spec as Temporal activities and durable timers. Both answer through the same document, which is what makes a local rehearsal worth trusting.

Checking a file never runs it. Steps have side effects, so executing a file to find a typo means causing part of it. flow validate reports the position, what is wrong, and what to do about it:

$ flow validate broken.yaml
broken.yaml:5:5: step "web": unknown task "htpp"; available tasks are http, log
broken.yaml:9:16: step "out" input "message": references step "later", which runs later; steps can only reference steps defined before them

flow run and flow run local apply the same checks before executing anything, so a mistake is reported rather than partially performed. flow fix migrates a file whose spelling has been retired, and flow compile shows what a correct file becomes. Both are in the Reference below.

• Writing workflows by hand? flow init scaffolds a workflow and its test; Quickstart below runs both without a server. Then docs/DSL.md for the language and examples/ for working files to pattern-match against.
• An agent using Flowstate? flow mcp serves the same surface over stdio: validate, compile, run locally, run durably, all without a Go compiler in the loop. See flow mcp: the same surface, for an agent.

Nothing in this first part needs a server, a worker, or Temporal. Scaffold a workflow and its test, run it, and run the test:

$ go run ./cmd/flow init my-pipeline
+ created my-pipeline/workflow.yaml
+ created my-pipeline/workflow.test.yaml

NEXT
  flow run local my-pipeline/workflow.yaml
  flow test my-pipeline

$ go run ./cmd/flow run local my-pipeline/workflow.yaml
INFO hello, world
COMPLETED workflow my-pipeline
{"stepValues":{"greet":{"namedValues":{}}}, "runOutputs":null}

$ go run ./cmd/flow test my-pipeline
PASS  my-pipeline/workflow.test.yaml: the greeting uses the input it was given

That is the whole of the local loop, and it is worth rehearsing with: the two drivers are one execution model, so conditions, retries, timeouts, loops and waits behave here the way they behave in production.

What the local loop cannot give you is durability. A local run is a process, with no run id, nothing watching it, and no survival past the command being interrupted. For that, start a local Temporal development server, a Flowstate worker, and the Flowstate API server, each in its own terminal:

$ temporal server start-dev
$ go run ./cmd/flow worker --allow-unversioned-interpreter
$ go run ./cmd/flow server --insecure-no-auth

Both flags are for a dev setup that outlives nothing. A production worker passes --deployment-name and --build-id instead, so a deploy does not change the interpreter behind a run already in flight (see Deployment portability), and a production server passes --auth-policy with a trust policy instead of allowing anonymous callers.

Then run a workflow durably, through the server:

$ go run ./cmd/flow run ./examples/hello-world-multi-step/workflow.yaml
started flowstate-workflow-01b09563-6f8a-4ab1-a1d0-67896e7b8da2; come back to it with `flow watch flowstate-workflow-01b09563-6f8a-4ab1-a1d0-67896e7b8da2`
COMPLETED workflow flowstate-workflow-01b09563-6f8a-4ab1-a1d0-67896e7b8da2 run 019fe297-35dc-743c-b8c0-2a3c65e64f8a after greet, shout
{"stepValues":{"greet":{"namedValues":{}}, "shout":{"namedValues":{}}}, "runOutputs":null}

The same file run with flow run local prints the same steps and the same final document; the difference is that this one survives its worker being restarted.

go install ./cmd/flow puts flow on your PATH (at $(go env GOPATH)/bin/flow) once you'd rather not type go run every time. Everything above also has a --help, and docs/reference/cli.md is every command and flag, generated from the binary's own command tree.

Each step names a task directly: the task's own name is the key, its inputs the value beneath it. log has no outputs, deliberately. A log line is an effect on a reader, not a value for a later step; to carry a value, name it with vars: instead.

Names only: types, defaults and which are required belong to the schema, and repeating them here is how the two disagree. flow tasks prints the full catalog; flow tasks --output json carries the same catalog as one document, for a script or an agent. docs/reference/tasks.md is the generated, complete version of both tables.

A plugin's tasks are not in this table, or in flow validate's registry. See Plugins for why, and flow plugins --plugin-dir <dir> to ask a worker what it would load.

flow is the command line interface: write a Flowfile, check it, then either run it on your own machine or hand it to a server that runs it durably through Temporal. Every command below takes --help for its full flags, and docs/reference/cli.md is the same table generated from the binary's own command tree, with which environment variable feeds each flag's default.

run, get, watch, list, signal, cancel and terminate talk to a server and take --address (or FLOWSTATE_ADDRESS); run local contacts nothing.

docs/reference/envvars.md is the generated, complete table: every variable the code reads, held to the tree by a test that fails on a read this list does not carry. The essentials:

With no configuration at all, Flowstate connects to a local development server: self-hosted is the default, and Temporal Cloud is opt-in configuration rather than a prerequisite. A credential is never sent over plain HTTP to anywhere but this machine. flow refuses rather than warns, unless an operator sets FLOWSTATE_INSECURE_PLAINTEXT_TOKEN=true to say that something else (a sidecar, a service mesh) is terminating TLS in front of it.