Cyberun skill - Cyberun

This page is both human-readable docs and an installable agent skill (agentskills.io format). Install with the skills CLI:

npx skills add cyberun-cloud/skills

The CLI writes the skill to the right per-agent directory (~/.claude/skills/cyberun/SKILL.md, .cursor/skills/cyberun/SKILL.md, etc.). Restart the tool to pick it up. To target one agent only, append -a claude-code (or cursor, windsurf, codex, …).

What Cyberun is

Cyberun is a platform for running AI workflows (ComfyUI, Nerfstudio, container services) on GPU agents a team controls. The dashboard is Cyberun Cloud at https://app.cyberun.cloud. This skill drives Cyberun exclusively through the Cloud MCP server at https://core.cyberun.cloud/api/v1/mcp (Streamable HTTP, Bearer sk-… integration credential). Every operation below assumes the MCP tools are registered in your current session. If they aren’t, see First-time setup before going further. There is no curl / REST fallback in this skill.

First-time setup (no Cyberun MCP tools in your session?)

If list_workflows, run_workflow_by_slug, get_task_result, etc. are not in your tool registry, the MCP server isn’t configured yet. This is a one-time user-side step. You can not do it yourself, because MCP servers are loaded at session start — adding one mid-session has no effect until restart. Tell the user, then wait for them to restart:

Sign in at https://app.cyberun.cloud → Access → Integration → Create integration key. The sk-… value is shown once; store it in a secret manager.
Set it in their shell environment:
```
export CYBERUN_API_KEY=sk-…
```
Run the per-client setup command from Connect MCP below. Pick the row matching the AI client they’re running you in.
Restart the AI session.

Identifying your AI client. Check which command-line tool is on the user’s PATH (claude, codex, …), or the directory the SKILL.md was loaded from (~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/, .cursor/skills/, …). Match that to a row in Connect MCP below. Do not fall back to any other transport in this session. No curl, no direct REST calls. If the user cannot complete the setup, refer them to https://docs.cyberun.cloud/api-reference (the human-readable REST docs) and stop. Don’t try to do it for them via shell.

Authentication

Every MCP tool call carries Authorization: Bearer sk-…. The header is set automatically once the MCP server is configured with the user’s CYBERUN_API_KEY. The team scope is bound to the credential at issue time — X-Team-ID is neither needed nor accepted on sk-… calls. If a tool call returns isError: true with a 401 code, the credential is dead. Don’t retry. Ask the user for a fresh key.

Connect MCP

Pick the row that matches the AI client you’re running in. After the user runs the snippet, they must restart their AI client before the Cyberun MCP tools become available.

Claude Code (CLI)

claude mcp add --transport http cyberun \
  https://core.cyberun.cloud/api/v1/mcp \
  --header "Authorization: Bearer $CYBERUN_API_KEY"

Claude Code / Claude Desktop (config file)

{
  "mcpServers": {
    "cyberun": {
      "url": "https://core.cyberun.cloud/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${CYBERUN_API_KEY}" }
    }
  }
}

Cursor (`.cursor/mcp.json`)

Same shape as the Claude Desktop config above.

VS Code 1.101+ (`.vscode/mcp.json`)

{
  "servers": {
    "cyberun": {
      "type": "http",
      "url": "https://core.cyberun.cloud/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${CYBERUN_API_KEY}" }
    }
  }
}

Codex CLI (one-shot)

codex mcp add cyberun \
  --url https://core.cyberun.cloud/api/v1/mcp \
  --bearer-token-env-var CYBERUN_API_KEY

Or hand-edit ~/.codex/config.toml:

[mcp_servers.cyberun]
url = "https://core.cyberun.cloud/api/v1/mcp"
bearer_token_env_var = "CYBERUN_API_KEY"

Windsurf (stdio shim, for clients without native Streamable HTTP)

{
  "mcpServers": {
    "cyberun": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://core.cyberun.cloud/api/v1/mcp",
               "--header", "Authorization: Bearer ${CYBERUN_API_KEY}"]
    }
  }
}

MCP tools

Once configured, these tools appear in your registry under the cyberun server (no per-tool prefix on Cloud MCP):

