Architecture
This is the centerpiece. The diagram below is the whole system — and every component is clickable. Click a node to drill into its deep-dive page; each of those pages has its own diagram that drills further, down to the source on GitHub.
System overview (click any node)
Underlined nodes are clickable; dashed boxes are groupings. (Adapted from
website/docs/reference/diagrams/architecture.md.)
Component map
| Component | What it does | Deep dive |
|---|---|---|
| Orchestrator | FastAPI control plane: lifecycle, state, forwarding | Orchestrator → |
| Image Builder / Kaniko | Compose images from plugins, build in-cluster | Image builder → |
| Server Pod | Sandboxed FastAPI environment + MCP gateway | Server → |
| Clients | Python client library + MCP access for agents | Client → |
| Plugins | Image / server / client extension points | Plugins → |
| Watcher | Cleanup / reconcile loop | Watcher → |
| Rewards & Tools | What agents do & how they're scored | Rewards & tools → |
| PostgreSQL | Clients, servers, jobs, snapshots | Orchestrator → |
| Registry & Observability | Image storage, metrics & traces | Deployment → |
The key flows
- Build image — orchestrator compiles an
Image(plugins) → build spec → Kaniko job → image pushed to the registry. - Provision — orchestrator creates a Kubernetes Deployment; the pod pulls the image and boots Supervisor → FastAPI server (and any in-pod IDE).
- Use — client/agent requests are forwarded by the orchestrator into the server pod's HTTP / MCP endpoints; tools execute inside the sandbox.
- Clean up — the watcher reconciles database state with the cluster and tears down stale resources.
New to IdeGYM? Read the core concepts first, then the end-to-end data flow.