Skip to main content

Client

The idegym-client package is the programmatic front door. It handles authentication, client registration, server lifecycle, and every operation on a running environment — all async. Agents that prefer tools over code can use the orchestrator's MCP interface instead; both reach the same handlers.

Client surface (click a node for source)​

IdeGYMClient​

The entry point, used as an async context manager: entering registers the client with the orchestrator; exiting deregisters it and stops its servers.

async with IdeGYMClient(
    orchestrator_url="https://idegym.example.com",
    name="my-training-run",
    namespace="idegym",
    auth=BasicAuth(username="admin", password="..."),
) as client:
    async with client.with_server(image_tag="...", server_name="s1") as server:
        result = await server.execute_bash("echo hello")

Key methods: with_server(...) (start + auto-cleanup), explicit start_server / stop_server / finish_server, list_servers() (what this registration owns), jobs.build_and_push_images(...), and health_check(). The reuse_strategy (NONE / RESTART / RESET) and close_action (FINISH / STOP) control reuse — central to fast RL episodes.

The client is bound to the loop that created it: it owns an httpx session and a heartbeat task. Since deregistering terminates every server a client owns, an integration that drives sandboxes from several loops has to share one registration rather than open two — which is what SharedIdeGYMClient is for. It owns a loop in a dedicated thread and marshals calls onto it. See the client reference.

Failures are typed. An HTTP error raises a subclass of IdeGYMHTTPError chosen by status (IdeGYMNotFoundError, IdeGYMBusyError, …), an error the sandbox itself returned on a forwarded call raises IdeGYMSandboxError, and a failure with no response at all raises IdeGYMTimeoutError (also a builtin TimeoutError) or IdeGYMConnectionError. Lifecycle calls such as stop_server raise rather than returning an error value, and a permanent 4xx is never retried. See error handling.

IdeGYMServer​

Returned by with_server() / start_server(). It exposes the environment's operations:

  • Tools — execute_bash, create_file, edit_file, patch_file, reset_project.
  • Rewards — compilation_reward, setup_reward, test_reward.
  • Lifecycle — restart_server, list_capabilities (the runtime plugin list).
  • OpenEnv — openenv_url for WebSocket/OpenEnv-compatible access.

Plugin operations & forward()​

When IdeGYMServer is constructed it loads the idegym.plugins.client entry points and attaches each as an attribute (hyphens → underscores), so an installed PyCharm plugin gives you server.pycharm.inspect(...). Each server instance gets its own ops objects.

For endpoints without a typed wrapper, the escape hatch is forward():

from idegym.api.tools.bash import BashCommandRequest

response = await server.forward(
    method="POST", path="tools/bash", body=BashCommandRequest(command="echo hi", timeout=30.0)
)

It delegates to the same ForwardingOperations every typed method uses, accepts any Pydantic body, and returns the parsed JSON. See plugins for how the three plugin hook points line up.

View source​