Download OpenAPI specification:Download
REST API for the IdeGYM orchestrator: client registration, server lifecycle, in-cluster image builds, request forwarding, async operations, and pod snapshots.
| client_id required | string <uuid> (Client Id) |
| availability | string (AvailabilityStatus) Default: "ALIVE" Enum: "ALIVE" "FINISHED" "REUSED" "FAILED_TO_START" "STOPPED" "KILLED" "CRASHED" "DELETION_FAILED" "RESTART_FAILED" |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "availability": "ALIVE"
}null| name required | string (Name) Human-readable name for the client |
| nodes_count | integer (Nodes Count) >= 0 Default: 0 Number of nodes to spin up for the client |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace for the client and its servers |
{- "name": "string",
- "nodes_count": 0,
- "namespace": "idegym"
}null| client_id required | string <uuid> (Client Id) UUID of the client |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace containing the client servers |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym"
}null| client_id required | string <uuid> (Client Id) UUID of the client |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace containing the client servers |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym"
}null| client_id required | string <uuid> (Client Id) UUID of the client that will own the server |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace where the server should run |
| image_tag required | string (Image Tag) [ 1 .. 383 ] characters ^[a-z0-9._/:@-]+$ OCI image to deploy as the server |
| server_name | string (Server Name) [ 1 .. 63 ] characters ^[a-z]([-a-z0-9]*[a-z0-9])?$ Default: "default-idegym-server" Logical server name, used as the Kubernetes resource name prefix. It is one of the seven fields reuse matches on, not the key: see 'reuse_strategy' for the full set. |
Runtime Class Name (string) or Runtime Class Name (null) (Runtime Class Name) Kubernetes RuntimeClass for the server pod, for example "gvisor" for sandboxing | |
| run_as_root | boolean (Run As Root) Default: false Run the server container as UID 0 |
| service_port | integer (Service Port) [ 0 .. 65535 ] Default: 80 Port exposed by the Kubernetes Service |
| container_port | integer (Container Port) [ 0 .. 65535 ] Default: 8000 Port the server container listens on |
KubernetesResources (object) or null Kubernetes resource requirements as requests/limits dictionaries | |
Node Selector (object) or Node Selector (null) (Node Selector) Kubernetes node selector labels for scheduling the server pod | |
object (Labels) Extra labels applied to the server's Deployment, Pod, Service and PodDisruptionBudget, so a sandbox can be found with 'kubectl get pods -l ...' and grouped for cost attribution. Keys IdeGYM manages ('app', 'app.kubernetes.io/', 'idegym.jetbrains.com/') are rejected rather than silently ignored, since overwriting them would break the selectors that address the pod. Applied only when a server is created: a server taken over through RESTART or RESET keeps the labels it was created with, so use reuse_strategy=NONE when the pod's labels must match this request. | |
object (Annotations) Extra annotations applied to the server pod. Use for metadata too long or too unstructured to be a label, such as a task URL or a serialized request id. Keys IdeGYM manages ('cluster-autoscaler.kubernetes.io/safe-to-evict', 'podsnapshot.gke.io/', 'prometheus.io/') are rejected rather than silently overwritten. Like 'labels', applied only when a server is created: a reused server keeps the annotations it was created with. | |
Array of objects (Volumes) Pod-level volumes (native Kubernetes shape), mounted into the server container via 'volume_mounts' | |
Array of objects (Volume Mounts) Volume mounts added to the server container (native Kubernetes shape) | |
Array of objects (Env From) envFrom sources (secretRef/configMapRef) imported into the server container as env vars | |
Service Account Name (string) or Service Account Name (null) (Service Account Name) ServiceAccount for the server pod. Ignored during snapshot preparation, where the configured snapshot ServiceAccount takes precedence. | |
object (KubernetesPodOverrides) Partial V1PodSpec deep-merged into the generated pod spec. Escape hatch for pod-level fields without a dedicated option, e.g. tolerations, hostAliases, dnsConfig, or pod-level securityContext. Applied last, so for any overlapping key it takes precedence over the dedicated fields above (scalars overridden, list fields concatenated). Two invariants are enforced: it may not set serviceAccountName (use service_account_name), and it may add sidecar containers but not replace the managed 'server' container. | |
| server_start_wait_timeout_in_seconds | integer (Server Start Wait Timeout In Seconds) >= 0 Default: 300 How long to wait in seconds for the server pod to become ready. The default covers a cold image pull, which a multi-gigabyte environment image needs minutes for; raise it further for larger images rather than retrying into the same wall. |
| reuse_strategy | string (ServerReuseStrategy) Default: "RESET" Enum: "NONE" "RESTART" "RESET" Whether to take over an existing server instead of creating one: NONE always creates from scratch, RESTART reuses one and restarts its pod, RESET reuses one and resets the project state. Reuse runs only for RESTART and RESET, and a candidate must match on all seven of: client name, image_tag, runtime_class_name, run_as_root, server_kind, server_name (when set), and an availability of FINISHED. A server is FINISHED only after finish_server; a client that always calls stop_server leaves its servers STOPPED, so reuse never hits. StartServerResponse.reused reports what actually happened. A reused server keeps the Kubernetes labels and annotations it was created with; only NONE guarantees they match this request. |
| server_kind | string (ServerKind) Default: "idegym" Enum: "idegym" "openenv" Server type: "idegym" or "openenv" |
SnapshotRef (object) or null GKE ONLY: restore the server from a pod snapshot [Look at the README]. Provide the snapshot group id, and optionally a specific snapshot tag. Leave empty to start a fresh server. | |
| max_restarts | integer (Max Restarts) >= 0 Default: 0 Pod restarts tolerated before the server is marked CRASHED and torn down by the watcher. 0 (default) gives up on the first crash, which surfaces the failure reason to the client instead of looping restarts. Increase to allow transient crashes to self-heal. |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym",
- "image_tag": "registry.example.com/my-env:latest",
- "server_name": "my-server",
- "runtime_class_name": "gvisor",
- "run_as_root": false,
- "service_port": 80,
- "container_port": 8000,
- "resources": {
- "limits": {
- "cpu": "1",
- "memory": "1Gi"
}, - "requests": {
- "cpu": "500m",
- "memory": "512Mi"
}
}, - "node_selector": {
- "kubernetes.io/os": "linux"
}, - "labels": {
- "job": "swe-bench-run-42",
- "team": "research"
}, - "volumes": [
- {
- "name": "agent-creds",
- "secret": {
- "secretName": "agent-creds"
}
}
], - "volume_mounts": [
- {
- "mountPath": "/etc/creds",
- "name": "agent-creds",
- "readOnly": true
}
], - "env_from": [
- {
- "secretRef": {
- "name": "agent-creds"
}
}
], - "service_account_name": "agent-runner",
- "pod_overrides": {
- "tolerations": [
- {
- "key": "string",
- "operator": "string",
- "value": "string",
- "effect": "string",
- "tolerationSeconds": 0
}
], - "hostAliases": [
- {
- "ip": "string",
- "hostnames": [
- "string"
]
}
], - "nodeSelector": { },
- "runtimeClassName": "string",
- "priorityClassName": "string",
- "schedulerName": "string",
- "terminationGracePeriodSeconds": 0,
- "automountServiceAccountToken": true,
- "restartPolicy": "string",
- "dnsPolicy": "string"
}, - "server_start_wait_timeout_in_seconds": 300,
- "reuse_strategy": "NONE",
- "server_kind": "idegym",
- "snapshot": {
- "id": "string",
- "tag": "string"
}, - "max_restarts": 0
}null| client_id required | string <uuid> (Client Id) UUID of the client that owns the server |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace containing the server |
| server_id required | integer (Server Id) Numeric IdeGYM server ID |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym",
- "server_id": 0
}nullList the servers a client owns, so a leaked pod can be found without kubectl.
Terminal servers are excluded unless asked for, since the common question is "what is still mine and running".
| client_id required | string <uuid> (Client Id) |
| include_terminal | boolean (Include Terminal) Default: false |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "servers": [
- {
- "server_id": 0,
- "server_name": "string",
- "generated_name": "string",
- "namespace": "string",
- "availability": "string",
- "usable": true,
- "image_tag": "string",
- "created_at": 0,
- "last_activity_at": 0,
- "keepalive_until": 0,
- "details": "string"
}
]
}| client_id required | string <uuid> (Client Id) UUID of the client that owns the server |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace containing the server |
| server_id required | integer (Server Id) Numeric IdeGYM server ID |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym",
- "server_id": 0
}nullHold a server against the watcher's inactivity reaper for the requested window.
The reaper works off the last time a request finished, which is a poor proxy for "somebody is using this": a sandbox can be legitimately idle while an agent thinks or a build runs. Only the holder knows, so this is how it says so.
| client_id required | string <uuid> (Client Id) UUID of the client that owns the server |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace containing the server |
| server_id required | integer (Server Id) Numeric IdeGYM server ID |
| minutes | number (Minutes) ( 0 .. 1440 ] Default: 15 How long from now to hold the server, in minutes. Calling again extends the window; it is never shortened, so two holders cannot cut each other short. |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym",
- "server_id": 0,
- "minutes": 15
}{- "server_id": 0,
- "keepalive_until": 0,
- "minutes": 0
}Report whether a server is usable, without touching it.
It does not update the server's activity timestamp, so polling cannot keep a server from being reaped. The database record is the answer and the pod view is best effort: Kubernetes is not asked about a terminal server, and a Kubernetes failure leaves the pod fields null rather than hiding the recorded status behind a 500.
| server_id required | integer (Server Id) |
| client_id required | string <uuid> (Client Id) |
{- "server_id": 0,
- "server_name": "string",
- "generated_name": "string",
- "namespace": "string",
- "availability": "string",
- "usable": true,
- "image_tag": "string",
- "created_at": 0,
- "last_activity_at": 0,
- "keepalive_until": 0,
- "details": "string",
- "idle_seconds": 0,
- "pod_phase": "string",
- "pod_ready": true
}| client_id required | string <uuid> (Client Id) UUID of the client that owns the server |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace containing the server |
| server_id required | integer (Server Id) Numeric IdeGYM server ID |
| server_start_wait_timeout_in_seconds | integer (Server Start Wait Timeout In Seconds) >= 0 Default: 300 Seconds to wait for server readiness after restart |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym",
- "server_id": 0,
- "server_start_wait_timeout_in_seconds": 300
}nullBuild Docker images from a YAML file using the configured build backend.
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace for the image build jobs |
| yaml_content required | string (Yaml Content) YAML content containing image build job definitions |
{- "namespace": "idegym",
- "yaml_content": "string"
}null| client_id required | string <uuid> (Client Id) UUID of the client that owns the server being snapshotted |
| server_id required | integer (Server Id) Numeric IdeGYM server ID that should be snapshotted |
| namespace | string (Namespace) Default: "idegym" Kubernetes namespace the server runs in |
{- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "server_id": 0,
- "namespace": "idegym"
}nullAccept a batch of start-server requests, prepare a snapshot for each independently.
required | Array of objects (Requests) List of start server requests to prepare snapshots for | ||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||
{- "requests": [
- {
- "client_id": "5b3fa7ba-57d3-4017-a65b-d57dcd2db643",
- "namespace": "idegym",
- "image_tag": "registry.example.com/my-env:latest",
- "server_name": "my-server",
- "runtime_class_name": "gvisor",
- "run_as_root": false,
- "service_port": 80,
- "container_port": 8000,
- "resources": {
- "limits": {
- "cpu": "1",
- "memory": "1Gi"
}, - "requests": {
- "cpu": "500m",
- "memory": "512Mi"
}
}, - "node_selector": {
- "kubernetes.io/os": "linux"
}, - "labels": {
- "job": "swe-bench-run-42",
- "team": "research"
}, - "volumes": [
- {
- "name": "agent-creds",
- "secret": {
- "secretName": "agent-creds"
}
}
], - "volume_mounts": [
- {
- "mountPath": "/etc/creds",
- "name": "agent-creds",
- "readOnly": true
}
], - "env_from": [
- {
- "secretRef": {
- "name": "agent-creds"
}
}
], - "service_account_name": "agent-runner",
- "pod_overrides": {
- "tolerations": [
- {
- "key": "string",
- "operator": "string",
- "value": "string",
- "effect": "string",
- "tolerationSeconds": 0
}
], - "hostAliases": [
- {
- "ip": "string",
- "hostnames": [
- "string"
]
}
], - "nodeSelector": { },
- "runtimeClassName": "string",
- "priorityClassName": "string",
- "schedulerName": "string",
- "terminationGracePeriodSeconds": 0,
- "automountServiceAccountToken": true,
- "restartPolicy": "string",
- "dnsPolicy": "string"
}, - "server_start_wait_timeout_in_seconds": 300,
- "reuse_strategy": "NONE",
- "server_kind": "idegym",
- "snapshot": {
- "id": "string",
- "tag": "string"
}, - "max_restarts": 0
}
]
}nullCheck whether a snapshot exists for the given server configuration.
| namespace | string (Namespace) Default: "idegym" |
| image_tag required | string (Image Tag) [ 1 .. 383 ] characters ^[a-z0-9._/:@-]+$ |
| server_name | string (Server Name) [ 1 .. 63 ] characters ^[a-z]([-a-z0-9]*[a-z0-9])?$ Default: "default-idegym-server" |
Runtime Class Name (string) or Runtime Class Name (null) (Runtime Class Name) | |
| run_as_root | boolean (Run As Root) Default: false |
| server_kind | string (ServerKind) Default: "idegym" Enum: "idegym" "openenv" |
null