Install the tools¶

ankka is used through three things: libraries your service depends on, the ankka command-line tool, and a platform to deploy to. This page installs the first two. The third has its own page, Install a local platform, and you need it only once you want to deploy.

The CLI is installed with Homebrew, or unpacked from a release; the Scala libraries and the Java and Kotlin SDKs come from Maven Central, the Python SDK from PyPI, the TypeScript SDK from npm, the Go module from its own repository through the Go module proxy and the Rust crate from crates.io. One piece is not yet packaged: the sidecar image that hosts a Python, TypeScript or Go service is built from the repository, and this page says where that applies.

Prerequisites¶

Tool	Needed for	Version
JDK	Scala, Java and Kotlin services, the CLI (Homebrew installs its own), building the platform's images	21
sbt	Scala services, and `ankka init` for one	any recent 1.x
Docker	running Postgres locally, integration tests, building images	any recent
uv and Python	Python services	Python 3.12
Node.js	TypeScript services	22.22 or later; 24 recommended
Go	Go services	1.26 or later
rustup and the `wasm32-unknown-unknown` target	Rust services	stable Rust, edition 2024
kind and `kubectl`	a local platform to deploy to	recent
just	optional shortcuts in the repository	any

Docker is required even for a service you never deploy, because the integration test kits start a throwaway Postgres in a container. No model API key is needed for anything on this page.

Install the CLI¶

On macOS, and on Linux with Homebrew, the CLI comes from ankka's tap. The formula installs a native executable that needs no JVM, so nothing else is needed:

brew install thinkmorestupidless/tap/ankka
ankka version

brew upgrade ankka moves to a newer release. ankka init needs sbt on the PATH for a Scala service, because it runs sbt new to expand the Scala template; a service in any other language, and every other command, works without it. A Java project carries the Maven wrapper and a Kotlin project the Gradle wrapper, so neither needs a build tool installed.

Anywhere else, releases from version 0.7.0 carry the CLI as a single native executable for each platform, with no JVM to install: linux-x64, linux-arm64, macos-arm64 and macos-x64, each on the GitHub release beside a .sha256 checksum. The Linux builds need glibc 2.35 or later, so they do not run on Alpine.

ankka_version=0.16.1                                  # a release from the releases page
platform=linux-x64                                   # or linux-arm64, macos-arm64, macos-x64
base="https://github.com/thinkmorestupidless/ankka/releases/download/v$ankka_version"
curl -LO "$base/ankka-cli-$ankka_version-$platform.tar.gz" -LO "$base/ankka-cli-$ankka_version-$platform.tar.gz.sha256"
shasum -a 256 --check "ankka-cli-$ankka_version-$platform.tar.gz.sha256"
tar -xzf "ankka-cli-$ankka_version-$platform.tar.gz" # one file, ankka: put it on your PATH
./ankka version

The macOS executables are not signed by Apple. curl downloads them without the quarantine attribute and they run as they are; one downloaded through a browser is refused by Gatekeeper until the attribute is removed with xattr -d com.apple.quarantine ankka.

Every release also carries the CLI as a zip that runs on a JDK 21 on the PATH or in JAVA_HOME, for a platform with no native build: unpack it and put its bin directory on your PATH.

ankka_version=0.16.1                                  # a release from the releases page
curl -LO "https://github.com/thinkmorestupidless/ankka/releases/download/v$ankka_version/ankka-cli-$ankka_version.zip"
unzip "ankka-cli-$ankka_version.zip"
export PATH="$PWD/ankka-cli-$ankka_version/bin:$PATH"
ankka version

Get the repository¶

The Python, TypeScript and Go SDKs and the local platform are built from the ankka repository, and so is a CLI newer than the last release:

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

To run the CLI from a checkout rather than a release, sbt cli/stage builds it into cli/target/universal/stage/bin/ankka; that CLI reports a snapshot version, and ankka init writes that version into the projects it creates, which is what the sbt publishLocal below is for.

Make the Scala libraries available¶

A Scala service depends on six libraries, published under the organization com.thinkmorestupidless:

Artifact	What it holds
`ankka-core`	effects, identifiers, codecs, component descriptors
`ankka-sdk`	the component API: entities, workflows, views, consumers, timers, the component client
`ankka-runtime`	the runtime that interprets effects: sharding, persistence, projections, timers
`ankka-http`	HTTP endpoints and the server
`ankka-agent`	agents: model providers, session memory, tools, the agent loop
`ankka-testkit`	unit and integration test support

Released versions are on Maven Central, and a project created from the template resolves them from there; with a released CLI there is nothing to do. A CLI built from the repository reports a snapshot version, and ankka init writes that version into the new project, so publish the libraries from the same checkout for the project to resolve them:

sbt publishLocal                                     # the six, and the control plane's wire library, into ~/.ivy2/local

Run it again whenever you pull a newer version of the repository and want your projects to use it.

Make the Java and Kotlin SDKs available¶