Tool	Inputs	What it does
`list_workflows`	`current_page`, `per_page`	List the team’s workflow templates.
`get_workflow`	`workflow_id`	Fetch a workflow’s full schema (parameters, defaults, ranges).
`get_workflow_by_slug`	`workflow_slug` (`slug` or `slug@version`)	Same as `get_workflow`, by human-readable slug.
`run_workflow`	`workflow_id`, `body` (parameters object)	Submit a workflow. Returns `{task_id}`.
`run_workflow_by_slug`	`workflow_slug`, `body`	Submit by slug instead of UUID.
`list_tasks`	`current_page`, `per_page`, `status`	List recent tasks; optional `status` filter.
`get_task`	`task_id`	Read current task state.
`get_task_result`	`task_id`	Final output (or error) of a finished task.
`cancel_task`	`task_id`	Cancel a non-terminal task. Idempotent.
`stream_task_events`	`task_id`, `timeout_seconds`	Subscribe and wait until terminal. Emits `notifications/progress`.
`list_agents`	`current_page`, `per_page`	The team’s connected agents and their status.
`list_container_services`	(none)	Deployed container services.
`get_container_service`	`service_slug`	URL + status of one container service. Includes `usage_prompt` (free-form description) and `openapi_url` if set.
`call_container_service`	`service_slug`, `method`, `path`, `body_base64?`, `headers?`	Send an HTTP request through the gateway tunnel to a running container service. Body is base64-encoded. Returns `{status_code, headers, body_base64}`.
`presign_file_upload`	`body` (file metadata)	S3 PUT URL for a file a workflow will consume.

Common patterns

Submit a workflow and wait for the result

list_workflows (or get_workflow_by_slug if the user named one) to find the target.
Read the returned parameters array. Note which entries have required: true. Check type, default, min, max, options. If anything required is missing from the user’s request, ask the user before submitting.
run_workflow_by_slug with body: { parameters: { … } }. Returns {task_id}.
stream_task_events with the task_id. The tool returns when the task reaches completed, failed, or cancelled, and emits MCP notifications/progress along the way.
get_task_result to fetch the final output — includes presigned download URLs for any produced files.

Cancel an in-flight task

cancel_task with the task_id. No-op success on already- terminal tasks.

Call a container service

list_container_services — find a service whose service_status is running.
get_container_service with the slug — read usage_prompt (free-form instructions written by the service author, e.g. “POST /api/generate with {model, prompt}”) and openapi_url if set. Do not invent a method/path — ask the user if neither field is populated.
call_container_service with service_slug, method, path, and body_base64 (base64-encoded request body — empty string for GET/DELETE). Returns {status_code, headers, body_base64}; decode the response body before passing it back to the model.

Invoking a service requires the invoke permission on container services. A 403 means the credential’s role is too low (Viewer can list/read but not invoke).

Pick an eligible agent

Optionally call list_agents before submitting. Prefer agents whose status is idle or busy. Agents with status of syncing, tunnel, or unhealthy won’t pick up new tasks.

Task lifecycle

pending → waiting → queued → running → completed | failed | cancelled

stream_task_events returns when a terminal state (completed, failed, cancelled) is reached. Treat the stream’s return value as the authoritative final state.

Do

Read CYBERUN_API_KEY from the environment, never from chat.
Address workflows by slug when the user names them; fall back to UUID otherwise.
Surface MCP isError: true messages verbatim — they come from the platform with intentional wording.
Prefer stream_task_events over polling get_task — lower latency, fewer requests, MCP progress notifications built in.

Don’t

Don’t invent tools — the full set is the table above.
Don’t hard-code an sk-… into source. Always env var or secret manager.
Don’t send X-Team-ID — the credential carries the team.
Don’t retry on 401. The credential is dead; ask the user for a new one.
Don’t fall back to curl / REST in this session. This skill is MCP-only. If MCP isn’t available, see First-time setup.

Reference

Dashboard: https://app.cyberun.cloud
Cloud MCP docs: https://docs.cyberun.cloud/mcp/cloud
Install the skill: npx skills add cyberun-cloud/skills
Underlying REST API (for non-AI-agent callers — CI scripts, shell automation): https://docs.cyberun.cloud/api-reference

Documentation Index

​What Cyberun is

​First-time setup (no Cyberun MCP tools in your session?)

​Authentication

​Connect MCP

​Claude Code (CLI)

​Claude Code / Claude Desktop (config file)

​Cursor (.cursor/mcp.json)

​VS Code 1.101+ (.vscode/mcp.json)

​Codex CLI (one-shot)

​Windsurf (stdio shim, for clients without native Streamable HTTP)

​MCP tools

​Common patterns

​Submit a workflow and wait for the result

​Cancel an in-flight task

​Call a container service

​Pick an eligible agent

​Task lifecycle

​Do

​Don’t

​Reference