GoAkt Examples

Examples for GoAkt v4. For the v3.14 examples, see the v3 branch.

Getting Started

git clone https://github.com/Tochemey/goakt-examples
cd goakt-examples

To build all examples, install Earthly and run:

earthly +all

Examples

Core Concepts

• goakt-hello-world: a minimal actor system. Spawns an actor, sends it messages, and shuts down gracefully.
• goakt-ping-pong: two actors exchanging messages using the Tell pattern.
• goakt-behaviors: an actor that moves between states (authenticated, logged in) using behaviors.
• goakt-parent-child: spawning child actors from inside an actor and observing Terminated events.
• goakt-supervision: the Stop, Resume, and Restart supervision directives, each with retry limits.
• goakt-routers: actor pools with round-robin, fan-out, and consistent-hash routing, including resizing a pool at runtime.
• goakt-pubsub: topic-based publish/subscribe using WithPubSub() and the system TopicActor.
• goakt-scheduler: scheduling messages with ScheduleOnce, recurring schedules, and cancellation by reference.
• goakt-dead-letters: subscribing to the system event stream to observe unhandled messages.

Remoting and Location Transparency

• goakt-remoting: Ping and Pong actors running in separate processes and communicating over the network.
• goakt-cluster/dynalloc: location transparency in a cluster. Actors can live on any node and the cluster routes messages to them.

Clustering and Discovery

• goakt-cluster/static: a cluster whose nodes are configured with fixed peer addresses.
• goakt-cluster/dnssd: nodes that discover each other through DNS-SD/mDNS, using protobuf messages.
• goakt-cluster/dnssd-v2: the same as dnssd but with plain Go structs instead of protobuf, plus PostgreSQL persistence.
• goakt-cluster/k8s: a cluster on Kubernetes that uses the Kubernetes API to discover pods, with a gRPC API and protobuf messages.
• goakt-cluster/k8s-v2: a Kubernetes cluster with plain Go types, an HTTP/JSON API, PostgreSQL persistence, and OpenTelemetry tracing.
• goakt-cluster/k8s-ebpf: k8s-v2 with actor-level tracing collected by a goakt-ebpf sidecar, without instrumenting the application code.
• goakt-cluster/multi-dc: two datacenters (us-east-1 and eu-west-1) with a NATS JetStream control plane, NATS discovery, and cross-datacenter actor placement via SpawnOn and WithDataCenter.
• goakt-cluster/multi-dc-isolated: the same as multi-dc but with two separate Kind clusters on a shared Docker network, to simulate real network boundaries between datacenters.

Persistence and Extensions

• goakt-persistence: the persistence extension. Snapshots actor state to a pluggable store, with an in-memory store as the example implementation.

Grains (Virtual Actors)

• goakt-grains: the grains model. Virtual actors with automatic activation and passivation.
• goakt-iot-twin: device twins as grains. Each device activates on demand, passivates when idle, and restores its state on reactivation.
• goakt-grains-cluster/grains-dnssd: grains spread across multiple nodes with DNS-SD discovery.

Reactive Streams

• goakt-stream: backpressure-aware pipelines built from Sources, Flows, and Sinks, with fan-out and fan-in topologies, parallel processing, and actor integration.

Applications

• goakt-chat: a multi-room chat application with remoting, room-based messaging, and message history, using protobuf messages.
• goakt-chat-v2: the same chat application using plain Go structs instead of protobuf.
• goakt-saga: a money transfer service that uses the saga pattern with compensating transactions. Runs on Kubernetes/Kind and uses plain Go types.
• goakt-2pc: the same money transfer service implemented with two-phase commit instead of a saga. Runs on Kubernetes/Kind and uses plain Go types.
• goakt-ai: a distributed multi-agent system with Orchestrator, Research, Summarizer, and Tool agents. Supports OpenAI, Anthropic, Google, and Mistral models, and ships with a CLI and a load balancer. Runs on Kubernetes/Kind.
• goakt-tetris: a browser-playable Tetris game where each match is an actor tied to a WebSocket connection. Covers a scheduled-tick game loop, Watch/Terminated lifecycle cleanup, a SpawnSingleton matchmaker, cluster-aware placement with SpawnOn, and CBOR serializers, with a TypeScript canvas client and a two-node docker compose setup.
• goakt-pictograph: a browser-playable multiplayer drawing and guessing game in the style of Skribbl.io. Each room is a RoomActor with a Become-driven state machine (waiting, choosing, drawing, round over, game over), Stash for early guesses, a pub/sub topic per room for stroke and chat fan-out (spectators included), a PlayerProfileGrain for cross-session stats, and a cluster-wide CRDT PNCounter leaderboard. Uses the same two-node docker compose setup as goakt-tetris.
• goakt-scrabble: browser-playable multiplayer Scrabble for 2 to 4 players, humans or bots, in English. Each room is a RoomActor with a turn-based Become state machine (waiting, playing, game over) around a pure-Go Scrabble engine (DAWG dictionary, premium-square scoring, Appel/Jacobson move generation). Each bot seat is a child BotActor that uses ScheduleOnce to simulate thinking time. Shared per-language dictionaries live in system Extensions, and a CRDT PNCounter tracks a per-player, per-language leaderboard. The client is a vanilla TypeScript SVG board.
• skybound-runner: a browser-playable co-op platformer for up to 4 players, in its own repository. A GameActor per match runs an authoritative 60 Hz physics simulation, a MatchFactory singleton matches players into games with SpawnOn and least-load placement, and a PlayerSessionActor bridges each WebSocket connection to its game. Uses CBOR serializers for remoting and a TypeScript canvas client.