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

# Connect an agent

> Install the Cyberun agent on a GPU machine so the team can dispatch tasks to it.

A **Cyberun agent** is the process that connects your GPU machine
to the platform. This page is the install-and-connect walkthrough.
For the conceptual model see [Agents](/cloud/concepts/agents).

## Before you start

* A team you belong to. Any member can create an agent key.
* A machine with a usable GPU, on Linux, macOS, or Windows. The
  agent runs on all three; each runtime sets its own platform and
  hardware support — see [Platform → Agents](/platform/agents).
* Outbound network access from the GPU machine to Cyberun. No
  inbound ports required.

## 1. Create the agent credential

1. In Cloud, open **Access** in the sidebar.
2. Switch to the **Agent** tab.
3. Click **Create agent key**.
4. Name it after the machine (`home-rtx-4090`, `studio-mac-mini`,
   `cloud-h100-a`).
5. Click **Create**.
6. **Copy the `ak-…` value shown.** It's displayed once.

## 2. Install the agent

The agent ships with a per-platform installer that handles the
download, the ComfyUI setup, and the service registration. Run the
one-liner for your OS:

**Linux & macOS:**

```sh theme={null}
curl -sL https://releases.cyberun.cloud/agent/install.sh | bash -s -- \
    --api-key ak-…
```

**Windows (PowerShell):**

```powershell theme={null}
& ([scriptblock]::Create((irm https://releases.cyberun.cloud/agent/install.ps1))) -ApiKey ak-…
```

<Note>
  The agent runs on every supported OS; each runtime sets its own
  requirements. See [Platform → Agents](/platform/agents) for the
  per-runtime support details.
</Note>

That sets up ComfyUI in a Python virtual environment, registers the
agent as a per-user service, and starts it — no `sudo`, with comfyui
as the default tool. The agent connects to Cyberun and within a few
seconds appears in **Agents** in Cloud as **idle**.

For the full list of installer flags (Docker mode, specific GPU
indices, custom image, …) see
[Platform → Agents](/platform/agents).

## 3. Verify

Submit a small task targeting this agent's labels. See
[Run your first task](/cloud/getting-started/first-task) for the
walkthrough.

## Troubleshooting

**`401 unauthorized`** — the agent key is wrong, revoked, or
expired. Check **Access → Agent** in Cloud and reissue.

**`connection refused`** — your network can't reach the gateway.
Test it with `curl -v https://gateway.cyberun.cloud/ws`: a reachable
gateway returns `401 Unauthorized` with a JSON body like
`{"error_message":"missing api key"}` — that means the host is up
and the gateway responded, just that `curl` didn't authenticate.
A timeout, DNS error, or TLS failure means the host is unreachable
— most often a firewall on the GPU machine's network blocking
outbound WSS.

**Agent stays on `syncing` forever** — the agent is downloading
models or node packages on its first run. Look at the agent's
local logs (`journalctl --user -u cyberun-agent-comfyui` on Linux); it's
usually network bandwidth. Subsequent connects skip already-cached
artifacts.

**Tasks queue but never dispatch** — the workflow's required
labels don't match the agent's. Compare them in the workflow
detail page and the agent's row in **Agents**.

## Related

* [Agents](/cloud/concepts/agents) — concept and lifecycle.
* [Credentials](/cloud/concepts/credentials) — the agent-key
  family.
* [Platform → Agents](/platform/agents) — install reference for
  operators (system services, log locations, all flags).
* [Cyberun CLI](/cloud/guides/cli) — `cyberun agent serve` runs a
  lightweight foreground agent tied to your logged-in session, versus
  the standalone installer on this page that registers a long-running
  system service.