Skip to content

Install the tools

The flow CLI verifies a blueprint, writes the AnkkaFlow resource a cluster runs, and requests resets. It is one native executable for macOS (Apple silicon and Intel) and Linux (x64 and arm64), with no JVM to install. The sidecar and operator images are published to a registry with every release.

The flow CLI

With Homebrew, on macOS or Linux:

brew install thinkmorestupidless/tap/ankka-flow
flow version

flow version prints the CLI's version and the protocol version it writes, for example flow 0.1.0, protocol 1.0. The tap is the one ankka's CLI ships through, so brew install thinkmorestupidless/tap/ankka installs ankka beside flow; the two coexist, and brew upgrade moves each to its latest release.

From a release archive

Every release attaches one archive per platform, with a checksum beside it:

Platform Archive
macOS, Apple silicon ankka-flow-cli-<version>-macos-arm64.tar.gz
macOS, Intel ankka-flow-cli-<version>-macos-x64.tar.gz
Linux, arm64 ankka-flow-cli-<version>-linux-arm64.tar.gz
Linux, x64 ankka-flow-cli-<version>-linux-x64.tar.gz

Download the archive and its .sha256, verify the checksum, unpack the one file inside, and put it on your PATH:

version=0.1.0
platform=macos-arm64                                         # or macos-x64, linux-arm64, linux-x64
base=https://github.com/thinkmorestupidless/ankka-flow/releases/download/v$version
curl -fsSLO "$base/ankka-flow-cli-$version-$platform.tar.gz"
curl -fsSLO "$base/ankka-flow-cli-$version-$platform.tar.gz.sha256"
shasum -a 256 -c "ankka-flow-cli-$version-$platform.tar.gz.sha256"
tar -xzf "ankka-flow-cli-$version-$platform.tar.gz"          # unpacks one file: flow
install -m 755 flow /usr/local/bin/flow                      # or any directory on your PATH
flow version

A checksum that does not match means the download is not the release's file; download it again rather than run it.

On macOS, Gatekeeper may refuse to run a binary that was downloaded by a browser. Allow it under System Settings → Privacy & Security → Open Anyway, or clear the quarantine mark:

xattr -d com.apple.quarantine flow

A flow downloaded with curl carries no quarantine mark, and neither does Homebrew's.

A platform outside these four builds the CLI from source, which runs on a JVM; Build ankka-flow from source covers it.

The images

Each release publishes the platform's images, and the samples', to ghcr.io/thinkmorestupidless with the release's version as the tag:

Image What it is
ankka-flow-sidecar the container the platform adds beside every streamlet; it owns everything Kafka
ankka-flow-operator the Kubernetes operator that runs AnkkaFlow resources
sample-cart-router-scala the sample Scala streamlet, holding its code, the SDK and a Java runtime
sample-cart-router the sample Python streamlet, holding only its own code and the SDK
docker pull ghcr.io/thinkmorestupidless/ankka-flow-sidecar:0.1.0
docker pull ghcr.io/thinkmorestupidless/ankka-flow-operator:0.1.0
docker pull ghcr.io/thinkmorestupidless/sample-cart-router-scala:0.1.0
docker pull ghcr.io/thinkmorestupidless/sample-cart-router:0.1.0

Install the platform puts the operator and sidecar images on a cluster of your own. The two tutorials that follow work from a clone of the repository and build the images they need with sbt, so they can run the sample's code as you change it; Build ankka-flow from source lists what that takes.

What you need for the tutorials

Tool Used for
Docker the Kafka and sidecar containers of the laptop loop, and building the sample's image
uv, with Python 3.12 or later the Python SDK and sample, and the scripts that send and check the tutorial's events
JDK 21 and sbt the Scala SDK and sample, building the sidecar image for the laptop loop, and the images just up loads into kind
kind and kubectl a local Kubernetes cluster, for deploying a pipeline
just (optional) short names for the commands on the pages; every recipe is one command you can run yourself

Clone the repository and work from its root:

git clone https://github.com/thinkmorestupidless/ankka-flow.git
cd ankka-flow

The Scala SDK

A Scala streamlet project depends on the SDK from Maven Central. It needs Scala 3.3 or later, a JDK 21 or later, and sbt:

libraryDependencies += "com.thinkmorestupidless" %% "ankka-flow-sdk" % "<version>"

The version is the ankka-flow release whose sidecar runs the streamlet. In the repository the SDK is sdks/scala, and the Scala sample builds against it directly. To run the SDK's own checks and the conformance suite against it:

sbt sdk/test sdkConformance

The Python SDK

The SDK is in sdks/python. A streamlet project depends on it by path, so uv sync in the project installs it; nothing needs building first. To run the SDK's own checks:

cd sdks/python && uv sync && uv run python scripts/proto.py && uv run mypy && uv run pytest -q

What to do with them

flow init starts a streamlet project of your own, in Scala or Python, with its test, descriptor, blueprint, image build and laptop setup:

flow init greeter                 # or: flow init greeter -l python
  • Your first streamlet starts from flow init, runs the project on a laptop with Kafka and the sidecar in containers, and then shows the sidecar at work with the sample.
  • Deploy to a local cluster runs the same streamlet on kind with the operator.