There are many OCaml stacks, this one is mine.
Quick Start | What Riot Is | Command Surface | What You Can Build | Non-goals
Riot is a tech-demo of an opinionated OCaml stack for building applications as one piece: tools, services, databases, packages, experiments, and systems that need to stay understandable while they grow.
It is centered around one tool, riot, plus a modern package registry,
prebuilt OCaml toolchains, a multi-core-ready actor-model runtime, a new
standard library, and first-class support for agentic work.
Install Riot:
curl -sSL https://get.riot.ml | sh
riot --helpStart a workspace:
riot init app
cd app
riot build
riot testRiot is a stack, but it is also a tool: riot. The goal is that this is the
only tool you need inside the stack.
Riot includes:
- a package-aware build system using plain
riot.tomlmanifests - package management through
pkgs.ml, including add, remove, update, search, publish, yank, login, and logout flows - managed OCaml toolchains declared in
ocaml-toolchain.toml, including prebuilt host and cross-target toolchains riot fmt, a strict zero-knobs formatter optimized for readability and stable diffsriot fix, an extensible linting and codemod surface with package-provided rules and automated fixes- one test runner for unit tests, property tests, snapshot tests, and replayed fuzz cases
riot fuzzfor coverage-guided fuzzing campaigns against parsers, codecs, protocol handlers, and CLI boundariesriot snapshotsfor reviewing generated expected-output changesriot benchfor benchmark runs, recording, and comparisonriot docfor local and release package documentationriot runfor local executables, GitHub repositories, URLs, and one-off workflow tools- package provider commands like
riot sqlx:migrate, so dependencies can extend the local workflow without becoming separate global tools .agents/skills/riot-mlin generated projects, plus--jsonoutput across important command paths so agents can inspect and repair workflows as data- an actor-model runtime and standard library surface for building real OCaml applications
Useful links:
- Landing page: https://riot.ml
- Installer: https://get.riot.ml
- Package registry: https://pkgs.ml
- Source repository: https://github.com/leostera/riot
- Agent discovery: https://riot.ml/llms.txt
Riot keeps the normal software-development loop behind one command family:
| Command | Purpose |
|---|---|
.agents/skills/riot-ml |
local agent instructions for Riot projects |
riot build |
build packages and workspaces |
riot fmt |
format OCaml with one house style |
riot fix |
lint, explain rules, and apply safe fixes |
riot test |
run unit, property, snapshot, and replayed fuzz tests |
riot fuzz |
run and replay coverage-guided fuzzing campaigns |
riot snapshots |
approve or reject pending snapshot candidates |
riot bench |
run, record, and compare benchmarks |
riot add, riot rm, riot update |
manage dependencies and riot.lock |
riot publish, riot yank |
publish and manage registry releases |
riot search, riot login, riot logout |
work with pkgs.ml |
riot init, riot new |
create workspaces and packages on the blessed path |
riot toolchain |
install, list, and validate OCaml toolchains |
riot doc |
generate package documentation |
riot run |
run workspace binaries and remote sources |
riot <pkg>:<cmd> |
run package-owned workflow commands |
Most automation-oriented commands either support --json today or are designed
around structured output, so scripts, editors, CI jobs, and agents do not need
to scrape prose.
Riot is intended for:
- multi-core applications using actors, supervision, and message passing
- command line interfaces with clear errors and structured output
- cloud and networked services that do real IO
- developer tooling such as formatters, linters, code generators, release tools, migration scripts, and project automation
- TUI applications with packages like
mintteaandgooey - web applications with
suri, including LiveView-style flows - database-backed systems with
sqlx,postgres, andsqlite - agentic workflows that can be run, inspected, repaired, and repeated
Riot is not a full port of the Erlang VM. It does not try to support Erlang or Elixir bytecode, hot-code reloading in live applications, function-call-level tracing in live applications, or ad-hoc distribution.
Riot is also not trying to preserve compatibility with the traditional OCaml toolchain or experience. This is my own vision of what writing OCaml could look like.
Riot continues work I started with Caramel, an Erlang backend for the OCaml compiler.
If you are looking for the old Riot library that used to be published in opam, you can find it at https://github.com/leostera/riot/commit/310a4868edaa4f97304ca5398f23d843b8b26eae.
