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>"
         ▼
┌─────────────────┐  ③ curl install.sh + 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 with become: true (or equivalent).

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 permissions for the v2 agents API. Generate one under Settings → REST API → Tokens, mark it active, and use it as the apitoken request header.
• Network reachability from each target host to the rConfig server on port 443. The install script downloads the binary and exchanges the bootstrap token over HTTPS.
• Root (or sudo) on each target host. The install script writes to /usr/local/bin/rconfig, /etc/systemd/system, and runs systemctl enable && start.
• 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 -kfsSL \"https://rconfig.example.com/vector/install.sh?bootstrap_token=u8E…Sn1\" | bash",
    "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 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 pipeline. It is the same command the rConfig UI shows when an operator clicks Generate Install Command for an existing agent.

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.

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

Step 2: Run the install command on the target

The install command is a one-liner. On the target host, as root:

curl -kfsSL "https://rconfig.example.com/vector/install.sh?bootstrap_token=…" | bash

What that does, in order:

1. Installs curl and coreutils if missing (apt / dnf / yum).
2. Creates the directory tree under /usr/local/bin/rconfig/.
3. Downloads the active agent binary and verifies its SHA256 checksum.
4. Calls POST /api/vector/agents/bootstrap with the embedded agent_id + bootstrap_token, receives back the permanent api_token.
5. Writes /usr/local/bin/rconfig/activeagent/.env (mode 600) with API_URL, API_KEY, SSL_VERIFY.
6. Writes /etc/systemd/system/vectoragent.service if not already present.
7. Runs systemctl daemon-reload, enable, then start (or restart if the binary was updated).
8. Prints vectoragent --version and systemctl status vectoragent so you can see the result in the runbook output.

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

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 script’s own internal idempotency, you can re-run this playbook against the same hosts safely.

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" "$install_cmd"
done

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' > /tmp/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 = "/tmp/install-${each.value}.sh"
  }
}

Verifying success

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

• systemctl status vectoragent shows active (running).
• The agent appears in Settings → Agents 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 in the UI under Settings → Agents → [agent] → Source IP, or re-provision with srcip set correctly.
• TLS verification failing on the agent side. The default install enables SSL_VERIFY=true if the agent record has it set; if your rConfig server uses a self-signed certificate, set ssl_verify: false on the agent record before provisioning.
• The bootstrap token expired before step 2 ran. Provision again to mint a new one.

Caveats and limits

• Linux x86-64 only. The current install script 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 script 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 anything that token’s role allows. Treat it as a high-trust credential and rotate it regularly.

Related

• Manual Binary Install: the OS-by-OS walkthrough for hosts that cannot use the piped installer.
• Adding Agents to Vector: what the agent record itself contains and how authentication works under the hood.