Distributed Gleam Simple Example

# Context

We approached Gleam looking for a modern, friendly way of writing concurrent and distributed systems for the Erlang runtime.

As of April 2025, I found no example of how to communicate two BEAM instances using Gleam that is both simple and up to date. Please let me know if overlooked something.

The goal of this repository is to reflect my attempt at it and allow others to give feedback.

I had no prior experience with Gleam or Erlang.

# What I tried to achieve

• Two processes living in different BEAMs interchanging messages.
• Just connect, send and receive messages.
  • In bare-metal Gleam with no libraries.
• Messages must be of the same types one would use between two internal processes.
• All logic must be inside Gleam: no external parameters to erl.
  • Reason: not exposing users to such details.

# Remarks

• The connection can be stablished with net_kernel:start/1 which can elegantly be externalized directly, but is deprecated in favor of /2.
  • net_kernel:start/2 required an Erlang wrapper to convert Erlang Maps into Gleam Records, which took me a lot of time to get "right" (if I may presume).
• I had to systemctl start epmd.service.
  • I would like to learn how not to depend on it maybe this.
• Gleam process.Subject can't be used from other instances (as far as I know).
  • Processes can only send messages to named processes of the other instance.
  • The receiving process will receive a dynamic.Dynamic value that has to be "manually" decoded. This took me a lot of time to get "right".
    • Gleam Records will arrive as a Tuple of an Atom (with the constructor's name) and the values of the fields.
      • I ignore if this imposes any limitation.
      • I had to implement a new_primitive_decoder for atom.Atom.

# How to use the repo

• Install gleam and erlang.
• systemctl start epmd.service.
• Open two terminals and run one on each:
  • $ gleam run -- --ego=mike --illum=joe
  • $ gleam run -- --ego=joe --illum=mike

Exit with double CTRL+C.

# References

• erlang net_kernel docs
• gleam-distribution-demo
• Learn OTP with Gleam
• Gleam coming from Erlang
• gleam/erlang docs
• Gleam's Discord: people are very helpful (specially Gleam's author).
• gleam/dynamic/decode docs