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