Automated Agent Deployment via REST API

Available in rConfig V8.2.1+

The POST /api/v2/agents/provision endpoint was added in rConfig V8.2.1. Earlier versions support the UI Install Command and Manual Binary Install paths only. Confirm your Vector Server version under Settings → System → About before wiring this into a runbook.

Pushing Vector Agents to a fleet by hand stops scaling somewhere around the tenth host. The POST /api/v2/agents/provision endpoint exists so you can fold agent rollout into the same runbook you already use to provision the rest of the host. Each call creates the agent record, mints a one-shot bootstrap token, and returns a ready-to-run install command. You execute that command on the target host. Done.

The endpoint is idempotent on name, so re-running the same playbook against an already-provisioned host issues a fresh token instead of failing. That makes it safe to use as the standard “agent rollout” task in any infrastructure-as-code workflow.

Note

Need the field-by-field reference for the request and response? It is rendered in-app under Settings → REST API → REST API Documentation → Vector API → Agent Provisioning, gated to instances where the Vector Server package is installed. This page is the deployment-process companion: when to use it, how to wire it up, and what to expect on the target host.

The flow

There are two steps and two hosts involved. The provision call is made from your orchestrator (Ansible control node, CI runner, jump host, your laptop). The install command is run on the target host where the agent will live.

┌─────────────────┐  ① POST /api/v2/agents/provision   ┌──────────────────┐
│  Orchestrator   │  ─────────────────────────────────▶│  rConfig Server  │
│ (Ansible / CI)  │  ◀───── 201 install_command ───────│                  │
└────────┬────────┘                                    └──────────────────┘
         │
         │ ② ssh target "<install_command>"
         ▼
┌─────────────────┐  ③ installer, SHA256 check, bootstrap ┌───────────────┐
│  Target host    │ ──────────────────────────────────▶│  rConfig Server  │
│ (vectoragent)   │ ◀───── api_token + binary ─────────│                  │
└─────────────────┘                                    └──────────────────┘

Step ① returns a string. It does not deploy anything by itself. You still have to execute that string on the target host. The most common runbook pattern is one task per host that does step ① against rConfig, and a second task that runs the returned install_command on the target as a user that can sudo.

Changed in V8.4.1: update runbooks that run install_command

From V8.4.1, install_command no longer pipes a script from the rConfig server into bash. It downloads a fixed installer, checks it against a published SHA256, and runs it with sudo. The old curl … /vector/install.sh?bootstrap_token=… | bash command now installs nothing and exits 1. Runbooks that run install_command as returned keep working once sudo is available on the target; runbooks that build the old URL themselves must switch to install_command.

Prerequisites

• rConfig Vector Server V8.2.1 or later. The provision endpoint does not exist on earlier versions.
• Vector Server package installed and the agents table reachable from the rConfig server.
• An rConfig REST API token with the Provision Vector agents (agents.write) ability. Create one under Settings → REST API → Tokens, tick that ability, and send the token as the apitoken request header. From V8.4.2 the endpoint checks this, and also checks the token owner’s role: agent.create to create an agent, or agent.update to issue a new install command for an agent that already exists. Earlier versions accepted any active token.
• Network reachability from each target host to the rConfig server on port 443. The installer downloads the binary and exchanges the bootstrap token over HTTPS only.
• sudo on each target host, and curl, sha256sum, sort, awk, install and mktemp. The installer writes to /usr/local/bin/rconfig and /etc/systemd/system, and runs systemctl enable and start. It does not install missing tools.
• A Linux x86-64 host. The currently published install script targets linux_amd64 only; ARM, Windows, and macOS targets are not covered by this flow.

Step 1: Provision the agent

Call the provision endpoint with the agent’s intended name. name is the only required field; everything else has sensible defaults.

curl -k -X POST "https://rconfig.example.com/api/v2/agents/provision" \
  -H "apitoken: $RCONFIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"edge-customer-acme-01"}'