The Java SDK is three artifacts under com.thinkmorestupidless, built on the Scala libraries above: ankka-java (the SDK), ankka-java-testkit and ankka-java-agent. The Kotlin SDK is three more over them: ankka-kotlin, ankka-kotlin-testkit and ankka-kotlin-agent. All six are on Maven Central at every release, with the platform's version, and a project made by ankka init --language java or --language kotlin names that version in its pom.xml or gradle.properties. A Java or Kotlin service runs in the runtime's own JVM, so it needs no sidecar image.

To use a Java SDK that is not released yet, publish it from a checkout into the local Maven repository, ~/.m2, with the Scala libraries it is built on; the Kotlin SDK is a Gradle build in sdks/kotlin, whose README says how to build it against that publication:

sbt publishM2                                        # the Scala libraries and the Java SDK, into ~/.m2

Install the Python SDK¶

The Python SDK is the package ankka on PyPI, published at every release with the platform's version. Add it to your own project, pinned to the version of the platform you deploy to:

uv add "ankka==0.16.1"

The testkit extra (uv add "ankka[testkit]==0.16.1") brings the dependencies of the integration testkit, which starts Postgres and the sidecar in containers. To use an SDK that is not released yet, install it from a checkout of the repository instead: generate its protocol stubs with uv run python scripts/proto.py in sdks/python, then uv add --editable /path/to/ankka/sdks/python.

A Python service also needs the ankka sidecar image, which runs beside your process and hosts everything stateful. It is public on GitHub Container Registry, tagged with the platform's version:

docker pull ghcr.io/thinkmorestupidless/ankka-sidecar:0.16.1

SDKs from version 0.7.0 start that image in the integration testkit by default, at their own version, and pull it on first use; a project made by ankka init does the same in its docker-compose.yml. Earlier SDKs start ankka-sidecar:latest unless ANKKA_SIDECAR_IMAGE names the published one. An SDK installed from a checkout of the repository is version 0.0.0 and starts ankka-sidecar:latest, built from the same checkout with sbt sidecar/Docker/publishLocal.

Install the TypeScript SDK¶

The TypeScript SDK is the package ankka on npm, published at every release with the platform's version. Add it to your own project, pinned to the version of the platform you deploy to:

npm install ankka@0.16.1
npm install -D testcontainers @testcontainers/postgresql      # only for the integration testkit

Node.js 22.22 or later runs a TypeScript service from source, with no build step. To use an SDK that is not released yet, build it from a checkout of the repository instead: npm ci && npm run proto && npm run build in sdks/typescript, then npm install /path/to/ankka/sdks/typescript. A TypeScript service needs the same ankka-sidecar image as a Python one, chosen the same way.

Install the Go SDK¶

The Go SDK is the module github.com/thinkmorestupidless/ankka-go, published at every release with the platform's version and fetched through the Go module proxy. Add it to your own module, pinned to the version of the platform you deploy to:

go get github.com/thinkmorestupidless/ankka-go@v0.16.1

The test kits are the package github.com/thinkmorestupidless/ankka-go/testkit in the same module, so there is nothing more to add; its integration kit starts Postgres and the sidecar in containers, and its tests are skipped unless ANKKA_SLOW=1 is set. Go 1.26 or later builds a service with the standard toolchain and no code generation, to one static executable with CGO_ENABLED=0. To use an SDK that is not released yet, point your module at a checkout of the repository instead: go mod edit -replace github.com/thinkmorestupidless/ankka-go=/path/to/ankka/sdks/go. A Go service needs the same ankka-sidecar image as a Python one, chosen the same way: ANKKA_SIDECAR_IMAGE when it is set, else the published image at the module's version, and ankka-sidecar:latest for a replaced module, which is version 0.0.0.

Install the Rust crate¶

The Rust SDK is the crate ankka on crates.io, published at every release with the platform's version. A Rust service is built to a WebAssembly module, so add the target once, then the crate to your own project, pinned to the version of the platform you deploy to:

rustup target add wasm32-unknown-unknown
cargo add ankka@0.16.1 serde --features serde/derive
cargo add --dev ankka@0.16.1 --features testkit                 # the integration testkit, which needs Docker

The runtime that loads a module is the same ankka-sidecar image a Python, TypeScript or Go service runs beside, chosen the same way: the crate's integration testkit takes ANKKA_SIDECAR_IMAGE, else the published image at the crate's version. To use a crate that is not released yet, depend on it by path from a checkout of the repository, ankka = { path = "/path/to/ankka/sdks/rust/ankka" }; it is version 0.0.0 and starts ankka-sidecar:latest, built from the same checkout with sbt sidecar/Docker/publishLocal.

What you have now¶

ankka on your PATH, for creating services, running the local console and operating a platform.
The Scala libraries resolvable by sbt, the Java or Kotlin SDK resolvable by Maven or Gradle, or the Python, TypeScript or Go SDK or the Rust crate in your project.
For Python, TypeScript, Go or Rust, the ankka-sidecar image, pulled from ghcr.io/thinkmorestupidless/ankka-sidecar.

Continue with your first service in Scala, your first service in Java, your first service in Kotlin, your first service in Python, your first service in TypeScript, your first service in Go or your first service in Rust.