Agents

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

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

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

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.

Overview

Deployment

Configure

Operate

Before you install

Linux and macOS

Windows (PowerShell)

Install flags

Uninstall flags

Where the agent lives

After install

Updating the agent

Removing the agent

​Before you install

​Linux and macOS

​Windows (PowerShell)

​Install flags

​Uninstall flags

​Where the agent lives

​After install

​Updating the agent

​Removing the agent

Before you install

Linux and macOS

Windows (PowerShell)

Install flags

Uninstall flags

Where the agent lives

After install

Updating the agent

Removing the agent