Model Weights and Checkpoints

Your model image has to load its weights somewhere. There are three options, in order of preference.

1. Bake the weights into the image (recommended)

Copy the weights into the image at build time and load them from a fixed path in load(). The image then starts the same way on every probe and every evaluation, with no download at run time.

FROM python:3.11-slim
ARG RLMESH_VERSION=0.1.0
RUN pip install --no-cache-dir "rlmesh[numpy]==${RLMESH_VERSION}" torch
WORKDIR /app
COPY weights/ /opt/weights/
COPY model.py .
EXPOSE 50051
CMD ["python", "-m", "rlmesh.serve", "model:MyPolicy"]

import torch
from rlmesh.numpy import Model


class MyPolicy(Model):
    spec = ...  # your ModelSpec

    def load(self):
        self.policy = torch.load("/opt/weights/policy.pt", weights_only=False)
        self.policy.eval()

    def predict(self, observation):
        ...

To bake weights from a Hugging Face repository, download them during the build into an explicit directory:

RUN pip install --no-cache-dir huggingface_hub \
 && python -c "from huggingface_hub import snapshot_download; snapshot_download('your-org/your-model', local_dir='/opt/weights')"

For a private repository, pass your token as a build secret. It is used during the build and is not stored in the image:

RUN --mount=type=secret,id=hf_token \
    HF_TOKEN="$(cat /run/secrets/hf_token)" \
    python -c "from huggingface_hub import snapshot_download; snapshot_download('your-org/your-model', local_dir='/opt/weights')"

export HF_TOKEN=hf_...
docker build --platform linux/amd64 --secret id=hf_token,env=HF_TOKEN -t registry.rlmesh.dev/your-namespace/my-model:v1 .

Load from the directory (/opt/weights above), not by repository id. The platform sets HF_HOME to its own cache directory when it runs your image, so files cached in the default Hugging Face location at build time are not found at run time.

2. Download from Hugging Face when the model starts

load() can download the weights each time the model starts:

from huggingface_hub import snapshot_download

class MyPolicy(Model):
    def load(self):
        path = snapshot_download("your-org/your-model")
        ...

Run pods reach the internet only through a proxy. It allows these hosts, over HTTPS (port 443) or HTTP (port 80):

• huggingface.co, hf.co and their subdomains
• pypi.org and files.pythonhosted.org
• github.com and objects.githubusercontent.com

The platform sets HTTPS_PROXY and HTTP_PROXY for you. huggingface_hub, pip and requests use them. A client that ignores them has no internet access.

Every probe and every evaluation downloads the weights again, so starts are slower than with baked weights.

Private repositories. Set HF_TOKEN on the model in the evaluation request. The dashboard has no field for it, so submit the request from the CLI or Python:

{
  "models": [
    {
      "model": "your-namespace/my-model",
      "envVars": { "HF_TOKEN": "hf_..." }
    }
  ],
  "tasks": [{ "taskId": "libero_goal/0", "env": "prebuilt/libero", "episodes": 5 }]
}

Two things to know before you do this:

• The token is stored with the evaluation. Everyone in your organization can read it on the evaluation’s Configuration tab under Raw request, and through the API. Use a read-only token limited to the one repository.
• The probe that runs after you push does not receive the request’s env vars. If load() cannot finish without the token, the probe fails and the image cannot be selected for an evaluation. In that case bake the weights in with a build secret (option 1).

Optional: environment variables the platform sets

The platform sets two variables on the model container when they apply. Reading them is optional; an image that ignores them runs as before.

Both are absent otherwise, so give each a fallback:

import os

checkpoint = os.environ.get("RLMESH_MODEL_CHECKPOINT_PATH", "/opt/weights/policy.pt")
seed = os.environ.get("RLMESH_MODEL_SEED")
if seed is not None:
    torch.manual_seed(int(seed))

3. Anything else

Loading weights from S3, Google Cloud Storage, Weights & Biases, or your own servers is not supported yet: those hosts are not on the list above. If you need one of them, ask us. Until then, copy the weights into the image (option 1).