Building / Installation

You may skip this section if you’re using Docker 🐳.

Pre-compiled static executable

All Ogmios releases comes with downloadable pre-compiled static executables for Linux (amd64 & arm64). If you like living on the edge and wants to access a not-yet-released executable, see the continuous integration workflow on Github. Build artifacts are indeed continuously produced though this automated workflow. Find them at the bottom of any workflow run:

Building manually

Pre-requisites (Server)

Ogmios is built using the great Haskell build tool cabal. You’ll also need git to clone the source code, that is:

  • git 2.11.*
  • cabal 3.6.*.* and higher
  • ghc 9.6.3

We recommend using GHCup to install cabal & the Haskell platform.

Ogmios is using library directly from the ouroboros-network, cardano-ledger and cardano-node projects. This is handy for re-using existing logic, but comes at the cost of several system dependencies that are required for building everything. Some may already be installed on your system, but the complete list is:

  • libffi-dev
  • libgmp-dev 6.1.*
  • libnuma-dev
  • libpcre3-dev 2.8.* (for Mac OS, see below)
  • libssl-dev 1.1.*
  • libsystemd-dev
  • llvm 1.11.*
  • llvm-11-dev
  • pkg-config 0.29.*
  • zlib1g-dev 1.2.*
  • libsodium-dev 1.0.* with VRF support (see below)
  • secp256k1 (see below)
  • blst (see below)

libsodium with VRF support

A special patched version of libsodium to include VRF support. Note that, while this is necessary to run a validator node; it is not necessary for a simple application node serving data to your client. So here, it suffices to install libsodium-dev 1.0.*, and to add/create the following to your cabal.project.local (to be placed next to the current cabal.project:

package cardano-crypto-praos
  flags: -external-libsodium-vrf


A custom revision of bitcoin-core’s secp256k1, with Schnorr signature support enabled:

  • autoconf 2.*
  • libtool 2.*.*
git clone
cd secp256k1
git reset --hard ac83be33d0956faf6b7f61a60ab524ef7d6a473a
./configure --prefix=/usr --enable-module-schnorrsig --enable-experimental
make check
sudo make install


A fancy crypto library for BLS12-381, a.k.a BLST:

git clone
cd blst
git checkout v0.3.10
cat > libblst.pc << EOF

Name: libblst
Description: Multilingual BLS12-381 signature library
Version: 0.3.10
Cflags: -I\${includedir}
Libs: -L\${libdir} -lblst
sudo cp libblst.pc /usr/local/lib/pkgconfig/
sudo cp bindings/blst_aux.h bindings/blst.h bindings/blst.hpp  /usr/local/include/
sudo cp libblst.a /usr/local/lib
sudo chmod u=rw,go=r /usr/local/{lib/{libblst.a,pkgconfig/libblst.pc},include/{blst.{h,hpp},blst_aux.h}}

pcre (MacOS)

On MacOS only, you might need to specify extra lib & include directories for pcre depending on your installation. For example, if you used Homebrew with defaults, add the followings to your cabal.project.local:

package pcre-light
  extra-include-dirs: /opt/homebrew/opt/pcre/include
  extra-lib-dirs: /opt/homebrew/opt/pcre/lib

🔨 Server

Clone the git repository from Github:

$ git clone --depth 1 --recursive --shallow-submodules
$ cd cardano-ogmios/server

Then, use cabal to compile the project source code from the server directory:

$ cabal update
$ cabal build ogmios:exe:ogmios

The first time, this may take a while as cabal needs to setup a compilation environment and to download a lot of dependencies. Subsequent executions are much faster.

From there, you can run Ogmios via cabal using the run command:

$ cabal run ogmios:exe:ogmios -- --help

Alternatively, you can instrument cabal to copy the compiled executable elsewhere so that you can run Ogmios all by itself:

$ cabal install ogmios:exe:ogmios --install-method=copy --overwrite-policy=always
$ ogmios --help

🔨 TypeScript Client

Clone the git repository from Github:

$ git clone --depth 1 --recursive --shallow-submodules
$ cd cardano-ogmios/clients/TypeScript

Then, use Yarn to install dependencies and compile the project source code from the client/TypeScript directory:

$ yarn && yarn build

📚 Documentation

The documentation is built using Hugo. You’ll need an -extended version of hugo with version >= 0.96.0. Then, simply run:


# or, alternatively for a development setup on http://localhost:1313

hugo serve

in the ./docs folder.

In addition, the TypeScript API reference can be generated using yarn docs from within the client/TypeScript folder. This will automatically create and copy files in the right folder for hugo to pick up.


You may skip this section if you’re not interested in contributing to Ogmios.

🔧 Unit Tests

First, make sure to pull and update git submodules:

$ git submodule update --init

Then, simply use cabal as follows:

$ cabal test all

💨 End-to-end Tests

  • A synchronized node running on the preview network.
  • Ogmios running and listening on :1337.
Running the tests

From the project root, run:

$ cd clients/TypeScript
$ yarn
$ yarn test