gleam_otp: typed actors and supervisors for Gleam on the BEAM

It is bindings, not a new framework

The most important clarification is in the readme, and it changes how you should evaluate the package. This package is not a distinct OTP-inspired framework, and the regular Erlang OTP APIs can be used with and alongside it without trouble. That is a stronger claim than it first appears, because a package that reimplements a runtime's semantics on top of it inevitably diverges. This one does not, so a Gleam program using it is running on the real BEAM with the real OTP underneath, and you can drop down to the Erlang APIs for anything the package does not cover. The package description calls itself opinionated bindings to many of the core concepts of OTP, giving type safe APIs over the same semantics, and the goals it lists are full type safety of actors and messages, compatibility with Erlang's OTP actor framework, fault tolerance and self-healing through supervisors, and equivalent performance to Erlang's OTP. The last of those is a target rather than a measurement, and nothing in the readme quantifies it, so treat it as a design goal that a real workload would need to confirm.

Adding it, and a first actor in twenty lines

It is a Hex package, added with the Gleam package manager:

gleam add gleam_otp@1

The example in the readme is the clearest statement of the API shape, and it is a complete program rather than a fragment:

import gleam/erlang/process.{type Subject}
import gleam/otp/actor

pub fn main() {
  // Start an actor
  let assert Ok(actor) =
    actor.new(0)
    |> actor.on_message(handle_message)
    |> actor.start

  // Send some messages to the actor
  actor.send(actor.data, Add(5))
  actor.send(actor.data, Add(3))

  // Send a message and get a reply
  assert actor.call(actor.data, waiting: 10, sending: Get) == 8
}

pub fn handle_message(state: Int, message: Message) -> actor.Next(Int, Message) {
  case message {
    Add(i) -> {
      let state = state + i
      actor.continue(state)
    }
    Get(reply) -> {
      actor.send(reply, state)
      actor.continue(state)
    }
  }
}

pub type Message {
  Add(Int)
  Get(Subject(Int))
}

Several design choices are visible. The actor is built with a pipeline of new, then on_message to attach the handler, then start, and the result is pattern matched with a let assert on an Ok, which tells you the start is fallible. The message type is declared with a custom type carrying a payload, and the reply variant carries a subject rather than a value, so the caller can send an answer back. The call function takes a named waiting timeout alongside the message to send, and the timeout is a real value the type system checks. And the handler returns an actor.Next value rather than a bare state, so the choice between continuing, stopping or replying is encoded in the return type.

Read the OTP documentation first, because the package assumes it

The readme has a section on learning OTP and the advice is blunt about it. This package has limited documentation for OTP itself, so attempting to use it without first studying the framework itself is likely to result in some confusion and sub-optimal code. That is an unusual thing for a library to say about itself, and it is worth taking at face value rather than reading it as a disclaimer. The library documents its own abstractions and functionality, but the readme tells you that you likely should read the documentation or other material on Erlang OTP to get a fuller understanding of OTP, the problems it solves and the motivations for its design. In practice that means the package is a layer of typed syntax over a framework you are expected to already understand, and reading it in the other order is how people end up with actors that restart on the wrong conditions. The repository layout is correspondingly small, with a src directory for the package source, a test directory, a gleam.toml and a manifest.toml for the Hex package definition, a changelog, a licence file and a GitHub directory for the workflows.

Three kinds of actor, and which one you want

The library offers three abstractions, and the readme is helpful about which to reach for. The process is the lowest level building block of OTP, and all other actors are built on top of processes either directly or indirectly, but the readme notes that this abstraction would typically not be used very often in Gleam applications, favouring the other actor types that provide more functionality. The process type comes from Gleam's own process module in the gleam_erlang library rather than from this package, which is a sensible division. The actor is the most commonly used process type in Gleam and serves as a good building block for other abstractions, and like Erlang's gen_server it handles OTP's system messages automatically, which is what enables OTP's debugging and tracing functionality to work without you doing anything. The supervisor is the fault tolerance layer. Supervisors are processes that start and then supervise other processes, and they can restart them if they crash and terminate them when the application is shutting down. Supervisors can start other supervisors, which produces a hierarchical process structure called a supervision tree, and the package ships two variants with their own documentation pages, a static supervisor and a factory supervisor.

The gaps, stated plainly

The readme does not oversell what is here, and the honest parts are the most useful. Not all Erlang OTP functionality is included, with some of it not possible to represent in a type safe way and therefore not included, and other features still in development, such as further process supervision strategies. The system messages gap is spelled out in its own section. OTP system messages are special messages used by some debugging APIs, actors do not yet support all of them, so some of the more niche of those APIs may not be fully functional, and the readme asks you to open an issue if you need one of the unimplemented messages. That is a reasonable way to handle it, since system messages are mostly of interest to people doing deep runtime introspection. The other structural point is that the package covers a core subset of OTP, enough for the majority of OTP code, and that for anything else you use the Erlang APIs directly or reach for another package that provides bindings to more functionality. The reminder at the end is the one to keep in mind when you are tempted to treat this as a Gleam-specific framework, that OTP is one framework shared between all BEAM languages, with no special Gleam version and no reason to be limited to certain packages or APIs.

Editorial conclusion

gleam_otp is a good fit for a Gleam team that wants Erlang's supervision model and fault tolerance without leaving the language, and for anyone who already knows OTP and wants the same design in a language with static types. It is the wrong choice if you are starting from scratch with actors, because the documentation itself warns that the package has limited documentation of OTP itself and that using it without studying the framework is likely to produce confusion and sub-optimal code. It is also the wrong choice if you need the whole of OTP, since not all of it is included, with some of it not representable in a type safe way and some still in development. It is the wrong choice if you want a Gleam-specific variant of the framework, because the documentation is explicit that OTP is one framework shared between all BEAM languages with no special Gleam version. Before adopting it, read up on Erlang OTP first, and note the gaps: actors do not yet support all OTP system messages, and further process supervision strategies are still in development. The project is Apache-2.0 licensed, the last push was on 2026-10-15, and the current release is v1.3.0 from 2026-08-09.

Frequently asked questions

Official sources

1. gleam-lang/otp on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases