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

> Install and operate Cyberun agents on Linux, macOS, and Windows hosts.

A **Cyberun agent** is the process that runs on a GPU host and
executes the team's workflows. Each install pairs one host with one
runtime — ComfyUI by default; add others (such as Nerfstudio) where
the runtime supports the host. To run more than one runtime on the
same host, install once per runtime; each install lives in its own
directory and registers its own service.

This page covers the headless agent: a long-running install on a
worker host.

## Before you install

* A Cyberun team and an **agent credential** (`ak-...`) for that
  team. Create one from **Access → Agent** in
  [Cyberun Cloud](https://app.cyberun.cloud).
* A GPU suited to the runtimes you'll run, plus disk for their
  model caches. The agent runs on Linux, macOS, and Windows; a
  runtime's availability is set by that runtime, not by the agent.
  Nerfstudio, for example, needs Linux + NVIDIA, while ComfyUI also
  runs on macOS (Apple GPU via Metal) and Windows.
* Outbound network access from the host to your Cyberun gateway.
  Agents do not need an inbound listener.

## Linux and macOS

```bash theme={null}
# Native mode (default): a rootless per-user install. comfyui is the
# default tool, so no --tool is needed; the installer sets up ComfyUI
# in a Python virtual environment and installs ComfyUI-Manager.
curl -sL https://releases.cyberun.cloud/agent/install.sh | bash -s -- \
    --api-key ak-...

# Nerfstudio (Linux + NVIDIA only) — the one case that needs --tool.
curl -sL https://releases.cyberun.cloud/agent/install.sh | bash -s -- \
    --tool nerfstudio --api-key ak-...

# Docker mode: run ComfyUI in a container instead of natively. Docker
# needs a root systemd unit, so this implies --system — run with sudo.
curl -sL https://releases.cyberun.cloud/agent/install.sh | sudo bash -s -- \
    --api-key ak-... --docker

# Uninstall. Add --purge to also wipe the ComfyUI checkout, the
# virtual environment, and any downloaded models.
curl -sL https://releases.cyberun.cloud/agent/uninstall.sh | bash -s -- --purge
```

The default install is rootless — no `sudo`. The shared `agent`
binary lands in `~/.cyberun/bin`, each tool's runtime in
`~/.cyberun/agent/<tool>`, and the agent runs under a per-user
service: user systemd on Linux, a launchd user agent on macOS. You
only need `sudo` for `--system` or `--docker`, or to let the
installer pull system prerequisites (NVIDIA driver, missing apt
packages). On Linux, run `sudo loginctl enable-linger <user>` so the
per-user agent keeps running after logout and starts at boot.

Omit `--api-key` and the installer prompts for the credential
interactively (hidden input). Passing the credential on the
command line is best reserved for automation that already keeps
it in a secret manager.

## Windows (PowerShell)

```powershell theme={null}
# Native mode (default) — per-user, no Administrator needed.
& ([scriptblock]::Create((irm https://releases.cyberun.cloud/agent/install.ps1))) -ApiKey ak-...

# Docker mode (Docker Desktop with WSL2 required):
& ([scriptblock]::Create((irm https://releases.cyberun.cloud/agent/install.ps1))) -ApiKey ak-... -Docker

# Uninstall:
& ([scriptblock]::Create((irm https://releases.cyberun.cloud/agent/uninstall.ps1))) -Purge
```

The Windows install is per-user — no Administrator needed. The
binary lands in `%USERPROFILE%\.cyberun\bin` and runs under a
per-user Scheduled Task that starts at logon. comfyui is the only
Windows runtime and the default, so `-Tool` can be omitted.

## Install flags

| `install.sh`                     | `install.ps1`     | Default             | Purpose                                                                               |
| -------------------------------- | ----------------- | ------------------- | ------------------------------------------------------------------------------------- |
| `--tool comfyui` \| `nerfstudio` | `-Tool comfyui`   | `comfyui`           | Which tool runtime to install. Nerfstudio is Linux + NVIDIA only.                     |
| `--api-key ak-...`               | `-ApiKey ak-...`  | prompted if missing | The agent credential the agent uses to connect.                                       |
| `--system`                       | —                 | off (rootless)      | Install system-wide to `/opt/cyberun` with a root systemd unit (Linux); needs `sudo`. |
| `--docker`                       | `-Docker`         | off                 | Run ComfyUI in Docker rather than natively. Implies `--system`, so it needs `sudo`.   |
| `--image <ref>`                  | `-Image <ref>`    | (with `--docker`)   | Override the Docker image. Defaults to the standard published image.                  |
| `--no-install`                   | `-NoInstall`      | off                 | Skip ComfyUI / virtual-env / PyTorch setup (bring-your-own ComfyUI at the path).      |
| `--no-manager`                   | `-NoManager`      | off                 | Skip cloning ComfyUI-Manager into `custom_nodes/`.                                    |
| `--gpu-indices 0,1`              | `-GpuIndices 0,1` | all visible GPUs    | Pin the agent to specific CUDA device indices.                                        |
| `--nerfstudio-version v1.1.5`    | —                 | `v1.1.5`            | Pin the Nerfstudio version (Linux only).                                              |

To point the agent at a non-default gateway, set
`CYBERUN_WSS_URL=wss://...` in the install environment (Linux,
macOS) or pass `-GatewayUrl wss://...` (Windows).

## Uninstall flags

| `uninstall.sh`                   | `uninstall.ps1` | Purpose                                                                               |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
| `--tool comfyui` \| `nerfstudio` | `-Tool comfyui` | Which tool agent to remove. Defaults to `comfyui`.                                    |
| `--system`                       | —               | Remove a legacy system-wide install under `/opt/cyberun` (needs `sudo`).              |
| `--purge`                        | `-Purge`        | Also wipe the ComfyUI checkout, the virtual environment, models, and the install dir. |

## Where the agent lives

The default rootless install lays out like this:

|                 | Linux                                       | macOS                                | Windows                              |
| --------------- | ------------------------------------------- | ------------------------------------ | ------------------------------------ |
| Binary (shared) | `~/.cyberun/bin/agent`                      | `~/.cyberun/bin/agent`               | `~\.cyberun\bin\agent.exe`           |
| Install dir     | `~/.cyberun/agent/<tool>/`                  | (same)                               | `~\.cyberun\agent\<tool>\`           |
| ComfyUI         | `<dir>/comfyui/`                            | (same)                               | `<dir>\comfyui\`                     |
| Service         | user systemd `cyberun-agent-<tool>`         | launchd `cloud.cyberun.agent.<tool>` | Scheduled Task `CyberunAgent-<Tool>` |
| Logs            | `journalctl --user -u cyberun-agent-<tool>` | `<install_dir>/agent.log`            | `<install_dir>\cyberun-agent.log`    |

A `--system` install on Linux lives under `/opt/cyberun` instead,
with a root systemd unit you read via
`journalctl -u cyberun-agent-<tool>`.

One install = one tool runtime = one agent process. The shared
`agent` binary is reused; each tool gets its own
`~/.cyberun/agent/<tool>` directory and its own service. To run
ComfyUI and Nerfstudio on the same Linux box, run the installer
once per tool.

## After install

Once the service starts, the agent dials the gateway, presents its
agent credential, and reports its labels and capabilities. The
team's Cyberun Cloud dashboard shows the agent under **Agents**
within a few seconds. From there, tasks the agent is eligible for
can be dispatched to it. The eligibility model is covered in
[Cloud → Agents](/cloud/concepts/agents).

## Updating the agent

Re-run the installer for the same tool. It drops in the new binary
and re-applies the service definition; settings and model caches are
preserved. On macOS the launchd agent reloads immediately; on Linux
restart the service to pick up the new binary — `systemctl --user
restart cyberun-agent-<tool>` (or `systemctl restart` for a
`--system` install).

## Removing the agent

Run the uninstall command shown above. Without `--purge`, the
ComfyUI checkout and models stay on disk in case you reinstall
later; with `--purge`, everything under the install directory is
removed.