miniopenenv

miniopenenv

The OpenEnv protocol, rebuilt from observed bytes in dependency-free C99 — small enough to read in an afternoon, faithful enough that Hugging Face's own client cannot tell it from the reference.

C99 · zero dependencies · Apache-2.0

New to OpenEnv? It is Hugging Face's standard for running reinforcement-learning environments as services. The environment runs in a container and speaks HTTP and WebSocket. The loop it speaks is the classic Gym one: reset(), step(action), observation, reward. So a trainer in one process can drive a game, a browser, a codebase or a robot sim in another. One run of the loop — a reset, then steps, until done — is an episode. The reference implementation, huggingface/OpenEnv ↗, is 752 Python files and 164,342 lines at the revision this repository captured (60ecc7b7).

The protocol buried inside those lines is a JSON envelope with four keys, seven WebSocket message types, and sixteen routes. This repository is that protocol, alone. It was reimplemented from captured wire traffic, separated from the framework around it — and the separation is enforced, not described. src/wire/ may not contain a single OpenEnv word. src/proto/ may not contain a single system call. make check fails the build if either stops being true.

It is written in C not because C is a good language for RL infrastructure, but because you cannot accidentally paraphrase Python in it.
§ 1 · Pick a door

Pick a door

You want to understand OpenEnv
read What the protocol is, then take the tour: sixteen steps, about an hour. At the end you will know the protocol rather than a codebase.
You are implementing OpenEnv in another language
three files are the spec that does not exist upstream. docs/PROTOCOL.md is the numbered requirements. tests/fixtures/reference-corpus.json ↗ is 103 byte-exact captured cases to test against. docs/GAPS.md lists the places where the protocol is underspecified and you will have to choose.
You are debugging any OpenEnv setup, even a pure-Python one
examples/oe_probe.c ↗ connects to any OpenEnv server and annotates every byte in both directions: the handshake, the frame headers, the rule each field obeys. make && build/rel/bin/oe_probe http://your-server --episode. One whole episode of that output, typeset, is the annotated episode.
You want the smallest possible OpenEnv server
a complete conforming environment is 45 statements of C and ships as a 211 kB container. The Python base image is 467 MB.
You want to train something against it, today
the arcade is ten game servers built on this protocol — a bandit, cart-pole, snake, 2048, Wordle, blackjack, a maze, pong, connect four and Kuhn poker — and one trainer that learns to play them over a real WebSocket. make train-cartpole prints a learning curve of 2000 episodes over a real WebSocket in a few seconds.
You found a byte we got wrong
file it ↗. A byte-level counterexample is the most valuable issue this project can receive. docs/GAPS.md is the roadmap of decisions most worth arguing with.
§ 2 · Sixty seconds

Sixty seconds

No dependencies. No autotools, no CMake, no submodules. Any C99 compiler on a POSIX system: Linux, macOS, the BSDs. (Elsewhere, see docs/PORTING.md; the port is one file.)

$ git clone https://github.com/ericflo/miniopenenv && cd miniopenenv
$ make
built: rel  lib=build/rel/libopenenv.a  programs=59

$ ./build/rel/bin/echo --port 8010 &
openenv info   listening on: 0.0.0.0:8010  max_sessions=8 max_connections=64

$ curl -s localhost:8010/health
{"status":"healthy"}

$ curl -s -X POST localhost:8010/step -H 'content-type: application/json' \
      -d '{"action":{"message":"hello"}}'
{"observation":{"metadata":{},"echoed":"hello"},"reward":null,"done":false,"metadata":null}

$ kill %1
Sixty seconds. A complete, conforming server: sixteen routes, /schema, WebSocket sessions. The reference's own openenv validate gives it 6/6. (The default port is 8000, the container contract; 8010 here only because this machine had 8000 taken.) — make interop, oracle 1

The shape of what you just built:

your trainer · your agent · curl — anything that speaks HTTP

this repository

  1. src/server/ · src/client/the I/O hosts

    a poll() loop and a dialer — the only code that owns a socket

  2. ok src/proto/ calls no syscall, clock, or process function
  3. src/proto/THE PROTOCOL

    16 routes · 7 message types · one 4-key envelope · 7 error codes — four pure functions: no socket, no clock, no global state

  4. ok wire/ knows no application vocabulary (tier A: words)
  5. src/wire/plumbing (not OpenEnv)

    HTTP/1.1 · RFC 6455 · JSON · UTF-8 · SHA-1 · arena — forbidden to contain a single OpenEnv word

make check fails the build if either boundary breaks

The stack. Two boundaries, both enforced rather than described: src/proto/ may not contain a single system call, and src/wire/ may not contain a single OpenEnv word. The seams between the layers are two of make check's fifty-two rules, quoted here by the names it prints for them. Each layer name links to the note that directory keeps about itself, and each of those notes opens with a claim you can check. — make check

That middle layer is the entire answer to "what is OpenEnv, exactly?" It is four pure functions, so you can embed it with no sockets at all. And the test suite can replay recorded reference traffic through it byte-for-byte, in about a millisecond.

§ 3 · The protocol, entire

