Install the agent

The tier-3 hybrid agent runs in your VPC and brokers all connector calls from RapidValue's control plane. Single file, single bash command, outbound-only HTTPS.

Why an agent?

For EU sovereignty, air-gapped targets, or anywhere connector calls must originate from your network edge. Identity data + credentials never leave your environment.

Requirements

• Python 3.10+
• Outbound HTTPS to your RapidValue control plane (https://<tenant>.rapidvalue.be)
• Inbound network reachability to the targets you'll connect (LDAP, SAP, on-prem REST APIs, etc.)
• ~200MB RAM, ~50MB disk

The agent is one Python file (~700 lines). No daemonizing framework required — systemd, supervisord, or a plain & background process all work.

One-line install

Get the install one-liner from your tenant:

# In your tenant: Settings → Tier-3 agents → Register new agent
# Copy the command shown. Looks like:

curl -sSL https://<tenant>.rapidvalue.be/agent/install | \
  RV_AGENT_TOKEN=rv_agent_xxx... bash

What this does:

1. Downloads tier3_agent.py from your control plane
2. Verifies its SHA-256 against the manifest
3. Writes it to /opt/rapidvalue/tier3_agent.py
4. Creates /opt/rapidvalue/agent-vault.json (empty)
5. Writes a systemd unit (or prints alternate launch instructions if systemd isn't present)
6. Starts the agent
7. Confirms registration with the control plane

You'll see "Agent registered, status: online" in the tenant's agent list within ~30 seconds.

Environment variables

The systemd unit (or your launch command) needs:

Variable	Required	Purpose
RV_CONTROL_PLANE_URL	Yes	Your tenant URL — set by the installer
RV_AGENT_TOKEN	Yes	Bearer token for spine auth — printed at registration
RV_AGENT_UPDATE_KEY	Yes	HMAC key for verifying self-update payloads
RV_AGENT_VAULT_PATH	No	Default /opt/rapidvalue/agent-vault.json
RV_AGENT_SELF_UPDATE	No	1 (default) to allow auto-updates, 0 to pin
RV_POLL_WAIT	No	Long-poll wait seconds, default 25
RV_HEARTBEAT_INTERVAL	No	Default 30 seconds
RV_AGENT_CHUNK_SIZE	No	Records per chunk for large syncs, default 500

Add credentials for your targets

Edit /opt/rapidvalue/agent-vault.json:

{
  "salesforce-prod": {
    "client_id": "...",
    "client_secret": "...",
    "refresh_token": "..."
  },
  "ldap-corp": {
    "bind_dn": "cn=svc-rapidvalue,ou=service,dc=corp,dc=local",
    "bind_password": "..."
  }
}

The key is the connector business_id. Credentials never travel across the wire — the agent looks them up locally when a task arrives.

Restart the agent after editing (or send SIGHUP to reload without dropping the long-poll connection).

Verify

In your tenant, head to Settings → Tier-3 agents. You should see:

• Status: online (green dot)
• Last heartbeat: <30 seconds ago
• Version: current tier3_agent.py SHA
• mTLS: optional — see security model for setup

Run a test sync from any connector instance configured with execution_mode=agent. The dashboard will show the task being claimed by your agent, executed, and the result streamed back.

Optional: mTLS

For an extra trust layer on top of the bearer token, register a client cert fingerprint with the agent:

# Generate a cert pair (or use one from your PKI):
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /opt/rapidvalue/agent-cert.key \
  -out /opt/rapidvalue/agent-cert.pem \
  -days 365 -subj "/CN=tier3-agent-prod-01"

# Compute fingerprint:
openssl x509 -in /opt/rapidvalue/agent-cert.pem -noout -fingerprint -sha256

# In tenant: Settings → Tier-3 agents → <your agent> → mTLS
# Paste the fingerprint, save.

# Restart agent with cert paths set.

The control plane will now require requests from this agent to present the matching client cert. Fingerprint mismatch = 403.

Updating

Self-update is on by default. The control plane signs new agent binaries with the per-agent HMAC key. The agent verifies, writes tier3_agent.py.bak, restarts, and waits 60s for .stable marker before committing.

If the new version crashes during boot, next-start auto-reverts to the .bak and reports the failure to the control plane.

To pin a version: set RV_AGENT_SELF_UPDATE=0.

Uninstall

systemctl stop rapidvalue-agent
systemctl disable rapidvalue-agent
rm -rf /opt/rapidvalue
rm /etc/systemd/system/rapidvalue-agent.service

In the tenant, Settings → Tier-3 agents → Remove to revoke the bearer token.