---
name: cyberun
description: 'Drive Cyberun Cloud workflows (run tasks, fetch results, manage agents) via the Cloud MCP server at https://core.cyberun.cloud/api/v1/mcp. TRIGGER when the user asks to run, submit, watch, or cancel a Cyberun workflow or task, list Cyberun agents or workflows, or set up MCP access for Cyberun. Authenticate with a Cyberun integration credential (sk- prefix). SKIP if the user is asking about generic ComfyUI, generic NeRF, or another unrelated AI platform.'
license: Proprietary
metadata:
  homepage: "https://docs.cyberun.cloud"
  source: "https://github.com/cyberun-cloud/skills"
---

## 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.

A separate **Desktop MCP** exists on `127.0.0.1` inside the
Cyberun Desktop app (tools prefixed `desktop.`). Use it when
the user has Desktop running locally — same skill applies, just
hit a different MCP endpoint. Full reference:
https://docs.cyberun.cloud/mcp/desktop.

## 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:**

1. Sign in at https://app.cyberun.cloud → **Access** →
   **Integration** → **Create integration key**. The `sk-…`
   value is shown once; store it in a secret manager.
2. Set it in their shell environment:
   ```
   export CYBERUN_API_KEY=sk-…
   ```
3. Run the per-client setup command from **Connect MCP**
   below. Pick the row matching the AI client they're running
   you in.
4. 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)
```bash
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)
```json
{
  "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`)
```json
{
  "servers": {
    "cyberun": {
      "type": "http",
      "url": "https://core.cyberun.cloud/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${CYBERUN_API_KEY}" }
    }
  }
}
```

### Codex CLI (one-shot)
```bash
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`:
```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)
```json
{
  "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. |

Desktop MCP exposes the same workflow operations under the
`desktop.` prefix, plus three local-only tools
(`desktop.list_local_models`, `desktop.gpu_info`,
`desktop.tail_logs`) when Desktop is in Agent or Both mode.

## Common patterns

### Submit a workflow and wait for the result

1. `list_workflows` (or `get_workflow_by_slug` if the user
   named one) to find the target.
2. 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.
3. `run_workflow_by_slug` with
   `body: { parameters: { … } }`. Returns `{task_id}`.
4. `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.
5. `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

1. `list_container_services` — find a service whose
   `service_status` is `running`.
2. `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.
3. `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
- Desktop MCP docs: https://docs.cyberun.cloud/mcp/desktop
- Skill source: https://github.com/cyberun-cloud/skills
- Underlying REST API (for non-AI-agent callers — CI scripts,
  shell automation): https://docs.cyberun.cloud/api-reference