The protocol, entire

A conforming OpenEnv server is an HTTP/1.1 server that answers sixteen routes. Every status code below was produced by envs/counter.c while writing this table.

#MethodPathAnswers
1GET/openapi.json200 — info.version selects the conformance profile
2GET/list_environments200 ["counter_env"]
3GET/{env}/splits501 — the Task API; every shipped env declines it
4–7POST/{env}/tasks, …/num_tasks, …/task, …/task_range501, or 422 on a missing field
8WS/mcpbare JSON-RPC, no envelope, spaced separators (WART-13)
9POST/reset200 — stateless: builds an environment, runs it, destroys it
10POST/step200 — stateless too; the action arrives wrapped under "action"
11GET/state200 — truncated to the two base fields (WART-05)
12GET/metadata200 — six keys, fixed order
13GET/health200 {"status":"healthy"} — the container readiness contract
14GET/schema200 — JSON Schema for action and observation; the only typing channel
15POST/mcp200 JSON-RPC 2.0, four methods
16WS/wsthe episode — the only route where one can exist

Over /ws: text frames, one JSON object each, strictly lock-step. One response per request, no correlation ids, nothing server-initiated.

// CLIENT -> SERVER  (five)                 // SERVER -> CLIENT  (four)
{"type":"reset" [,"data":{…}]}              {"type":"observation","data":{…}}
{"type":"step"  , "data":{…}}               {"type":"state"      ,"data":{…}}
{"type":"state"}                            {"type":"error"      ,"data":{…}}
{"type":"close"}                            {"type":"mcp"        ,"data":{…}}
{"type":"mcp"   , "data":{…}}

Every observation is this envelope, and it is the whole data model:

{"observation": {…env-specific…}, "reward": 3, "done": false, "metadata": {…}}

reward is bool | int | float | null. There is exactly one done, and no Gymnasium terminated/truncated pair. Errors are seven strings, a closed set. Their one observable difference is what happens to the socket:

The socket stays openThe socket closes
INVALID_JSONCAPACITY_REACHED
UNKNOWN_TYPEFACTORY_ERROR
VALIDATION_ERRORSESSION_ERROR
EXECUTION_ERROR
Plate 1. That is the protocol. All of it. Sixteen routes, seven message types, one envelope, seven error strings — every status code above was produced by envs/counter.c. src/proto/routes.c ↗ is the executable form. The vocabulary is src/proto/types.h ↗, a file that is 80% comment because the comment is the specification.
§ 4 · The stateless surprise

The stateless surprise

The route table marked /reset and /step stateless, and that word is doing more work than it appears to. A counter, stepped twice over HTTP:

$ curl -s -X POST http://127.0.0.1:8990/step -H 'content-type: application/json' -d '{"action":{"amount":2}}'
{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}

$ curl -s -X POST http://127.0.0.1:8990/step -H 'content-type: application/json' -d '{"action":{"amount":2}}'
{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}

2, then 2 again. Nothing is broken. Each HTTP call constructed a fresh environment, ran one step, and destroyed it; there is nowhere for the second step to accumulate. Now the same two steps over the WebSocket:

$ build/rel/bin/oe_probe http://127.0.0.1:8990 --episode --steps 2 --action '{"amount":2}'
  >> {"type":"step","data":{"amount":2}}
  << {"type":"observation","data":{"observation":{"metadata":{"steps":1},"total":2,…},"reward":2.0,"done":false,…}}
  >> {"type":"step","data":{"amount":2}}
  << {"type":"observation","data":{"observation":{"metadata":{"steps":2},"total":4,…},"reward":4.0,"done":true,…}}
  ~ one connection is one session is one environment instance
  ~ WS /ws is the only transport in OpenEnv where an episode can exist
Plate 2. The same counter, stepped twice on each transport: 2 then 2 over HTTP, 2 then 4 over the WebSocket. Nothing is broken — each HTTP call built a fresh environment, ran one step, destroyed it. tools/demo.sh ↗ exits 1 unless the HTTP bodies match and the WS observations differ. A demo that cannot fail is a screenshot. — make demo-stateless
§ 5 · Proof

Does it actually interoperate?

An oracle, here, is an independent judge — usually upstream's own code. Sixteen oracles grade this implementation: one recorded corpus and fifteen live checks. The judge in every live one is somebody else's code. Oracle zero is the corpus: 103 cases recorded off six real reference servers and checked in. The replay drives them through the four pure functions with no socket, no clock and no Python. The other fifteen ask live:

