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

# 代理

> 在 Linux、macOS 与 Windows 主机上安装并运行 Cyberun 代理。

**Cyberun 代理** 是运行在 GPU 主机上、执行团队工作流的进程。每次安装把一台主机和一个运行时配对 —— 默认是 ComfyUI;在运行时支持该主机的前提下,也可以加入其它运行时(例如 Nerfstudio)。若想在同一主机上运行多个运行时,按运行时各安装一次;每次安装住在自己的目录里,并注册自己的服务。

本页关注无头代理:运行在工作主机上的长期安装。

## 安装之前

* 一个 Cyberun 团队,以及该团队的**代理凭证**(`ak-...`)。从 [Cyberun Cloud](https://app.cyberun.cloud) 的 **访问 → 代理** 创建。
* 一块与你要运行的运行时相匹配的 GPU,以及容纳其模型缓存的磁盘空间。代理可在 Linux、macOS 与 Windows 上运行;某个运行时是否可用由该运行时本身决定,而非由代理决定。例如 Nerfstudio 需要 Linux + NVIDIA,而 ComfyUI 还可在 macOS(通过 Metal 使用 Apple GPU)与 Windows 上运行。
* 主机到你的 Cyberun 网关的出站网络访问权限。代理无需任何入站监听端口。

## Linux 与 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
```

默认安装是无 root 的 —— 无需 `sudo`。共享的 `agent` 二进制文件落在 `~/.cyberun/bin`,每种工具的运行时落在 `~/.cyberun/agent/<tool>`,代理在每用户服务下运行:Linux 上是用户级 systemd,macOS 上是 launchd 用户代理。只有在使用 `--system` 或 `--docker`,或需要让安装器拉取系统先决条件(NVIDIA 驱动、缺失的 apt 包)时,才需要 `sudo`。在 Linux 上,运行 `sudo loginctl enable-linger <user>`,让每用户代理在登出后仍持续运行,并在开机时启动。

省略 `--api-key`,安装器会以交互方式提示输入凭证(隐藏输入)。在命令行上传入凭证适合那些已经把它存在密钥管理器中的自动化场景。

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

Windows 安装是每用户的 —— 无需管理员权限。二进制文件落在 `%USERPROFILE%\.cyberun\bin`,在登录时启动的每用户计划任务下运行。comfyui 是 Windows 上唯一的运行时,也是默认值,所以 `-Tool` 可以省略。

## 安装参数

| `install.sh`                     | `install.ps1`     | 默认值             | 用途                                                         |
| -------------------------------- | ----------------- | --------------- | ---------------------------------------------------------- |
| `--tool comfyui` \| `nerfstudio` | `-Tool comfyui`   | `comfyui`       | 安装哪种工具运行时。Nerfstudio 仅支持 Linux + NVIDIA。                   |
| `--api-key ak-...`               | `-ApiKey ak-...`  | 缺失时提示输入         | 代理用于连接的代理凭证。                                               |
| `--system`                       | —                 | 关闭(默认无 root)    | 系统级安装到 `/opt/cyberun`,使用 root systemd 单元(Linux);需要 `sudo`。 |
| `--docker`                       | `-Docker`         | 关闭              | 在 Docker 中而非本地运行 ComfyUI。隐含 `--system`,因此需要 `sudo`。        |
| `--image <ref>`                  | `-Image <ref>`    | (配合 `--docker`) | 覆盖 Docker 镜像。默认使用已发布的标准镜像。                                 |
| `--no-install`                   | `-NoInstall`      | 关闭              | 跳过 ComfyUI / 虚拟环境 / PyTorch 安装(自带 ComfyUI 到指定路径)。          |
| `--no-manager`                   | `-NoManager`      | 关闭              | 跳过将 ComfyUI-Manager 克隆进 `custom_nodes/`。                   |
| `--gpu-indices 0,1`              | `-GpuIndices 0,1` | 所有可见 GPU        | 把代理绑定到特定的 CUDA 设备索引。                                       |
| `--nerfstudio-version v1.1.5`    | —                 | `v1.1.5`        | 锁定 Nerfstudio 版本(仅 Linux)。                                 |

要把代理指向非默认网关,在安装环境中设置 `CYBERUN_WSS_URL=wss://...`(Linux、macOS)或传入 `-GatewayUrl wss://...`(Windows)。

## 卸载参数

| `uninstall.sh`                   | `uninstall.ps1` | 用途                                      |
| -------------------------------- | --------------- | --------------------------------------- |
| `--tool comfyui` \| `nerfstudio` | `-Tool comfyui` | 要移除哪种工具的代理。默认为 `comfyui`。               |
| `--system`                       | —               | 移除 `/opt/cyberun` 下的旧式系统级安装(需要 `sudo`)。 |
| `--purge`                        | `-Purge`        | 同时清除 ComfyUI 检出、虚拟环境、模型与安装目录。           |

## 代理住在哪里

默认的无 root 安装布局如下:

|         | Linux                                       | macOS                                | Windows                           |
| ------- | ------------------------------------------- | ------------------------------------ | --------------------------------- |
| 二进制(共享) | `~/.cyberun/bin/agent`                      | `~/.cyberun/bin/agent`               | `~\.cyberun\bin\agent.exe`        |
| 安装目录    | `~/.cyberun/agent/<tool>/`                  | (相同)                                 | `~\.cyberun\agent\<tool>\`        |
| ComfyUI | `<dir>/comfyui/`                            | (相同)                                 | `<dir>\comfyui\`                  |
| 服务      | 用户级 systemd `cyberun-agent-<tool>`          | launchd `cloud.cyberun.agent.<tool>` | 计划任务 `CyberunAgent-<Tool>`        |
| 日志      | `journalctl --user -u cyberun-agent-<tool>` | `<install_dir>/agent.log`            | `<install_dir>\cyberun-agent.log` |

`--system` 安装在 Linux 上改为落在 `/opt/cyberun`,使用 root systemd 单元,通过 `journalctl -u cyberun-agent-<tool>` 查看日志。

一次安装 = 一种工具运行时 = 一个代理进程。共享的 `agent` 二进制文件被复用;每种工具都有自己的 `~/.cyberun/agent/<tool>` 目录和自己的服务。若要在同一台 Linux 机器上同时运行 ComfyUI 与 Nerfstudio,按工具各跑一次安装器。

## 安装之后

服务启动后,代理拨号至网关,出示其代理凭证,并上报标签与能力。在数秒之内,团队的 Cyberun Cloud 控制台便会在 **代理** 中看到它。从此处起,该代理符合条件的任务都可派发给它。资格模型见 [Cloud → 代理](/zh/cloud/concepts/agents)。

## 更新代理

对同一工具重新运行安装器。它会换上新的二进制并重新应用服务定义;设置与模型缓存被保留。macOS 上 launchd 代理会立即重新加载;Linux 上需重启服务以加载新二进制 —— `systemctl --user restart cyberun-agent-<tool>`(`--system` 安装则用 `systemctl restart`)。

## 移除代理

运行上面所示的卸载命令。不带 `--purge` 时,ComfyUI 检出与模型保留在磁盘上,以便后续重装时复用;带 `--purge` 时,安装目录下的所有内容都会被移除。