Upload a custom environment¶

Add your own Python gym code, choose an entrypoint class, validate, and save a version before training.

Prerequisites¶

Classic RL or Advanced Training project (custom gyms work with Classic RL experiments).
A Python module or zip ready to upload.

1. Open Environments¶

Click Environments in the left sidebar. This list is custom environments only. Built-in gyms show up later in the experiment Environment step.

Sidebar with Environments highlighted — **Environments** in the sidebar.¶

2. Create environment¶

Open the create flow and name the environment. The modal steps are Setup, Configuration, then Finalization. After that the editor opens and validation runs on the working copy.

Create custom environment modal — Starting a new custom environment.¶

3. Upload code¶

On Setup, upload your environment archive. Wait until the file is accepted.

Upload step for environment archive — The upload step with a file selected.¶

4. Entrypoint¶

On Finalization, pick the gym entrypoint. Click Finish to save the version and open the code editor. Validation runs on the working copy; you can click Validate again.

Entrypoint selection step — Choosing an entrypoint class.¶

5. Code editor view¶

After Finish, Arena opens the environment version in the code editor and auto-runs validation on the working copy.

Custom environment code editor — Viewing environment source in the editor.¶

6. Validation results¶

In the code editor, run Validate and open the checklist to review test results.

Custom environment validation checklist — Validation checklist for the working set.¶

7. Validation chart¶

Inspect rollout or reward charts from validation when available.

Custom environment validation chart — Validation chart panel.¶

8. Save version¶

Save the working set as a named version when validation passes.

Save custom environment version dialog — Confirming **Save version**.¶

9. Environment detail¶

After save, the environment page lists versions and status.

Custom environment detail page — The saved custom environment.¶

Language-based (LLM simulation) gyms use a shorter create flow. See Upload a language-based environment.

From the terminal¶

Upload and validate.

Install the CLI and sign in (Authentication):

pip install "agilerl[arena]"
arena login
# or: export ARENA_API_KEY=arena_pat_…

arena env validate my-env --version v1 --source ./my_env.tar.gz

Python¶

Validate the gym, then point a Classic RL spec at the gym name:

from agilerl.arena import ArenaClient

with ArenaClient() as client:
    client.validate_environment(
        name="my-env",
        version="v1",
        source="./my_env.tar.gz",
        language_based=False,
    )
    spec = client.get_default_run_spec(algorithm="PPO", gym_env="my-env")