$ make interop
ok    oracle 1: reference validator — 6/6 required criteria
ok    oracle 2a: upstream EnvClient drove envs/counter.c to done
ok    oracle 2b: upstream EnvClient read bool/int/float rewards back as themselves
ok    oracle 2c: our frame cap costs the real client a 300 KB action, exactly as limits.h says
ok    oracle 2d: upstream EnvClient drove tour/01_minimal.c to done — the two-endpoint claim
ok    oracle 2e: the genuine MCPToolClient listed and called two tools on envs/echo_tools.c
ok    oracle 3a: examples/oe_agent drove the real Python server to done
ok    oracle 3b: same client, both servers — 5 replies identical byte for byte
ok    oracle 3c: tour/03_client.c drove the real Python server to done — the hand-written client
ok    oracle 3d: examples/oe_agent (library) and tour/03_client (wire) sent 3 identical client frames byte for byte
ok    oracle 4: the official mcp SDK dies the same way on all three servers — McpError: Method not found: initialize
ok    oracle 5: 230 lines of stdlib Python satisfy the genuine MCPToolClient on both doors
ok    oracle 6: verifiers's taskset predicate decides envs/echo_tools.c HAS tools
ok    oracle 7: time-to-EOF 0.112 ms here / 0.313 ms at the reference (both sub-linger; ours was ~1001 ms before the half-close) — one socket carries one exchange here, a second at the reference (keep-alive): the lifetime divergence the corpus never captured
Oracle 1 is openenv validate --url, the reference project's own conformance suite: the only judge here we did not write a line of. Oracle 2 is the genuine openenv.core.env_client.EnvClient, driving our C server to done with its own WebSocket library and its own pydantic models. Oracle 2e is a different upstream client, MCPToolClient: it reads a tool table out of a C environment into a pydantic model that forbids a fourth key. Oracle 4 is the only one here where passing means a peer FAILED. The official Model Context Protocol SDK cannot handshake with the reference implementation either, and the two servers refuse it with the same sentence. — make interop (sh interop/setup.sh first; it skips loudly without it)

Oracle 3 is the direction that matters most: our client in front of a server we did not write. A client tested only against its own server is a mirror, not a measurement. Its strongest form points the same C client at the Python server and at ours, and diffs every payload:

$ diff wire-python.txt wire-c.txt
$ echo $?
0
Plate 3. An empty diff. Two servers sharing no line of code, indistinguishable to a client that reads bytes — the only definition of protocol compatibility that means anything. — make interop, oracle 3b

And each oracle was made to fail on purpose

Three deliberate mutations, each the obvious simplification a maintainer would reach for in six months, each caught by a different oracle:

The mutationCaught byWhat it reported
Make WS coerce rewards to float, as HTTP doesthe genuine Python clientFAIL bool_true: got 1.0 (float), want True (bool)
Make WS always emit "metadata", as HTTP doesthe byte-diffone line differed — and every live client stayed green
Answer /health with {"status":"ok"}the reference validator5/6, health_endpoint failed — and every live client stayed green

The last two changes were each visible to exactly one oracle, and real clients felt neither. No single judge sees everything; that is why there are fifteen live oracles, and the corpus underneath them.

§ 6 · How big is it, really?

How big is it, really?

Don't take a paragraph's word for it. The measurement is a build target, and make check fails if this transcript drifts more than ten percent from what the target actually prints.

$ make lines
GROUP / DIRECTORY              CODE   TOTAL
-----------------------------------------------
proto  (THE PROTOCOL)          4516   10990
-----------------------------------------------
wire   (RFC plumbing)          4771    9681
server (I/O)                   2777    5300
client (I/O)                    944    1651
-----------------------------------------------
envs   (YOURS)                  294     756
tour                            815    1407
  of which: THE PROTOCOL         64
  of which: the socket          177
  of which: neither half         13
  the Python: PROTOCOL           78
  the Python: the socket         0*
  02_conformant: WHOLE FILE      77
examples                       1651    2274
tests                         16143   25273
include (public API)            271    1219
Plate 4. 64 statements of protocol, 177 of socket in tour/01_minimal.c ↗. That file serves a real episode to the genuine Python client, with the JSON written as string literals. The 78 beside them is the reference's own minimal server in Python. The protocol is tiny in both languages, and everything else is plumbing somebody wrote once. A * marks a figure recorded rather than measured. — make lines
§ 7 · Going deeper

Going deeper

The contents page is every document and every directory note, grouped and described one line each. (It counts itself in its own standfirst.) The shortest route to the right one:

You wantRead
the whole thing, guideddocs/TOUR.md — sixteen steps, about an hour
one episode, every bytethe annotated episode — the handshake, five frames, the close
the protocol as prosedocs/PROTOCOL.md — 23 server + 20 client requirements
what is deliberately absentdocs/NOT-THE-PROTOCOL.md
where the spec runs outdocs/GAPS.md (generated)
the reference's accidents, honoureddocs/WARTS.md (generated)
the protocol/library boundary, per symboldocs/BOUNDARY.md (generated)
the memory model in one ruledocs/MEMORY.md
threat model and every capdocs/SECURITY.md
install, vendor, embed, containerizedocs/PACKAGING.md
porting off POSIXdocs/PORTING.md — rewrite one file
how a failure travelsdocs/ERRORS.md
the fuzzers, and what they founddocs/FUZZING.md
where each claim came fromdocs/PROVENANCE.md
the captured bytes themselvesdocs/evidence/OBSERVED-WIRE.md

Each directory says what it is in its own README: src/, src/wire/, src/proto/, src/server/, src/client/, envs/, examples/, tour/, tests/, tests/embed/. The whole README is here. The source is on GitHub ↗.