Upload a Model or Environment

Build a container, push it to RLMesh, and run it from the dashboard.

This example uploads a Gymnasium environment. A model follows the same login and push steps; its image serves a model instead of an environment.

Create the environment

In a new directory, add environment.py:

import gymnasium as gym
from rlmesh import EnvFactory


class CartPole(EnvFactory):
    def make(self) -> gym.Env:
        return gym.make("CartPole-v1")

Add a Dockerfile beside it:

FROM python:3.11-slim
ARG RLMESH_VERSION=0.1.0
RUN pip install --no-cache-dir "rlmesh[gymnasium]==${RLMESH_VERSION}"
WORKDIR /app
COPY environment.py .
EXPOSE 50051
CMD ["python", "-m", "rlmesh.serve", "--env", "environment:CartPole"]

rlmesh.serve starts the environment server when RLMesh runs the image. The platform uses that command to identify and probe the environment after you push it. For a model, use CMD ["python", "-m", "rlmesh.serve", "model:MyModel"] and declare its inputs and outputs with a ModelSpec. See Bring Your Own Container for a model container example.

This example pins rlmesh==0.1.0; override RLMESH_VERSION at build time to use another release. The platform admits an image when its rlmesh shares a workflow edition with the platform runtime; 0.1.0 implements the 2026.06 edition. A platform upgrade does not invalidate an image you already pushed unless that edition changes, and the probe reports the edition it negotiated. For a complete environment/model pair and a local container test, follow Bring Your Own Container.

Check before you push

Run both checks before every push. rlmesh check runs the packaging checks the platform runs at push time, so a missing ModelSpec, an environment without tags, or a spec that does not resolve fails here instead of on the probe. Run it against the class from the directory that holds it:

rlmesh check environment:CartPole

After building, rlmesh check-image reads the image config the way the platform will: the serve command, the exposed port, the architecture, the rlmesh workflow edition, and any dev.rlmesh.* labels. Fix what either command reports as failed; warnings do not block a push.

Hardware requirements

Most images declare nothing. Without a declaration the platform reads the image’s own markers:

  • A CUDA base (CUDA_VERSION, or the cuda>=X.Y part of NVIDIA_REQUIRE_CUDA, in the image config) needs an NVIDIA GPU whose driver supports that CUDA version or newer.
  • A ROCm base (ROCM_VERSION) needs an AMD GPU.
  • Without either, a PyTorch build tag such as 2.3.0+cu121 decides the same way.
  • Anything else runs on CPU.

To say more, such as a minimum compute capability or VRAM, write an rlmesh.toml next to the Dockerfile and publish with rlmesh registry publish, which builds the image and bakes the declaration into its dev.rlmesh.package label:

# rlmesh.toml
name = "my-model"
accel.vendor = "nvidia"
accel.cuda = ">=12.4"
accel.vram = "16Gi"
rlmesh registry publish registry.rlmesh.dev/your-namespace/my-model:v1
Key Value
accel.vendor "nvidia" or "amd". Every other key needs it.
accel.compute NVIDIA compute capability, a version constraint such as ">=8.0".
accel.cuda The CUDA version the host driver supports, a version constraint.
accel.driver The NVIDIA driver version, a version constraint such as ">=535.104".
accel.vram The minimum VRAM per GPU, as a quantity string such as "16Gi" or "24G".

A bare version is a minimum ("12.4" means ">=12.4"), and clauses join with commas (">=8.0,<10.0"). rlmesh registry publish --dry-run validates the file before building, and after the build the image is checked for declarations it contradicts, such as an accel.cuda older than the image’s CUDA runtime. The probe then runs the image on each kind of hardware its requirements admit, and the image page shows where it passed.

An organization admin can correct an image’s requirements without a rebuild: Edit metadata on the image page has a Requirements editor, saved as an override over what the image declares. A gpu tag from before requirements existed is still honoured for an image that declares no hardware, but new images use requires.

To ship several builds of one version, such as a CUDA build with a CPU fallback, see Compute Variants.

CPU and memory come from the probe’s measurements, floored at the platform defaults, unless the package label declares them.

Log in and push

Install the CLI with pip install rlmesh (see Your First Evaluation), then run:

rlmesh login
rlmesh registry login

The first command opens a browser to sign in. The second connects your local Docker client to the RLMesh registry, so you do not run docker login yourself. Its output ends with your push target:

Push targets
  • registry.rlmesh.dev/your-namespace

The same namespace is shown on the Registry page. Members and admins can push to it; viewers can only pull. Where a browser sign-in is awkward (an SSH session on a GPU box, a personal script), a personal API key with the Run evaluations preset works as the docker login password; it reaches only that organization’s namespace, and only while your role there still allows pushing. For shared CI, an admin creates an organization API key with the same preset instead.

Replace your-namespace below with yours, then build, check and push from the directory containing the two files:

docker build --platform linux/amd64 \
  -t registry.rlmesh.dev/your-namespace/cartpole:v1 \
  -t registry.rlmesh.dev/your-namespace/cartpole:latest .
rlmesh check-image registry.rlmesh.dev/your-namespace/cartpole:v1
docker push registry.rlmesh.dev/your-namespace/cartpole:v1
docker push registry.rlmesh.dev/your-namespace/cartpole:latest

--platform linux/amd64 matters on Apple silicon: the cluster runs amd64 nodes, and an arm64 image fails its probe. Give every build its own version tag (v1, v2, …) so you can pin it later, and push latest as well: latest selects the version the dashboard and an untagged request use. A push of only v1 records the version but does not select it.

Run an evaluation

Watch the image under Registry → Your uploads. After each push RLMesh probes the image: it starts it on the cluster, completes the handshake, sends test inputs (a model’s predict, an environment’s reset and step), and measures resources, GPU use and batch size. A probe can wait a few minutes while a node, often a GPU node, starts. Your organization can run 4 probes at once; a push beyond that is stored but not probed, so push it again once one finishes, or ask an admin to press Run probe on the image page.

If the probe fails, open the image to see why. Once it is ready, choose New evaluation, select the environment and a model, then launch. The evaluation page shows progress, episode results, and logs. To submit from a script instead, see CLI and API. For a model, read Model Weights and Checkpoints before you build.