Running Multiple Agents on One Host

From V8.4.1, with Vector agent 2.0.1 or later, one host can run several Vector Agents side by side. Each agent has its own directory, service and outbound source address, so each one connects to its devices from a different local IP.

Best for: a jump host or access node with one interface per network, where each network only accepts traffic from that interface’s address. This is common on MSP hosts that use source-based routing (ip rule add from <address> lookup <table>) to keep customer networks apart, including networks whose device addresses overlap.

When not to use: a host with one network, or several networks a single agent can reach from its default address. One agent is simpler.

How it works

Each network gets its own agent record in rConfig, with Outbound Source Address set to the host’s address on that network. The agent sends every device connection (SSH and ping) from that address, so the host’s existing routing sends it to the right network. No routing changes are needed on the host.

Because a device belongs to one agent, two networks can contain devices with the same IP. Each device is reached through its own agent and its own source address.

Item	Single agent	Agent instance `<name>`
Directory	`/usr/local/bin/rconfig/activeagent`	`/usr/local/bin/rconfig/agents/<name>`
Data (job and log databases)	`/usr/local/bin/rconfig/data`	`/usr/local/bin/rconfig/agents/<name>/data`
Service	`vectoragent`	`vectoragent@<name>`
Unit file	`vectoragent.service`	`vectoragent@.service` (one template for every instance)

The template unit sets VECTOR_AGENT_ROOT for each instance, so the agents never share files. A single agent and instances can run on the same host.

Set it up

For each network on the host:

In rConfig, go to Settings > Agents, click Add Agent, and give it a name that identifies the host and network, for example jump01-network-a.
On the Configuration tab, under Advanced, set Outbound Source Address to the host’s address on that network, IPv4 or IPv6, matching the IP version of that network’s devices. Loopback and link-local addresses are not accepted. Save.

Copy the agent’s install command (Linux install), add --instance <name> to the end, and run it on the host. Use a short name for the network, for example network-a. Add --no-proxy if the host sets http_proxy or https_proxy and rConfig must be reached directly.

curl -fsSL --proto '=https' -o vector-agent-install.sh 'https://rconfig.example.com/vector/agent-install.sh' \
  && echo '<installer_sha256>  vector-agent-install.sh' | sha256sum -c - \
  && sudo bash vector-agent-install.sh --server 'https://rconfig.example.com' --agent-id 42 --token '<bootstrap token>' --instance network-a --no-proxy

Assign that network’s devices to the agent.

Then check the agents on the host:

systemctl list-units 'vectoragent@*'
journalctl -u vectoragent@network-a -f

In rConfig, the agent’s details panel shows Outbound Source Address as In use once the agent has checked in with it.

Update and remove agents

Update an instance by running the installer again with its instance name. It keeps the instance’s .env, so no token is needed:

sudo bash vector-agent-install.sh --server 'https://rconfig.example.com' --instance network-a

To remove an instance, stop it and delete its directory, then reassign or delete its devices in rConfig and disable the agent:

sudo systemctl disable --now vectoragent@network-a
sudo rm -rf /usr/local/bin/rconfig/agents/network-a

When something is wrong

What you see	Cause and fix
Not on agent host on the agent, and device jobs fail with `outbound source address not available on this host`	The address is not configured on the host. Fix the address in rConfig, or the interface on the host. The agent never falls back to another address.
Agent update needed	The agent is older than 2.0.1 and ignores the address. Run the installer again for that instance once 2.0.1 is the active binary.
Waiting for agent	The agent has not checked in since the address was set. Wait one check-in interval.
Jobs fail with `different IP versions (IPv4/IPv6)`	The device’s address is IPv6 and the agent’s source address is IPv4, or the other way round. Move the device to an agent with a source address of the same IP version.
Two agents use the same data	The agent was started by hand, not through `vectoragent@<name>`. Use the service, which sets `VECTOR_AGENT_ROOT`.
`--instance must be 1-32 lowercase letters, digits, - or _`	Pick a shorter instance name made of those characters.

For other agent problems, see Vector Troubleshooting.