> ## 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. # Open tunnel > Opens a reverse proxy tunnel to a service running on the specified agent. By default, the tunnel connects to ComfyUI (port 8188). Use `target_port` to tunnel to a different service (e.g. Jupyter on 8888, Gradio on 7860). While the tunnel is active, the agent will not accept new tasks. Multiple team members can access the same tunnel simultaneously. Returns a tunnel URL that can be used to access the service's web interface. ## OpenAPI ````yaml /api-reference/core-openapi.yaml post /agents/{agentId}/tunnel 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: /agents/{agentId}/tunnel: post: tags: - Agent summary: Open tunnel description: > Opens a reverse proxy tunnel to a service running on the specified agent. By default, the tunnel connects to ComfyUI (port 8188). Use `target_port` to tunnel to a different service (e.g. Jupyter on 8888, Gradio on 7860). While the tunnel is active, the agent will not accept new tasks. Multiple team members can access the same tunnel simultaneously. Returns a tunnel URL that can be used to access the service's web interface. operationId: openAgentTunnel parameters: - $ref: '#/components/parameters/TeamIdHeaderOptional' - $ref: '#/components/parameters/AgentId' requestBody: content: application/json: schema: $ref: '#/components/schemas/TunnelOpenRequest' responses: '200': description: Tunnel opened content: application/json: schema: $ref: '#/components/schemas/TunnelResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] - DeviceAuth: [] 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 AgentId: name: agentId in: path required: true schema: type: string description: Unique identifier of the agent. example: gpu-node-01 schemas: TunnelOpenRequest: type: object properties: target_port: type: integer minimum: 1 maximum: 65535 description: | Port of the service to tunnel on the agent machine. Defaults to ComfyUI port (8188) when omitted. example: 8188 tunnel_protocol: type: string enum: - http - tcp default: http description: > Protocol of the tunneled service. "http" — HTTP/WebSocket reverse proxy (default, supports ComfyUI, Jupyter, etc.) "tcp" — Raw TCP tunnel (supports SSH, PostgreSQL, MySQL, etc.) example: http TunnelResponse: type: object required: - session_id - tunnel_url - admin_token properties: session_id: type: string description: Unique tunnel session identifier. example: a1b2c3d4e5f6... tunnel_url: type: string description: > For HTTP tunnels: URL to access the tunneled service's web interface. Contains the access token and can be safely shared. For TCP tunnels: WebSocket URL for TCP-over-WS relay. Connect with a TCP client tool. example: https://gateway.example.com/tunnel/a1b2c3d4e5f6.../ admin_token: type: string description: >- Admin token for privileged operations (e.g. WebTerminal). Must be kept secret — do not share. example: f7e8d9c0b1a2... tunnel_protocol: type: string enum: - http - tcp description: Protocol of the tunneled service. example: http ErrorResponse: type: object required: - error_message properties: error_message: type: string description: Human-readable error message describing what went wrong. example: resource not found 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. ````