> ## Documentation Index > Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt > Use this file to discover all available pages before exploring further. # List connected agents (runtime) > Returns agents currently registered for this team via WebSocket. Identical to the management endpoint but also accepts the runtime credential bearers. Data is read from the the platform's runtime state (the cache), not from a database. Supports pagination. Accepts JWT Bearer, `sk-` integration credential, or `dk-` device credential. ## OpenAPI ````yaml /api-reference/core-openapi.yaml get /r/agents openapi: 3.0.3 info: title: Cyberun API version: 1.0.0 description: > Multi-tenant GPU orchestration platform for enterprise private deployments. ## Authentication Two authentication families are supported: - **JWT Bearer** (`Authorization: Bearer `) — Used by team owners/admins/members for management endpoints and user sessions. JWT-authenticated requests that operate on a team **must** include the `X-Team-ID` header to select which team the request applies to (a user can belong to multiple teams). - **Credential Bearer** (`Authorization: Bearer `) — Unified machine credential. The credential is always scoped to a single team derived from the credential row, and any `X-Team-ID` header is **ignored**. The three kinds differ in identity and routing: | Kind | Prefix | Identity | Allowed surfaces | | ------------- | ------ | ------------------------- | --- | | `integration` | `sk-` | Team only | Runtime API (`/r/`) + the Web MCP endpoint. Rejected on every management endpoint because the authorization layer needs a user identity and `sk-` has none. | | `agent` | `ak-` | Team only | the platform's WebSocket handshake **only** — rejected by the REST surface at the middleware layer. | | `device` | `dk-` | Team + user (per-device) | Runtime API and scoped management endpoints — behaves like a JWT for the underlying user. Issued by the desktop pairing flow only (`POST /desktop/pair/confirm`). | the authorization layer runs against the user identity carried by JWT and `dk-`. `sk-` and `ak-` bypass the authorization layer; service-layer checks enforce team scope for them. Runtime endpoints under `/r/` accept **JWT (with `X-Team-ID`)**, `sk-`, and `dk-`. `ak-` is rejected at the middleware (it is only meaningful on the the platform's WebSocket handshake). Scoped management endpoints accept **JWT (with `X-Team-ID`)** or `dk-`; `sk-` is rejected on management because the the authorization layer authorize layer requires a user identity. The Web MCP endpoint accepts `sk-` only. Multipart upload endpoints (`/uploads/multipart/*`) remain JWT-only. Credential-bearing callers (`sk-`, `dk-`) should use single-part presign (`POST /r/files/presign`) instead — that returns a vanilla S3 PUT URL (≤ 5 GB by S3, subject to the server's configured request cap; default 500 MB). Files beyond the cap currently require the JWT-only multipart flow. ## Task Lifecycle Tasks follow this state machine: `pending → waiting → queued → running → completed | failed | cancelled`. Submit tasks via workflow run endpoints, poll status via GET /r/tasks/{taskId}, and retrieve results via GET /r/tasks/{taskId}/result. ## Pagination All list endpoints support pagination via `current_page` (default: 1) and `per_page` (default: 20, max: 100) query parameters. Responses include a `page_meta` object with `current_page`, `per_page`, and `total_count`. servers: - url: https://core.cyberun.cloud/api/v1 description: Cyberun Cloud API security: [] tags: - name: Auth description: > Authentication and account lifecycle: register, login, logout, token refresh, password reset, and email verification. - name: User description: | Current user profile management: view and update profile, change password. - name: Team description: > Team management: create, update, delete teams, leave, and transfer ownership. Each user gets a personal team on registration. - name: Member description: | Team member management: list members, update roles, and remove members. - name: Invitation description: > Team invitation management: invite users by email, accept/decline invitations, list pending invitations, and cancel invitations. - name: Credential description: | Unified credential management: integration keys (`sk-`) for programmatic API access, agent keys (`ak-`) for headless workers, and device keys (`dk-`) for paired desktop installs. All three share storage and revocation flow; the `kind` field selects behaviour. - name: DevicePair description: > Desktop device pairing flow. Three endpoints — start (anonymous), confirm (JWT, called from the Cyberun dashboard), poll (anonymous, called from desktop) — exchange a short user-visible code for a `dk-` credential without the user ever typing the secret. - name: Workflow description: > ComfyUI workflow template management: create, update, delete, and list workflow templates with configurable parameters, labels, timeout, and retry settings. - name: Task description: | Task execution and monitoring: submit workflow runs, poll task status, retrieve results, and cancel tasks. Tasks follow the lifecycle: `pending → waiting → queued → running → completed | failed | cancelled`. - name: Webhook description: > Webhook management: register HTTPS endpoints to receive event notifications (task.completed, task.failed) with HMAC-SHA256 signed payloads. - name: Container description: > Container service orchestration: deploy arbitrary Docker containers (vLLM, Ollama, custom services) to agents, manage lifecycle, and proxy HTTP requests through the gateway with load balancing. - name: CloudProvider description: > Cloud compute provider management: configure third-party cloud GPU provider API keys (e.g. ComfyUI Cloud) for teams without local GPU agents, and manage automatic cloud fallback settings. - name: Notifications description: | In-app notification center: list, read, and manage notifications for status changes and system alerts. - name: Agent description: > Agent monitoring: view connected agents for a team, including their status, labels, and current task. Data is read from the the platform's runtime state. - name: Node description: | Custom node management: upload, register, update, and delete ComfyUI custom node packages (zip archives) for team-scoped agents. - name: Model description: | Model management: upload, register, update, and delete AI model files (checkpoints, LoRAs, etc.) for team-scoped agents. - name: File description: > File upload for workflow inputs: request presigned upload URLs to stage files (images, videos, audio) in S3, then reference them as `type: file` parameters when running workflows. - name: Upload description: > Multipart upload support for large files: initiate, presign parts, complete, and abort multipart uploads. Used alongside domain-specific presign endpoints for files exceeding ~100 MB. - name: Server description: | Public server information: registration status and other configuration visible to unauthenticated clients. paths: /r/agents: get: tags: - Agent summary: List connected agents (runtime) description: > Returns agents currently registered for this team via WebSocket. Identical to the management endpoint but also accepts the runtime credential bearers. Data is read from the the platform's runtime state (the cache), not from a database. Supports pagination. Accepts JWT Bearer, `sk-` integration credential, or `dk-` device credential. operationId: listAgentsRuntime parameters: - $ref: '#/components/parameters/TeamIdHeaderOptional' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: '200': description: Agent list content: application/json: schema: $ref: '#/components/schemas/AgentListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' security: - bearerAuth: [] - DeviceAuth: [] - ApiKeyAuth: [] components: parameters: TeamIdHeaderOptional: name: X-Team-ID in: header required: false description: | UUID of the team to scope the request to. Used by dual-auth endpoints (runtime + scoped management): - **JWT callers** MUST send it — a user may belong to multiple teams and the runtime cannot otherwise know which one to operate on. Missing header → 400. - **Credential callers** (`sk-`, `dk-`) can omit it because the team is derived from the credential row itself. Any value sent is ignored. schema: type: string format: uuid example: 019abc12-4567-7890-abcd-ef1234567891 Page: name: current_page in: query required: false description: 'Page number to retrieve (1-based). Default: 1.' schema: type: integer minimum: 1 default: 1 example: 1 PerPage: name: per_page in: query required: false description: 'Number of items per page (1–100). Default: 20.' schema: type: integer minimum: 1 maximum: 100 default: 20 example: 20 schemas: AgentListResponse: type: object required: - agent_list - page_meta properties: agent_list: type: array description: Agents registered for this team in the current page. items: $ref: '#/components/schemas/AgentItem' page_meta: $ref: '#/components/schemas/PaginationMeta' AgentItem: type: object description: > An agent connected to the platform via WebSocket. Agents execute ComfyUI workflows on behalf of a team. Status and metadata are read from the the platform's runtime state. required: - agent_id - agent_status - agent_labels - last_heartbeat properties: agent_id: type: string description: Unique identifier of the agent (set by the agent on registration). example: gpu-node-01 agent_status: type: string enum: - idle - busy - syncing - tunnel - unhealthy description: > Current agent state: - `idle`: Available to accept new tasks (running_count = 0). - `busy`: Currently executing one or more tasks (running_count > 0). For multi-GPU agents, a `busy` agent may still have available capacity. - `syncing`: Downloading models or updating software — will not accept tasks until complete. - `tunnel`: ComfyUI web tunnel is active — will not accept tasks until tunnel is closed. - `unhealthy`: ComfyUI health check failed — agent will not receive tasks until recovered. example: idle agent_version: type: string description: >- Agent binary version reported via heartbeat (e.g. "0.1.3"). May be empty if the agent has not sent a heartbeat yet. example: 0.1.3 tool: type: string enum: - comfyui - nerfstudio description: > Tool runtime this agent serves. One agent process serves one tool family; multi-tool deployments run multiple agent processes. example: comfyui tool_version: type: string description: > Version of the served tool runtime, reported via heartbeat. Empty until the runtime's first healthcheck completes (or the runtime opts out of version reporting). example: 0.3.13 comfyui_version: type: string deprecated: true description: > Deprecated alias of `tool_version` for ComfyUI agents. Populated only when `tool == "comfyui"`. New clients should read `tool_version`. Removed in a future major version. example: 0.3.13 agent_labels: type: array items: type: string description: > Capability labels declared by the agent at registration. Used for task routing — workflows with `required_labels` will only be dispatched to agents whose labels are a superset of the requirement. example: - gpu - a100 - comfyui gpu_capacity: type: integer description: > Total number of GPU slots this agent can run concurrently. Defaults to 1 for single-GPU or legacy agents. Multi-GPU agents report their actual GPU count. example: 8 running_count: type: integer description: > Number of tasks currently running on this agent. For multi-GPU agents, this can be less than `gpu_capacity`, meaning the agent still has available slots. example: 3 running_tasks: type: array items: type: string description: > IDs of all tasks currently being executed. Empty array if idle. Replaces the legacy `current_task_id` for multi-GPU agents. example: - 019abc12-9012-7890-abcd-ef1234567896 - 019abc12-9012-7890-abcd-ef1234567897 platform_arch: type: string description: > Operating system and architecture of the agent host (e.g. "linux/amd64", "darwin/arm64"). Reported at registration time. example: linux/amd64 sync_phase: type: string description: | Current synchronization phase when agent_status is `syncing`. Possible values: "downloading", "installing", "completed", "failed". Empty string when not syncing. example: downloading sync_detail: type: string description: > Human-readable detail about the current sync operation (e.g. model name being downloaded). Empty string when not syncing. example: Downloading model flux1-dev-fp8 (2.1 GB) sync_percent: type: integer description: > Sync progress percentage (0–100). Only meaningful when agent_status is `syncing`. example: 45 connected_at: type: string format: date-time description: > Timestamp when the agent established its current WebSocket connection to the gateway. Resets on reconnection. example: '2025-02-10T14:00:00Z' tasks_completed: type: integer description: > Total number of tasks completed by this agent since it connected. Resets on reconnection. Useful for monitoring agent productivity. example: 42 current_task_id: type: string description: > Legacy field — ID of a task currently being executed. For multi-GPU agents running multiple tasks, use `running_tasks` instead. Empty string if idle. example: 019abc12-9012-7890-abcd-ef1234567896 last_heartbeat: type: string format: date-time description: >- Last heartbeat timestamp from the agent (ISO 8601). Agents that miss heartbeats are automatically unregistered. example: '2025-02-10T14:30:00Z' system_stats: $ref: '#/components/schemas/AgentSystemStats' PaginationMeta: type: object description: Pagination metadata included in all list responses. required: - current_page - per_page - total_count properties: current_page: type: integer description: The 1-based page number being returned. example: 1 per_page: type: integer description: Number of items per page. example: 20 total_count: type: integer description: Total number of matching items across all pages. example: 42 ErrorResponse: type: object required: - error_message properties: error_message: type: string description: Human-readable error message describing what went wrong. example: resource not found AgentSystemStats: type: object description: > Host and GPU information reported by the agent from ComfyUI's /system_stats endpoint. Updated every few heartbeats. May be null if the agent hasn't reported stats yet. properties: comfyui_version: type: string description: ComfyUI server version. example: 0.3.10 pytorch_version: type: string description: PyTorch version used by ComfyUI. example: 2.5.1+cu124 os_type: type: string description: Operating system type (e.g. "posix", "nt"). example: posix gpu_devices: type: array description: GPU devices available on the agent host. items: $ref: '#/components/schemas/GPUDeviceInfo' GPUDeviceInfo: type: object description: GPU device information from ComfyUI runtime. required: - device_name - device_type - vram_total - vram_free properties: device_name: type: string description: GPU model name. example: NVIDIA GeForce RTX 4090 device_type: type: string description: Device type (cuda, mps, cpu). example: cuda vram_total: type: integer format: int64 description: Total VRAM in bytes. example: 25769803776 vram_free: type: integer format: int64 description: Free VRAM in bytes. example: 22548578304 responses: BadRequest: description: >- Invalid request: missing required fields, validation failure, or malformed input. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: 'Authentication failed: missing, expired, or invalid JWT/API key.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- Insufficient permissions: the authenticated user does not have the required role or the authorization layer policy. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: | User session JWT (Bearer ). Must be paired with the `X-Team-ID` request header on team-scoped endpoints so the server knows which team's resources to operate on. DeviceAuth: type: http scheme: bearer description: > Device credential (Bearer dk-...) issued by the client device-pair flow (`POST /desktop/pair/confirm`). Carries the confirming user's identity, so it behaves like the user's JWT on team-scoped endpoints — the authorization layer runs against the user. Accepted on runtime + management endpoints. Never accepted on the platform's WebSocket. Team scope is bound at pair time; `X-Team-ID` is ignored. ApiKeyAuth: type: http scheme: bearer description: > Integration credential (Bearer sk-...). Team-scoped, no user identity, bypasses the authorization layer. Full runtime access on `/r/*` (including container invoke and proxy) and the Web MCP endpoint. **Not accepted on management endpoints** — those need a user-bearing credential (JWT or `DeviceAuth`). Team scope is taken from the credential; `X-Team-ID` is ignored. ````