The response is JSON. Capture the install_command:

{
  "success": true,
  "message": "Agent provisioned successfully.",
  "data": {
    "agent_id": 42,
    "name": "edge-customer-acme-01",
    "created": true,
    "install_command": "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 'u8ESlutig0sAUwYGxAhhDlE8gSKRqRrVThRDtbj6NkguolubjDgD6qg4xykSrnzl'",
    "installer_sha256": "<installer_sha256>",
    "installer_docs_url": "https://docs.rconfig.com/installation-upgrades/vector/agent-installation/#installer-sha256",
    "bootstrap_token": "u8ESlutig0sAUwYGxAhhDlE8gSKRqRrVThRDtbj6NkguolubjDgD6qg4xykSrnzl",
    "expires_at": "2026-05-09T15:00:00.000000Z"
  }
}

A few things to note:

• HTTP 201 means the agent record was created. HTTP 200 with "created": false and the message Agent already existed; new bootstrap token issued. means an agent with that name already existed; rConfig burned any unused bootstrap tokens for it and issued a fresh one. Both are normal in a runbook re-run.
• bootstrap_token is single-use and TTL-bound. The default lifetime is 60 minutes. If your pipeline has a long delay between provision and run-on-host (large fleets, staged rollouts), pass bootstrap_ttl_minutes up to a maximum of 1440 (24 hours).
• install_command is a literal shell command. It is the same command the rConfig UI copies when an operator clicks Linux install for an existing agent.
• installer_sha256 is the SHA256 the command checks the installer against. installer_docs_url links to the published installer SHA256 for your version. Compare the two before you roll out, for example as a pipeline gate.
• If the agent record has TLS verification turned off (ssl_verify: false), the command adds -k to the download and --insecure-tls to the installer.

Per-agent endpoints return command, not install_command

The UI endpoints GET /api/agents/{id}/install-command and POST /api/agents/{id}/bootstrap-token return the command as command, with installer_sha256, installer_docs_url and expires_at. bootstrap-token also returns token. They use the signed-in UI session, not an apitoken, so use POST /api/v2/agents/provision from automation.

Optional fields

Field	Type	Default	Notes
email	string	null	Contact for the agent. Surfaced in the UI agent list.
srcip	string	null	CIDR allowlist (comma- or newline-separated) the agent will be permitted to connect from.
srcip_from_request	boolean	false	When true and srcip is omitted, the allowlist is set to the caller’s IP (/32). Only useful when the host calling this API is also where the agent will run. Orchestrators (Ansible control nodes, CI runners) should leave this off, since their IP is not the agent’s IP.
checkin_interval	integer	300	Seconds between agent check-ins.
max_missed_checkins	integer	3	Missed check-ins before the agent is marked down.
worker_count	integer	5	Number of agent workers.
roles	array of integer	[1]	Role IDs assigned to the agent.
bootstrap_ttl_minutes	integer	60	Lifetime of the returned bootstrap token. Max 1440.
device_source_address	string	null	IPv4 or IPv6 address on the agent host that the agent connects to devices from, the same IP version as the agent’s devices. Loopback, link-local, unspecified and multicast addresses are rejected with 422. Set only when the agent is created. See Outbound source address.

Explicit srcip always wins over srcip_from_request. Send both only if you want the explicit value.

From V8.4.1, the response also includes device_source_address, the agent’s stored outbound source address, and device_source_address_mismatch. Provisioning never changes the address of an agent that already exists. If you send a different device_source_address for an existing agent, device_source_address_mismatch is true, the stored value is returned unchanged and the message says so. Treat that as a stop in a runbook: fix the address on the agent in rConfig before installing.

Step 2: Run the install command on the target

The install command is a one-liner. Run it on the target host as root or as a user with sudo, from a folder only that user can write to, such as its home folder:

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

The command downloads the installer to vector-agent-install.sh in the current folder, checks its SHA256, and runs it with sudo only if it matches. The installer takes these arguments:

