Flezha

A durable runtime for streams, workflows and agents.

Flezha 0.1.1 is an early release: interfaces may still change between versions until 1.0.

Code that processes data tends to grow the same scaffolding around it: somewhere to keep state, a way to recover after a crash, retries, a way to spread the work over more machines. Flezha provides that scaffolding, so your code can stay about the data.

You write the logic in Java, Rust, Python, Node, Ruby, PHP, Go or Elixir. Flezha runs it as many small, independent pieces in parallel, on one machine or across several, keeps each piece's state on disk, and when a process or a machine fails, starts the work again elsewhere and carries on from where it stopped.

The same building blocks carry many shapes of data processing:

• Streams and ETL pipelines that read from files, HTTP, WebSockets, Kafka or Postgres, transform with state that survives a crash, and load into Postgres, Kafka or files.
• Workflows and long-running jobs that commit progress at every step, retry a failing step, and undo finished steps when a later one fails.
• Scheduled and timer-based work: batch jobs on a cron schedule, windows, timeouts and reminders kept per key.
• A service per user, device or order, each copy with its own state, from a handful to thousands running side by side.
• AI agents and chat sessions, one per conversation, that remember what was said and survive a crash (see Working with AI).

• The controller coordinates everything: it decides where work runs, keeps its state on disk, and starts it again elsewhere when something fails.
• A runner is your own program, written with one of the Flezha SDKs. It connects to the controller and runs the code you registered.
• A relay is one running copy of that code. A relay is a processing unit that works like a worker: it keeps its own state and carries data through its tasklets. Flezha runs thousands of relays in parallel. Inside a relay, your logic is split into small processing stages, called tasklets, wired into a graph.
• Plugins connect relays to the outside world (files, HTTP, Kafka, Postgres, RabbitMQ and more) without changing their code.

What is Flezha explains the pieces in more detail.

An echo in Python: it takes a line of text and sends it back.

1. Write the logic. A tasklet is one processing stage, run once per message:

import flezha

@flezha.tasklet(name="echo")
class Echo:
    def run(self, value: str, ctx: flezha.Ctx[None, str]) -> None:
        ctx.emit(f"echo: {value}")

2. Wire it into a relay. The relay says where messages come in, which stages they pass through and where results leave:

@flezha.relay("echo")
def echo_relay(c: flezha.ChannelBuilder) -> None:
    c.input("in", codec="text").into(Echo).output("out")

3. Serve it from a runner, a process that connects to the controller:

flezha.create_runner("default").register_factory(echo_relay).run()

4. Start it and send it a message with flz, the command-line tool that comes with the controller:

$ ./bin/flz relay start echo --id my_echo
$ ./bin/flz relay send my_echo --text 'hello world' --await 2000
Delivered to 'my_echo'.
out	echo: hello world

The same echo exists in every SDK, under sdk/<language>/examples/echo.

To start a project of your own, download a small, tested starter in any SDK language from the release page (Starter projects). Up and running builds the echo by hand, and the tutorials then build two larger example applications step by step.

Flezha works with AI from both sides: as a tool AI assistants can drive, and as a runtime for AI services.

• For AI assistants. flz mcp is an MCP server an assistant adds with one command: it gives the assistant the working rules and the current SDK form for its language before any controller runs, and then the controller's operations with a token of its own (docs/public/topics/core/mcp_server.md). A controller on another machine serves the same over HTTP (docs/public/plugins/http_api.md). Your relays are tools too: each described entry channel is one an agent can call (docs/public/topics/core/sending_and_calling.md). Every error carries a stable code and a hint for the next step (docs/public/errors.md), every flz command can answer in JSON, the documentation ships an llms.txt map to its pages in Markdown, and local mode tries a change in seconds.
• For AI services. Each conversation runs as its own session with its own state; answers stream while they are written, a turn can be taken back, and a crash does not end the conversation. Your code calls the model SDK or agent framework you already use. The agentdesk tutorial builds one.

Each one is also a git submodule of this repository, under sdk/<language>.

You need Elixir 1.17 or later and a stable Rust toolchain, plus Node.js for the WebSocket test server.

$ git clone --recurse-submodules https://github.com/flezha/flezha.git
$ cd flezha
$ make build && mix test.setup   # compile everything, build the test server
$ scripts/test.sh                # the controller's tests (mix test)
$ scripts/test-full.sh           # everything CI checks; --list prints each command

Setting up a checkout and running the tests have the details.

Contributions are welcome, and each one needs a signed CLA. Contributing has the rules, and the pages next to it cover setting up a checkout, running the tests and the code standards.

In short: build on the SDKs, the plugins and the examples freely, and copy from them into closed code; if you modify and distribute the controller's files, publish those modifications. Your own files never inherit either license. REUSE.toml holds the per-path map, and CI checks it.

Flezha is provided "AS IS", without warranty of any kind (MPL-2.0 §6-7, Apache-2.0 §7-8). Read Durability before trusting it with data. The licenses grant no trademark rights: a fork, derived work or hosted service must not use the name "Flezha" or one confusingly similar. Third-party components in binary distributions are listed in rel/third_party/THIRD_PARTY_NOTICES.md.