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.
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.
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.mdis the numbered requirements.tests/fixtures/reference-corpus.json↗ is 103 byte-exact captured cases to test against.docs/GAPS.mdlists 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-cartpoleprints 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.mdis the roadmap of decisions most worth arguing with.
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
/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 1The shape of what you just built:
your trainer · your agent · curl — anything that speaks HTTP
this repository
-
src/server/ · src/client/the I/O hosts
a
poll()loop and a dialer — the only code that owns a socket - ok src/proto/ calls no syscall, clock, or process function
-
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
- ok wire/ knows no application vocabulary (tier A: words)
-
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
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 checkThat 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.
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.
| # | Method | Path | Answers |
|---|---|---|---|
| 1 | GET | /openapi.json | 200 — info.version selects the conformance profile |
| 2 | GET | /list_environments | 200 ["counter_env"] |
| 3 | GET | /{env}/splits | 501 — the Task API; every shipped env declines it |
| 4–7 | POST | /{env}/tasks, …/num_tasks, …/task, …/task_range | 501, or 422 on a missing field |
| 8 | WS | /mcp | bare JSON-RPC, no envelope, spaced separators (WART-13) |
| 9 | POST | /reset | 200 — stateless: builds an environment, runs it, destroys it |
| 10 | POST | /step | 200 — stateless too; the action arrives wrapped under "action" |
| 11 | GET | /state | 200 — truncated to the two base fields (WART-05) |
| 12 | GET | /metadata | 200 — six keys, fixed order |
| 13 | GET | /health | 200 {"status":"healthy"} — the container readiness contract |
| 14 | GET | /schema | 200 — JSON Schema for action and observation; the only typing channel |
| 15 | POST | /mcp | 200 JSON-RPC 2.0, four methods |
| 16 | WS | /ws | the 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 open | The socket closes |
|---|---|
| INVALID_JSON | CAPACITY_REACHED |
| UNKNOWN_TYPE | FACTORY_ERROR |
| VALIDATION_ERROR | SESSION_ERROR |
| EXECUTION_ERROR |
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.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
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-statelessDoes 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
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
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 mutation | Caught by | What it reported |
|---|---|---|
| Make WS coerce rewards to float, as HTTP does | the genuine Python client | FAIL bool_true: got 1.0 (float), want True (bool) |
Make WS always emit "metadata", as HTTP does | the byte-diff | one line differed — and every live client stayed green |
Answer /health with {"status":"ok"} | the reference validator | 5/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.
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
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 linesGoing 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 want | Read |
|---|---|
| the whole thing, guided | docs/TOUR.md — sixteen steps, about an hour |
| one episode, every byte | the annotated episode — the handshake, five frames, the close |
| the protocol as prose | docs/PROTOCOL.md — 23 server + 20 client requirements |
| what is deliberately absent | docs/NOT-THE-PROTOCOL.md |
| where the spec runs out | docs/GAPS.md (generated) |
| the reference's accidents, honoured | docs/WARTS.md (generated) |
| the protocol/library boundary, per symbol | docs/BOUNDARY.md (generated) |
| the memory model in one rule | docs/MEMORY.md |
| threat model and every cap | docs/SECURITY.md |
| install, vendor, embed, containerize | docs/PACKAGING.md |
| porting off POSIX | docs/PORTING.md — rewrite one file |
| how a failure travels | docs/ERRORS.md |
| the fuzzers, and what they found | docs/FUZZING.md |
| where each claim came from | docs/PROVENANCE.md |
| the captured bytes themselves | docs/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 ↗.