Argument	Value
--server	https://<host>[:port] of the rConfig server, with no path
--agent-id	The agent ID from the provision response
--token	The bootstrap token, 32 to 128 letters and digits
--insecure-tls	Skip TLS certificate checks, for a self-signed rConfig certificate. Added only when the agent record has TLS verification off.
--token-file	Read the bootstrap token from a file instead of --token, so it never appears in ps or shell history. From V8.4.1.
--instance	Install one of several agents on the host, in /usr/local/bin/rconfig/agents/<name> with its own vectoragent@<name> service. From V8.4.1. See Running multiple agents on one host.
--no-proxy	Ignore http_proxy and https_proxy when contacting rConfig. From V8.4.1.

From V8.4.1, --agent-id and the token are optional when the agent is already installed. Re-running the installer with only --server (and --instance for an instance) updates the binary to the active release.

What the installer does, in order:

1. Stops unless it runs as root, and unless curl, sha256sum, sort, awk, install and mktemp are present.
2. Validates the server URL, agent ID and token before anything is written.
3. Downloads the active agent binary from <server>/vector/downloads/vectoragent-latest and checks its SHA256 against the pinned agent releases (1.1.1 to 2.0.1). A binary that is not a pinned release is never installed.
4. Refuses to replace a newer pinned release with an older one. An installed binary that is not a known release is replaced, with a warning.
5. If /usr/local/bin/rconfig/activeagent/.env does not exist, calls POST /api/vector/agents/bootstrap with the agent ID and token in a JSON body, and checks the returned API key.
6. Creates /usr/local/bin/rconfig/activeagent and /usr/local/bin/rconfig/data/{logs,db,files}, and installs the binary as /usr/local/bin/rconfig/activeagent/vectoragent unless the same binary is already there.
7. Writes .env (mode 600) with API_URL, API_KEY and SSL_VERIFY, only when it bootstrapped.
8. Writes /etc/systemd/system/vectoragent.service if not already present, runs systemctl daemon-reload and enable, then start (or restart if the binary was updated).
9. Prints systemctl status vectoragent and vectoragent --version so you can see the result in the runbook output.

The installer is idempotent. Re-running it on a host that already has the agent skips the binary install if the SHA matches, skips the bootstrap if .env already exists, and skips writing the unit file if it is already there.

The token is passed as an argument, not in a URL. It is still visible in ps on the target while the installer runs, and in your runbook logs, so treat those logs as sensitive. From V8.4.1 you can pass it with --token-file instead. It is single-use, so a token that has been used is worthless.

Wiring it into a runbook

The most common patterns. Pick whichever your existing automation already uses.

Ansible

# rconfig_token, rconfig_url, and inventory groups defined elsewhere.

- name: Provision Vector Agent in rConfig
  delegate_to: localhost
  uri:
    url: "{{ rconfig_url }}/api/v2/agents/provision"
    method: POST
    headers:
      apitoken: "{{ rconfig_token }}"
    body_format: json
    body:
      name: "{{ inventory_hostname }}"
    status_code: [200, 201]
    validate_certs: false
  register: rconfig_provision

- name: Deploy Vector Agent on target
  become: true
  shell: "{{ rconfig_provision.json.data.install_command }}"
  args:
    creates: /usr/local/bin/rconfig/activeagent/vectoragent

The creates: argument makes the shell task itself idempotent at the Ansible layer (it only runs if the binary file is missing). Combined with the installer’s own idempotency, you can re-run this playbook against the same hosts safely. To check the installer hash before deploying, compare rconfig_provision.json.data.installer_sha256 with the published value in an assert task.

Bash + ssh

#!/usr/bin/env bash
set -euo pipefail

RCONFIG_URL="https://rconfig.example.com"
HOSTS=(edge-acme-01 edge-acme-02 edge-acme-03)

