IdeGYM is a framework for creating disposable, scalable development environments for training reinforcement learning models. It provides tools for inspecting and modifying those environments, and can also be used for running AI agents or any workflow that requires clean, reproducible workspaces.
Think of it as GitHub Codespaces for RL training — but designed for thousands of parallel, short-lived environments.
📖 Docs & interactive architecture → jetbrains-research.github.io/idegym The site is built from
website/; the reference guides live underwebsite/docs/reference/.
- Scalable orchestration — spin up and tear down Kubernetes-based environments on demand
- Plugin-based image builder — compose Docker images from reusable plugins via a Python API or YAML; see Plugin Architecture
- Flexible project loading — clone from Git, download and extract a project archive, or mount a volume with a project directly into the image; see Image Builder
- HTTP and WebSocket forwarding — the orchestrator proxies requests directly to running server pods; WebSocket support enables integration with OpenEnv-compatible environments
- Persistent request history — every forwarded request and its response is stored in the database and retrievable later, enabling offline reward computation and reproducible evaluation
- Automatic resource cleanup — a background watcher periodically reconciles the database against live Kubernetes state, evicting stale servers and reclaiming resources without manual intervention
- Full observability — built-in Prometheus metrics, Grafana dashboards, and distributed tracing via Tempo
- MCP interface — the orchestrator exposes an MCP server at
/mcp; agents can discover and call all IdeGYM operations as MCP tools without touching the REST API directly; see MCP Server - IDE integration — optional IntelliJ IDEA and PyCharm plugins add live code inspection endpoints and typed client methods for IDE-aware environments; see Tools Reference
- Server checkpoint/restore — snapshot a warmed-up server and restore future servers from it, skipping cold-start work like project indexing; see Pod Snapshots
- Fast iteration — local development with Minikube mirrors the production Kubernetes setup
Everything lives on the IdeGYM site — an
interactive, drill-down architecture diagram plus the guides below. The site is built from
website/, and the reference guides are the relocated docs under
website/docs/reference/.
| Guide | Description |
|---|---|
| Architecture | Interactive system diagram — click a component to drill in |
| Core Concepts | Plain-language glossary of every moving part |
| Data & Usage Flow | The end-to-end RL / eval lifecycle |
| Getting Started | Prerequisites, installation, and running tests locally |
| Local Deployment | Run the full stack on Minikube (with GHCR images or local builds) |
| Remote Deployment | Deploy to a production Kubernetes cluster |
| Image Builder | Build custom environment images with the plugin API |
| Client Library | Python client API reference |
| MCP Server | Tool-based access to orchestrator operations |
| Tools Reference | All tools available on IdeGYM servers: bash, file ops, IDE inspection, mcp-steroid |
| Full Flow Example | End-to-end walkthrough: build an image, start a server, run a command |
| Plugin Architecture | Extending IdeGYM with image, server, and client plugins |
| HTTP Error Codes | HTTP status codes for orchestrator and server endpoints |
| API Reference | Interactive OpenAPI for the orchestrator and in-pod server |
| E2E Tests | Running the end-to-end test suite on Minikube |
| Orchestrator API | REST API reference for the orchestrator service |
uv>= 0.10.0 — Python package and project manager- Python 3.12 (installed automatically by
uv) - Docker — for integration tests and local image builds
# Clone the repository
git clone https://github.com/JetBrains-Research/idegym.git
cd idegym
# Install Python 3.12 and project dependencies
uv python install
uv venv --seed
uv sync --all-packages --all-extras --all-groups
# Install pre-commit hooks
uv run pre-commit install# Unit tests only (no external dependencies)
uv run pytest -m unit
# Integration tests (requires Docker with a registry on localhost:5000)
uv run pytest -m integration
# End-to-end tests (requires a running Minikube cluster)
uv run pytest -m e2eSee Getting Started for per-suite prerequisites.
uv run ruff format
uv run ruff checkidegym/
├── api/ # Pydantic API models
├── backend-utils/ # Shared backend utilities (Kubernetes, telemetry)
├── client/ # Python client library
├── common-utils/ # Shared utilities (config, logging)
├── examples/ # Runnable integration examples (standalone, not part of the workspace)
├── image-builder/ # Plugin-based Docker image building system
├── orchestrator/ # Kubernetes orchestrator service (FastAPI + PostgreSQL)
├── rewards/ # Reward calculation for agent evaluation
├── server/ # IdeGYM server (runs inside containers)
├── tools/ # Tool implementations (bash, file operations)
├── watcher/ # Background reconciler (cleanup, crash detection)
├── unit-tests/ # Unit test suite
├── integration-tests/ # Docker-based integration tests
├── e2e-tests/ # Kubernetes end-to-end tests
├── plugins/ # Image/server/client plugins (defaults, IntelliJ IDEA, PyCharm, OpenHands, shared utilities)
├── charts/ # Helm charts for Kubernetes deployment
├── scripts/ # Build and deployment scripts
└── website/ # Docs & presentation site (Docusaurus); guides in website/docs/reference/
The examples/ directory contains standalone, runnable examples showing
how to integrate external environments with IdeGYM. It is intentionally kept separate from the
main uv workspace because the OpenEnv environment packages have transitive dependencies that
conflict with the backend infrastructure packages.
See examples/README.md for available integrations and setup instructions.
We welcome contributions! Please open an issue or pull request on GitHub.
Read AGENTS.md first — it collects the repository's coding standards, testing rules, and the invariants that are easy to trip over. It applies to coding agents and humans alike, and is expected to be updated by whoever makes it inaccurate.
Before submitting a pull request:
- Run
uv run ruff format && uv run ruff checkto fix style issues - Run
uv run pytest -m "unit or integration"to verify tests pass - Ensure pre-commit hooks pass:
pre-commit run --all-files
See LICENSE for details.