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

# Agents

> Agents that connect out to the Cyberun gateway and execute tasks for your team.

A **Cyberun agent** is a process you run on a machine with a GPU.
The agent maintains an outbound connection to the Cyberun gateway,
identifies itself with an agent credential (`ak-...`), and waits to
be dispatched a task. Your machine never accepts inbound
connections.

You bring the hardware. Cloud schedules the work.

## How an agent connects

The agent dials out to Cyberun and holds the connection open. Your
machine never accepts inbound connections — you don't need to open
a port or change a firewall. As long as the GPU machine has
ordinary outbound internet access, it can join the team.

## Status

In the **Agents** sidebar page, each agent shows one of:

| Status        | Meaning                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------- |
| **idle**      | Connected, no task running. Ready to dispatch.                                                |
| **busy**      | Running a task. Other tasks queued behind it.                                                 |
| **syncing**   | Pulling models or node packages on first run; not yet eligible.                               |
| **tunnel**    | A ComfyUI web tunnel is open for interactive use. Won't accept tasks until the tunnel closes. |
| **unhealthy** | Connected, but its ComfyUI health check failed — it won't receive tasks until it recovers.    |

If the agent disappears from the list entirely, its connection to
the gateway dropped. Check that the agent's system service is still
running on the GPU machine (the installer registers it under a
name like `cyberun-agent-comfyui`). See [Connect an
agent](/cloud/guides/connect-agent) for the per-OS verification
commands.

## Labels

Labels are how workflows pick eligible agents. Common defaults:

* `gpu` — the agent has a usable GPU.
* `comfyui` — the agent runs the ComfyUI runtime.
* `nerfstudio` — the agent runs the Nerfstudio runtime.

Most labels are set automatically. The installer derives them
from the `--tool` you chose and from the detected hardware; the
agent advertises them when it connects. You can add extra labels
in the agent's local config file (under `agent_labels:` in
`cyberun-agent.yaml`) — useful for tagging a specific machine for
priority dispatch, e.g. `team-a`, `gpu-h100`.

A workflow declares the labels it requires. Tasks dispatch only to
agents whose label set is a superset of the workflow's requirements.
A workflow asking for `gpu, comfyui` runs on any agent advertising
at least those two.

Labels are case-sensitive. Don't ship the same logical capability
under two names (`comfyui` vs `comfy`) — pick one across your team.

## Health and resource reporting

The dashboard shows per-agent telemetry on the **Agents** page:

* GPU model and VRAM usage
* Runtime version (for example ComfyUI commit, Nerfstudio version)
* Last heartbeat timestamp
* Current task ID

When the resource is fetched via an integration key (`sk-`)
instead of a signed-in user session, some host-level stats appear
in a reduced form — this is by design, so a leaked key reveals
less about your team's hardware than a user session would. Sign
in through the dashboard if you need the full telemetry.

## Remote agent tools

Some deployments enable a remote-access toolkit on the agent
detail page, with three sub-tabs:

* **Terminal** — interactive shell into the agent host.
* **Files** — browse, upload, download, rename, copy, delete, mkdir.
* **Desktop** — view the agent's screen and send mouse, wheel, and
  keyboard input.

These tabs use short-lived tunnel credentials and are scoped to
the team. Treat them like SSH — only admins should use them, and
only on agents you trust. If the tabs aren't there, this
deployment doesn't include remote access. Contact your team admin
if you need it.

## Related

* [Connect an agent](/cloud/guides/connect-agent) — installation
  walkthrough.
* [Credentials](/cloud/concepts/credentials) — the `ak-` key family.
* [Workflows](/cloud/concepts/workflows) — how labels gate dispatch.