for host in "${HOSTS[@]}"; do
  echo "Provisioning $host…"
  install_cmd=$(curl -sk -X POST "$RCONFIG_URL/api/v2/agents/provision" \
    -H "apitoken: $RCONFIG_TOKEN" -H "Content-Type: application/json" \
    -d "{\"name\":\"$host\"}" \
    | jq -r '.data.install_command')

  echo "Installing on $host…"
  ssh "root@$host" "cd ~ && $install_cmd"
done

The command downloads the installer and runs it in the remote home folder; it never pipes anything into bash.

Terraform (null_resource)

resource "null_resource" "vector_agent" {
  for_each = toset(var.target_hosts)

  triggers = {
    host = each.value
  }

  # Provision in rConfig from the orchestrator
  provisioner "local-exec" {
    command = <<-EOT
      curl -sk -X POST "${var.rconfig_url}/api/v2/agents/provision" \
        -H "apitoken: ${var.rconfig_token}" \
        -H "Content-Type: application/json" \
        -d '{"name":"${each.value}"}' \
        | jq -r '.data.install_command' > ./install-${each.value}.sh
    EOT
  }

  # Run the returned command on the target host
  connection {
    host = each.value
    user = "root"
    type = "ssh"
  }

  provisioner "remote-exec" {
    script = "./install-${each.value}.sh"
  }
}

The saved file holds the bootstrap token. Keep it out of shared folders and delete it after the run.

Verifying success

After the install command finishes on the target, two things should be true:

• systemctl status vectoragent shows active (running).
• The agent appears on the Vector Agents screen in the rConfig UI with a green Healthy status, typically within one check-in interval (default 5 minutes).

If the agent appears but stays in Down state, the most common causes are:

• The srcip allowlist is set to a CIDR the agent’s egress IP does not match. Fix it on the Vector Agents screen (edit the agent, Source IP), or re-provision with srcip set correctly.
• TLS verification failing on the agent side. The installer writes SSL_VERIFY=true unless the command included --insecure-tls. If your rConfig server uses a self-signed certificate, turn TLS verification off on the agent record before provisioning, so the command includes it.
• The bootstrap token expired before step 2 ran. Provision again to mint a new one.

If the provision call returns 403, the token is missing the agents.write ability, or its owner’s role is missing agent.create (new agent) or agent.update (existing agent). Token abilities can’t be edited, so create a new token with Provision Vector agents ticked and swap it into your runbook.

If the install command itself stops, read its last line:

Output	Cause
vector-agent-install.sh: FAILED	The installer did not match installer_sha256. Nothing ran. Don’t work around it; check the rConfig server.
… is not a known rConfig Vector agent release (SHA256 …). Nothing was installed.	The active binary on the Vector Server is not a pinned release. Activate a published release on the Binary Admin page (/settings/agents/binaries).
Refusing to downgrade the agent from … to …. Nothing was installed.	The host runs a newer agent than the active binary on the server.
The bootstrap request to … failed. The token may be used or expired.	Provision again for a fresh token.
sudo: command not found	Install sudo, or run the part after the second && as root without sudo.

Caveats and limits

• Linux x86-64 only. The current installer fetches the linux_amd64 binary. ARM, Windows, and macOS targets need to be installed manually, see Manual Binary Install.
• No systemd, no auto-start. The installer skips the unit-file step on hosts without systemctl (Alpine, minimal containers). The binary will be installed and .env written, but you have to start vectoragent yourself.
• Bootstrap token TTL. The default is 60 minutes from the provision call. For staged rollouts that wait on approvals, raise bootstrap_ttl_minutes rather than re-calling provision repeatedly.
• API token scope. The apitoken you pass to provision is a regular rConfig REST API token. It can do what its abilities allow, within its owner’s role. Give your provisioning token only Provision Vector agents, treat it as a high-trust credential, and rotate it regularly.

What’s next

• Manual Binary Install - The OS-by-OS walkthrough for hosts that cannot use the install command
• Adding Agents to Vector - What the agent record contains and how authentication works under the hood