Protocol

gym-over-gRPC protocol

The eight unary RPCs of the AleEnv service, official vs practice environments, the hidden-seed lifecycle, and how the harness reads the authoritative EvalResult.

The AleEnv service

Every ALE Robotics task ships as one evaluator container that bundles exactly one simulator and one domain metric. The container exposes a single gRPC service, AleEnv, with 8 unary RPCs. The agent runs in a separate, offline (no-network) sandbox and interacts with the simulator only through this service — there is no other channel to the evaluator. The authoritative domain metric is always computed inside the evaluator and read back by the harness; the agent never self-reports the score.

This page describes the RPC surface, the distinction between official and practice environments, the lifecycle of hidden seeds, and how the harness obtains the authoritative EvalResult. For how episodes are actually driven, see Interactive tasks and Batch tasks; for how the returned numbers become a score, see Scoring.

The eight RPCs

All calls are unary (single request, single response). There are no streaming RPCs.

RPC	Group	Purpose
CreateEnv	Lifecycle	Create an environment instance and return its handle; declares whether the env is official.
GetSpec	Lifecycle	Return the observation space, action space, and task metadata for a handle.
Reset	Episode	Begin a new episode and return the initial observation.
Step	Episode	Apply an action and return the next observation, reward, done flag, and info.
StartEvalSession	Interactive eval	Run the official scoring episodes on hidden seeds and produce an EvalResult.
GetEvalResult	Read result	Return the authoritative EvalResult for a completed session.
SubmitBatchEval	Batch eval	Trigger the evaluator's native pipeline over a submission on the shared volume.
GetBatchEvalStatus	Batch eval	Poll a batch run's status and, on completion, its EvalResult.

Lifecycle and episode RPCs

CreateEnv and GetSpec establish an environment and let the agent discover its interface. Reset and Step follow standard gym semantics: Reset starts an episode and returns the first observation; Step advances the simulation one action at a time. Agents use these to drive practice episodes and to develop their method locally.

Evaluation RPCs

Scoring never happens through raw Step loops that the agent controls. Instead:

Interactive tasks call StartEvalSession, which runs a fixed number of scoring

episodes on hidden seeds inside the evaluator, then GetEvalResult to read the outcome.

Batch tasks write a submission to the shared /submission volume, call

SubmitBatchEval to launch the evaluator's native pipeline at full speed, and poll GetBatchEvalStatus until it reports completion with an EvalResult.

Official vs practice environments

CreateEnv can produce two kinds of environment. Only the harness's environment is official=true. Any environment the agent creates for its own experimentation is a practice env: identical interface, but its episodes never contribute to the score.

This separation is deliberate. The agent is free to Reset/Step practice envs as much as it likes, on any seeds it chooses, to tune its method. When it is ready, the harness — not the agent — drives the official environment through the evaluation RPCs. The agent cannot create an official env or promote a practice env to official.

Hidden-seed lifecycle

Official evaluation runs on hidden seeds that the evaluator holds internally:

Seeds are never sent to the agent in any RPC response.
During an eval session, client-supplied Reset seeds are ignored — the evaluator

substitutes its own hidden seeds, so the agent cannot memorize or pre-fit to the scoring distribution.

Seeds are never stored in raw form. The trajectory records only a commitment,

SHA256(seed || run_id || evaluator-secret), so a run can be audited for seed consistency without ever revealing the seed. See Trajectory format.

The practical consequence: an agent optimizes against practice seeds it controls, but is graded on seeds it has never seen and cannot enumerate.

Reading the authoritative EvalResult

The EvalResult returned by GetEvalResult / GetBatchEvalStatus is the single source of truth for a task's measured metric. Critically, the harness reads it over its own gRPC connection, using a docker-exec loopback client into the evaluator container. The agent sandbox has no exec access to the evaluator and cannot fabricate, intercept, or alter an EvalResult.

agent sandbox ──gym-over-gRPC──▶ AleEnv service (Reset/Step, practice envs)
                                        │
harness ──docker-exec loopback gRPC──▶ AleEnv service (official env, GetEvalResult)
                                        │
                              authoritative EvalResult ──▶ scoring.py

The harness then feeds the measured metric into Scoring: a normalized ratio against the paper target (default cap 1.5), safety penalty factors, and — for reproduction-genre tasks — the fail-closed faithfulness gate. Because the number the harness scores comes straight from the evaluator's own connection, self-reported agent metrics carry no weight. See Agent integration for the client's side of the protocol.