Building a chat app with Actyx Pond
In this tutorial, we are going to build a small chat app on top of the Actyx Platform. You might be tempted to skip it because you are not building chats in real-life — give it a chance. The techniques that you will learn in this tutorial are fundamental to building any app on the platform, and mastering them will give you a good understanding of its capabilities.
Before we start
The tutorial is divided into three sections:
- The first section, Setup for the tutorial, will explain how to set up your ActyxOS nodes and give you a starting point to follow the tutorial
- The Overview section will teach you the fundamentals of Actyx: nodes, events, and fishes
- The last section, Building the chat, will teach you the most common techniques in Actyx development
You don’t have to complete all of the sections at once to get value out of this tutorial. Try to get as far as you can — even if it’s just one or two sections.
In order to get the most out of this tutorial, it is helpful if you have basic knowledge of HTML, CSS, and TypeScript. But since this is a fairly simple app you should be able to follow along even if you are coming from a different programming language.
Typescript in 5 minutes
If you haven't worked in TypeScript before, we can recommend this guide to brush up on the basics.
The best way to experience this tutorial is using multiple devices. In addition to your PC, you will need a second device running Android.
mDNS and Client Isolation
If you have disabled mDNS in your network, you will have to ensure your devices can initially connect to the internet. If you have enabled Client Isolation, this tutorial will not work.
Setup for the tutorial
Now, let's get right to it. In this section we will turn your devices into ActyxOS nodes, configure the nodes, and set up the basic directory structure for the app we will build.
Setup your local device
ActyxOS currently runs natively on Windows and Linux. To install ActyxOS on one of these operating systems, please download the respective installer from our downloads and install ActyxOS as you would with any other application. You can also find detailled installation guides for Windows and Linux.
If you are working on a Mac, you can use ActyxOS on Docker. If you don't have Docker installed on your Mac already, you can install it from here. ActyxOS on Docker is publicly available on Docker Hub. To download and run the latest version please execute the following command from your terminal.
Since Docker does not support peer discovery via mDNS, you need to configure your Docker node with a bootstrap node. To do that, please paste the following command into your terminal.
If you get stuck or want to learn more about ActyxOS on Docker check out this guide.
Setup an Android device
ActyxOS on Android is publicly available from the Google Play Store. Just open the Google Play store on your Android device, search for ActyxOS and install it. To start ActyxOS, just open the app like any other.
If you get stuck or want to learn more about ActyxOS on Android check out this guide
Setup a web app project
In order to be able to run, test and build the chat app you are going to need Node.js and npm, which you can install from here.
We are now going to setup a simple web app project using Parcel. Somewhere on your computer create a directory called
In that directory create a file called
package.json and add the following content:
Create another file called
tsconfig.json with the following content:
Now create a file called
index.html and add the following:
Finally, create a file named
index.ts with the following content:
To test that everything works, open a terminal, navigate to the
chat directory and run
npm install and then
npm run start. This is what you should see in your terminal.
If you now navigate to http://localhost:1234 in your browser and open the Developer Tools you should see this:
Help, I’m stuck!
Now that you’re set up, let’s get an overview of the Actyx platform!
What is ActyxOS?
ActyxOS is a multi-node operating system that allows you to build local-first applications running in a swarm of nodes (devices). Specifically you can:
- Run one ore more apps on each node using the ActyxOS runtimes
- Access always-available
localhostAPIs such as the Event Service
- Count on automatic dissemination and persistence of data in the swarm
ActyxOS enables a completely decentral architecture that allows you to build apps that always run. Your apps always run because they run locally (on the edge) and only interact with
localhost APIs. Currently ActyxOS offers two APIs:
- The Event Service API at
http://localhost:4454/api/v1/eventsallows you to publish and receive events in the swarm of nodes
- The Console Service API at
http://localhost:4457/api/v1/logsallows you to generate logs for monitoring and debugging
What is Actyx Pond?
Actyx Pond is an application framework for building apps that run on ActyxOS. It is currently available for the TypeScript programming language. Support for further languages, including C#/.NET is planned. Here is how to works:
- You implement the business logic of your application by writing so-called fishes and run those in ActyxOS apps
- Actyx Pond then automatically synchronizes the state of all fishes throughout the swarm of nodes
What is interesting about Actyx Pond is that it allows you to forget completely about how to synchronize state between nodes in the swarm. This happens, for example, when one of the nodes goes offline for a while. As soon as it comes back up, Actyx Pond automatically reconciles what happened between all the nodes while they were disconnected from each other.
Eventual consistency for a partition tolerant system
Formally speaking, Actyx Pond provides eventual consistency for logic implemented on the partition tolerant ActyxOS. You can learn more about the theoretical concepts underlying ActyxOS and Actyx Pond here.
Building the chat
Let's now have a look at how to use ActyxOS and Actyx Pond to build our decentralized chat app.
To implement and run our chat app we need to do three things:
Install ActyxOS on each node (or device).Already done!
- Implement our chat logic as a fish
- Package and run our chat app
Our chat has a very simple logic. Any participant can send messages and receives messages sent by all other participants. When a participant joins the chat, he should also receive all past messages that were sent when he wasn't part of the chat.
The way to implement this using Actyx Pond is to write a so-called fish. A fish is a state-machine. It has a state which it updates when it receives information from other fishes.
Let's start by defining types for the chat fish's state and the events it can receive. Events it receives from other chat fishes are strings (chat messages). The state of the fish will then be an array of strings. In the
index.ts file, add the following two lines of code:
When a fish first starts up, it won't have received any chat messages yet. So let's define the initial state as an empty array:
Now comes the actual logic of our chat, namely how to calculate the chat state (which we will show to the user), from the events we have received. We do this by writing a so-called
onEvent function. In this case, we will simply add the chat messages (
ChatEvent) we have received to our state (
This is the complete chat logic. Let's now turn this into a fish.
The chat fish
In Actyx Pond you implement a fish by creating an object with a couple of properties. You must provide the fish with an ID, an initial state, the
onEvent function and information about where to get the chat messages from, a so-called event stream tag.
First, add the following imports to the top of the
Now that we have done that, we create the tag for our chat messages and then define the fish itself:
The user interface
Lastly, we need to build a user interface and hook up our fish. Let's implement a very simple user interface showing the chat messages, an input field to type a message and a button to send the message.
Open up the
index.html file and adjust the contents of the
body sections as follows:
The last thing we have to do is to hook up the user interface to the fish. We want to
- Show all chat messages, i.e. fish's state in the
- Send out a chat message event when the user clicks the Send button
index.ts file, add the following code:
To test that everything works navigate to the
chat directory, run
npm run start and open http://localhost:1234. You should now see the chat app. If you started ActyxOS on Docker on your local machine, you should now also be able to send messages. However, you still don't have anyone to chat with.
Package and run the app
In order to run the chat app on your Android device, you need to package and deploy it.
To tell ActyxOS about the app, add an app manifest file called
ax-manifest.yml to the
chat directory. Add the following contents:
Before packaging the app, run
npm run build to create a distribution version of the web app (which will be placed in the
dist directory). If everything works you should see something like this:
Now use the ActyxOS Node Manager to package and deploy the app (use the path to the
If you open ActyxOS on the Android device, you should now see the chat app. You can click and open the app and should now be able to chat back and forth with your local machine!
And just like that we have built a multi-node application that would traditionally have required a web server and a shared database or pub-sub broker 🎉
Here is what you can try out now:
- Do the chat messages get shared between nodes?
- Do I see history if I restart the app?
- What happens if I chat or restart in airplane mode?
- How are messages sorted after I reconnect a device?
We hope that you are now starting to experience the power of local-first applications and the Actyx Platform. If you are keen to dive a bit deeper, check out the following further resources.
Download the code
You can download the complete code for this tutorial from GitHub.
- Learn more about ActyxOS
- Learn more about Actyx Pond
- Or check out these additional libraries and tools:
Join our Discord chat
Feel free to join our Actyx Developer Chat on Discord. We would love to hear about what you want to build on the Actyx platform.