V-Ray Swarm
Advanced Settings
This page provides detailed Swarm setup information.
Last updated 21 November 2025
This page provides detailed Swarm setup information.
Yaml File Configuration
V-Ray Swarm 2 stores its configuration in a swarm.yaml file. The default file locations for each operating system are listed below.
Use the UI interface at http://localhost:1113/configuration to set your V-Ray Swarm machine preferences. If editing the swarm.yaml configuration file is required, see the table below for a list of the supported fields.
After changing the swarm. yaml file, you need to restart the Swarm service. Once you restart the service, open http://localhost:1113 to check if the settings file loaded correctly. If there is an error, Swarm runs in fallback mode and shows an information message in the Swarm interface.
Operating System | Location |
|---|
Operating System | Location |
|---|---|
Windows | C:/Windows/System32/config/systemprofile/AppData/Roaming/Chaos/V-Ray/Swarm 2/swarm.yaml |
macOS | /Library/Chaos/V-Ray/Swarm2/swarm.yaml |
Linux | /etc/Chaos/V-Ray/Swarm2/swarm.yaml |
Default Settings
Field | Unit type | Default value | Description |
|---|
Field | Unit type | Default value | Description |
|---|---|---|---|
dataDir | full path | <OS-diff> | Specifies the data directory where V-Ray Swarm 2 stores its downloaded V-Ray builds, cached peers table, and node ID. |
grpcPort | port number | 1115 | Specifies the port number for the gRPC server, which facilitates communication between the DCC and the V-Ray Swarm service. |
heartbeatPeriod | milliseconds | 5000 | Specifies the interval at which the node emits signals for network discovery. |
keepSockAlive | milliseconds | 5000 | Specifies the duration for which the peer socket remains active, waiting for incoming requests. |
licensesPath | full path | <OS-diff> | Specifies the path to the licenses.zip file, which contains information about the open-source libraries used by V-Ray Swarm 2. |
mcastGroup | IPv4 | 239.242.6.10 | Specifies the Multicast IP address of the group used for the network discovery of the nodes. V-Ray Swarm nodes use this IP for membership assignment to the group. |
mcastPort | port number | 1112 | Specifies the Multicast port used by the network discovery. |
mcastTTL | integer | 1 | Specifies the Multicast TTL used for the network discovery. |
offlinePeerAfter | milliseconds | 75000 | Specifies the time interval after which a peer is marked as offline. |
peersListen | integer | 256 | Listen queue length of the peers communication server socket. |
peersPort | port number | 1114 | Specifies the port of the TCP peers communication. |
peersTimeout | milliseconds | 3000 | Specifies the timeout for the peers communication. |
sockWaiting | poll | select | plain | Windows: select Others: plain | Specifies the socket waiting for all platforms. |
unstablePeerAfter | milliseconds | 25000 | Specifies the time interval after which a peer is marked as unstable. |
vrayPort | port number | 20212 | Specifies the port of the DR server. |
webPort | port number | 1113 | Specifies the port of the web page, e.g. V-Ray Swarm UI. |
Network Settings Requirements
V-Ray Swarm uses multicast, distributed discovery, and manual IP for node communication within the cluster.
Multicast – V-Ray Swarm uses multicast via UDP for automatic discovery of the nodes in a single network segment and TCP communication between the nodes to exchange node state data.
Distributed Discovery – Each node in V-Ray Swarm shares its knowledge of the already accessed peers with the rest of the cluster. This leads to faster knowledge synchronization within the cluster.
Manual IP – Provides multi-segment visibility of all cluster nodes. Add the IP of a machine in the neighbor segment. Your node connects via TCP and exchanges peer knowledge with that machine between the segments.
Firewall
V-Ray Swarm standalone installer adds a firewall exception for the service by default. In case of connectivity issues, check the values of grpcPort, mcastPort, peersPort, vrayPort, and webPort fields in the swarm.yaml config file. Make sure they are enabled for V-Ray Swarm 2 in the firewall settings.
Multicast
V-Ray Swarm uses multicast for UDP discovery so that all nodes can automatically discover the rest of the cluster's peers and establish successful communication with them.
The mcastGroup default value is 239.242.6.10.
To change the mcastGroup default value, edit the mcastGroup, mcastIp, mcastPort, mcastSockAlive, or the mcastTTL fields of the swarm.yaml configuration file. Make sure that the new value of mcastGroup is allowed for multicast.
Field | Unit type | Default value | Description |
Field | Unit type | Default value | Description |
mcastGroup | IPv4 | 239.242.6.10 | Specifies the multicast IP address of the group used for the network discovery of the nodes. V-Ray Swarm nodes use this IP for membership assignment to the group. |
mcastIp | [IPv4] | {include: [IPv4], exclude: [IPv4]} | [] | Specifies the NIC IPs for multicast to be included or excluded from the auto-detected ones. Specifies a list of IPv4 addresses to include, or an object for more advanced configurations. |
mcastPort | port number | 1112 | Specifies the multicast port used by the network discovery. |
mcastSockAlive | milliseconds | 15000 | Specifies the multicast sockets maximum lifetime. The re-join to mcastGroup value must be less than unstablePeerAfter. |
mcastTTL | integer | 1 | Specifies the multicast TTL used for the network discovery. The number of “hops” between switches or routers that a node's multicast ping passes inside the network before being discarded. |
Network Interface Cards (NIC)
Every computer can contain multiple network interface cards. Not all of them are active at the same time. Go to the Swarm Resources > Network tab to see the number of NICs on your machine and check their activity status.
V-Ray Swarm supports a multi-segment cluster and recognizes node visibility through all of its active NICs. It automatically adjusts and updates the communication through the best NIC option for your machine.
To ensure that V-Ray Swarm recognizes the correct network interface card (NIC), you can set a specific IP address in the mcastIp field of the swarm.yaml configuration file. This is particularly useful if you switch between your Ethernet NIC adapter and WiFi, as this may cause your machine's status to be inaccurately reflected in the V-Ray Swarm cluster. After making this adjustment, be sure to restart the V-Ray Swarm service. By doing so, V-Ray Swarm starts monitoring your node's availability based only on the specified NIC.
Field | Unit type | Default value | Description |
Field | Unit type | Default value | Description |
ipCmdPath | full path | - | Path to “ip” OS command (useful only if Swarm cannot find its default location), relevant for Linux |
ifconfigCmdPath | full path | - | Path to “ifconfig” OS command (useful only if Swarm cannot find its default location), relevant for Linux, MacOS |
nicIpPrio | [{NIC_NAME: [rule]}] | - | Rules (by NIC’s name; also “*” can be used instead of a NIC name which means “for all NICs”) specifying how to choose a single IP for NIC with multiple IPs (only one IP is supported). IPs are listed (by commands like “ipconfig” and similar) and then they are sorted, and the chosen IP is the first one after their sort. Rules are strings like:
Example: nicIpPrio: |
manualNics | [{ip: IPv4, name: NIC_NAME} | {mac: MAC, ip4: IPv4, ip6: IPv6, name: string}] | - | Manually added NICs with their names (NIC_NAME is just a string), addresses. The type is a list of dictionaries. A dictionary has 2 forms: brief (ip + name) which is the preferred form and full one (mac + ipv4 + ipv6 + name). Addresses support several equal keys: ip/ip4/ipv4 - are the same. And ip6/ipv6 - are the same too. Example: manualNics: - mac: 11:12:13:14:15:16 |
rejectNics | [string] | - | Rules to reject (not to be used by local Swarm instance) some NICs, it’s a list of string-rules and every string-rule can be:
Example: rejectNics: [vpn,vm] |
VPN
In case you are using a VPN and are experiencing availability issues with the V-Ray Swarm cluster, it may be due to your machine being on a different network than the cluster. To ensure successful communication and rendering with the machines in the cluster, follow these steps:
- Go to the Configuration page.
- Scroll down to the Network Discovery section.
- In the Manual IPs field, enter the IP address of an available machine in the cluster and save your changes. If you are unsure which IP address to use, consult your system administrator for the exact IP of a machine that is already part of the cluster.
V-Ray Swarm attempts to connect via TCP to the machines listed in the Manual IPs field. If at least one of these machines is accessible through the network and has V-Ray Swarm service running, the two machines start exchanging information about their cluster nodes. This establishes a connection between devices on different networks.
V-Ray Swarm nodes discover each other automatically. If multicast is disabled or not supported by the VPN configurations, at least one accessible IP for TCP communication can enhance cluster visibility.
SNAT
SNAT hides all node IPs from the private network into a single public IP. In order for all nodes from the cluster to have successful communication, V-Ray Swarms expects that TCP works in both directions - from node A to node B, and vice versa. If there is SNAT between nodes A and B, this condition won't be met.
For example, if node A uses VPN to reach node B in a private network with active SNAT, node A won't be able to recognize the different render nodes within the private network as they would look like the same machine for A.