Install the CloudGrange Relay

The CloudGrange Relay is a container that runs on a host inside your network, one per site. It maintains a persistent outbound connection to the CloudGrange control plane and routes jobs to the agents running on your managed Hyper-V hosts. The relay host needs only outbound access to the control plane — no inbound internet access is required.

CloudGrange is in active development and is not GA. The relay code lives in cloudgrange-runtime-relay. See current product and release status.

One relay per site

Deploy one relay per physical site or network segment — anywhere you have a group of Hyper-V hosts on the same LAN. A single site can hold multiple clusters and any number of hosts; all of them enroll with that site's relay. One CloudGrange instance manages any number of sites, each with its own relay.

Traffic flow

CloudGrange control plane
        │  outbound HTTPS/WSS (443) from relay
        ▼
   Relay host            (container, inside your network)
        │  inbound TCP 8443 from Hyper-V hosts
        ▼
   Hyper-V hosts running the CloudGrange agent

Security note: the relay's agent listener is plain HTTP inside the trusted cluster network; only the agent routes are exposed over TLS on port 8443. Per-agent mTLS is planned but not yet implemented.

Prerequisites

• A Linux or container-capable host with Docker, or a Kubernetes cluster (the on-premises install already includes a relay)
• Outbound HTTPS (443) from the relay host to the control plane
• Inbound TCP 8443 (TLS) from managed Hyper-V hosts to the relay
• For agentless (PSRemoting) inventory: outbound TCP 5986 from the relay to managed Windows hosts
• A persistent volume/directory for the relay identity (RELAY_IDENTITY_DIR)

Deployment model

In every on-premises install the relay ships inside the deployment and is wired up automatically — you do not deploy it separately for the first site. On the Kubernetes/Helm paths it is the cloudgrange-relay Deployment in the chart; on the legacy Compose path it is a container in the stack. A standalone relay is only needed for additional sites.

Confirm the built-in relay is running:

# Kubernetes/Helm (appliance, Windows-orchestrated, native Linux, your own cluster)
sudo k3s kubectl get pods -l app.kubernetes.io/name=cloudgrange-relay
sudo k3s kubectl logs -l app.kubernetes.io/name=cloudgrange-relay --tail=50

# Legacy Compose
sudo docker compose -f /opt/cloudgrange/docker-compose.yml ps cloudgrange-relay

An additional site on Kubernetes

Deploy the relay subchart on its own with the site's values:

helm install cloudgrange-relay oci://ghcr.io/cloudgrange/charts/cloudgrange \
  --version 2609.0.0-preview.7 \
  --set api.enabled=false --set portal.enabled=false \
  --set postgres.enabled=false --set keycloak.enabled=false \
  --set observability.enabled=false \
  --set relay.env.RELAY_PAAS_URL=https://<control-plane-host> \
  --set relay.env.RELAY_ENROLLMENT_TOKEN=<one-time-token-from-portal>

Generate the one-time enrollment token in the portal under Sites → add site → generate token.

A relay is configured by environment variables (see Variables Registry for the full list). The key ones:

Enrollment security

• A relay enrolls with the control plane once, using a one-time enrollment token generated in the portal (Sites → add site → generate token). The token is time-limited and single-use.
• Agents enroll with the relay using the shared RELAY_AGENT_ENROLLMENT_TOKEN.
• Re-enrolling a host that is already enrolled requires admin approval via RELAY_ADMIN_TOKEN, with a time-limited, single-use approval. This is an interim control until mTLS lands.

Next step

Install the CloudGrange Agent on each Hyper-V host at the site.

See current product and release status.