Riot · OCaml stack - NFHN Reader

Why Riot?

Riot is a tech-demo of a stack and tooling for building applications in OCaml. It is heavily opinionated, and designed from the ground up to get out of your way and help you ship great software with agents.

It comes with a single tool for all your needs, a modern package registry, a multi-core ready actor-model runtime, a whole new standard library, and first-class support for agentic work.

Riot is also a tool: riot — and it's the only tool you need in this stack.

It covers your usual SDLC needs:

Agent friendly

Riot ships with agent-facing instructions, not just human docs. The riot-ml skill tells agents how to use the stack, which commands to prefer, where workflows live, and how to keep package discovery grounded in pkgs.ml.

Every new Riot project created with riot init includes an .agents folder with the Riot skill already there. Start the project, then use your agent.
The local skill explains how to build, test, benchmark, run, format, fix, fuzz, and maintain Riot projects.
Riot commands prefer structured output with --json, so agents can inspect build results, diagnostics, test runs, package metadata, and registry flows without scraping prose.
The skill links deeper workflow references for testing, fuzzing, benchmarking, snapshots, and package lookup, so agents can run the right loop instead of guessing.
/llms.txt is the public discovery map for agents that find Riot from the web; inside a Riot workspace, the local skill is the starting point.

Start with agents included

A new Riot workspace already has the local agent instructions it needs.

$ riot init app
$ cd app
$ ls .agents/skills

Use structured command output

JSON output turns command results into data an agent can route, summarize, or repair from.

$ riot build --json
$ riot test --json
$ riot bench --json

Find packages without guessing

Use the package registry and its agent guide when a workflow needs dependencies or package docs.

$ riot search std --json
$ curl https://pkgs.ml/llms.txt

What’s possible in Riot?

Riot is for building OCaml software as one piece: tools, services, databases, packages, experiments, and systems that need to stay understandable while they grow.

Multi-core applications

Build actor-oriented systems on top of the runtime in std/runtime and the actor interface exposed through std/actor. Spawn work, supervise it, and let Riot use the cores you have.

Command line interfaces

Build fast CLIs with structured output, clear errors, and the kind of terminal behavior agents and humans can both drive.

Cloud and networked services

Use actors, supervision, message passing, and a practical standard library to build services that do real IO. The std/IO surface includes ioSlice for zero-copy operations when bytes need to move without extra copying.

Developer tooling

Write formatters, linters, code generators, release tools, migration scripts, and project automation with the same toolchain they plug into.

TUI applications

Build terminal interfaces with Riot packages like minttea and gooey: structured state, keyboard-driven UI, and native terminal ergonomics.

Web applications

Build web surfaces with suri, including LiveView support in suri/liveview, typed domain logic, and agent-friendly APIs without giving up the ergonomics of OCaml.

Database-backed systems

Build typed database flows with sqlx, connect to PostgreSQL through postgres, and use sqlite when the right database is a local file.

Agentic workflows

Create workflows that can be run, inspected, repaired, and repeated by agents: JSON output, stable diagnostics, clear command boundaries, and recoverable failure modes.