Installation

Install beryl packages from GitHub. They are not on Hex. Add them as Git dependencies in gleam.toml:

[dependencies]
beryl = { git = "https://github.com/tylerbutler/beryl.git", ref = "v0.5", path = "packages/beryl" }
beryl_mist = { git = "https://github.com/tylerbutler/beryl.git", ref = "v0.5", path = "packages/beryl_mist" }

Download the dependencies:

gleam deps download

gleam add installs only Hex packages. Add these entries by hand.

beryl includes the core runtime and the recommended beryl/channel API. beryl_mist provides the Mist WebSocket transport. For Ewe, use path = "packages/beryl_ewe". Use the same git and ref values for all packages. The WebSocket transport guide shows setup for both servers.

beryl supports only the Erlang (BEAM) target. It does not support the JavaScript target.

Packages

A typical application needs beryl and one WebSocket transport.

Package	Add it when
`beryl`	Always — the runtime, raw dispatch API, `beryl/channel`, wire codec, presence, PubSub, and groups
`beryl_mist`	You serve HTTP with Mist
`beryl_ewe`	You serve HTTP with Ewe

Import beryl/channel for the recommended channel model, or beryl/socket for raw dispatch. See Choose an API for the tradeoff.

Requirements

Gleam >= 1.18.0
Erlang/OTP >= 26 (recommended: 27+)
Target: Erlang only

Why Gleam 1.18?

beryl is a monorepo. Its packages are in the packages/beryl, packages/beryl_mist, and packages/beryl_ewe subdirectories. Git dependencies use the path field to select a subdirectory. Gleam added this field in version 1.18. Older versions can select only the repository root and cannot install beryl.

This requirement applies to the Gleam version that installs beryl. The packages declare gleam = ">= 1.13.0" and can compile with older toolchains. You need Gleam 1.18 only to use the dependency entries above.

On an older Gleam, gleam deps download fails while parsing your gleam.toml rather than reporting a version problem:

error: File IO failure

An error occurred while trying to parse this file:

    gleam.toml

  |
7 | beryl = { git = "...", ref = "...", path = "packages/beryl" }
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
data did not match any variant of untagged enum Requirement

If you see data did not match any variant of untagged enum Requirement, upgrade Gleam.

Pin a Git ref

The install example uses the highest published minor-series tag (vMAJOR.MINOR) at the time of the website build. Use this tag to stay on one API series rather than follow main. Check repository tags before you move to a newer minor release.

Minor-series tags can move to newer patch releases. For an immutable pin, use the commit SHA that the tag points to. These docs follow main and can describe features that are not in a release yet.

Gleam resolves Git dependencies at the specified ref. Use the same ref for beryl and its transport package. Do not mix versions.

Packages installed with beryl

beryl brings in these Gleam packages automatically:

Package	Purpose
`gleam_stdlib`	Standard library
`gleam_erlang`	Erlang interop
`gleam_otp`	OTP actors
`gleam_json`	JSON encoding/decoding
`gleam_crypto`	Socket ID generation
`lattice_presence`	CRDT-backed presence tracking
`palabres`	Structured logging