Vector Hub and the Live Channel: Vector Access, Agent Restarts, and Instant Job Pickup

Vector Hub is an optional service on the rConfig server that gives each enabled Vector Agent a persistent, bidirectional live channel. After reading this page you can install the hub, enable the live channel per agent, restart agents remotely, and fix the common hub problems.

When should I use Vector Hub?

Without the hub, Vector Agents only poll the rConfig server on a timer, so the server cannot reach into an agent on demand and new jobs wait for the next poll. Install the hub when you want operators to SSH to remote-site devices without a VPN or jump host, restart agents without logging in to the agent host, or have queued jobs start near-instantly.

The hub is additive. If it is not installed, rConfig and its agents behave exactly as before.

What does the live channel unlock?

Capability	What it does
Vector Access	Opens a live SSH session to a device, proxied through its agent, with optional session recording.
Restart an agent	Restarts an agent from the Hub page over the live channel.
Auto job pickup	Nudges an agent to poll the moment a job is queued for it.
Self-healing certificates	Restores the server’s hub client certificates automatically if they go missing.

How does Vector Hub work?

The hub runs on the rConfig server as the hardened systemd service vector-hub.service, under the dedicated vector-hub user. The binary lives at /usr/local/bin/rconfig/activehub/vector-hub. Agents dial in to the hub over an outbound WebSocket, and once connected the server can push commands to them in real time.

The hub opens three listeners:

Listener	Default address	Who connects	Transport
Public tunnel	:8443 (all interfaces)	Vector Agents, outbound	WSS (WebSocket over TLS), path /tunnel
Control API	127.0.0.1:8444 (loopback only)	the rConfig Laravel app	HTTPS with mutual TLS (mTLS)
Session broker	127.0.0.1:8445 (loopback only)	the vector:access command	authenticated, loopback only

flowchart LR
  subgraph Site["Remote site"]
    A[Vector Agent] --> D[Network devices]
  end
  subgraph Server["rConfig server"]
    H["vector-hub.service (:8443 tunnel)"]
    L[rConfig app] -- "mTLS :8444" --> H
    S["php artisan vector:access"] -- ":8445" --> H
  end
  A -- "outbound WSS :8443/tunnel" --> H

Security model

• Only the tunnel port 8443 is network-facing. The control API and session broker bind to 127.0.0.1 and are never exposed.
• Agents connect outbound. Allow egress from the agent site to the rConfig server’s tunnel host on port 8443. No inbound firewall rule is needed at the agent site.
• Traffic between rConfig and the hub uses mutual TLS plus a shared secret (VECTOR_HUB_AUTH_SECRET).
• The service is hardened with ProtectSystem=strict, NoNewPrivileges, and MemoryDenyWriteExecute, and runs as a non-login user.
• Device credentials for Vector Access sessions are resolved on the server and are never printed or logged.

Prerequisites

• Vector installed and enabled in rConfig. The Hub navigation item and its settings only appear when Vector is installed. See Vector Server installation.
• At least one Vector Agent registered and enabled. See Adding agents to Vector.
• Root access to the rConfig server. The install script writes a systemd unit and TLS material.
• A TLS certificate and private key on the rConfig server for the public tunnel.
• Egress from each agent site to the rConfig server on TCP 8443.

How do I install Vector Hub?

Install from the UI (recommended)

1. Click Hub in the left sidebar (route /hub).

2. In the Install Vector Hub card, fill in the fields below.

   Field	Required	Meaning
   rConfig URL	Yes	The rConfig app URL the hub calls back to.
   Tunnel host	Yes	Hostname or IP agents dial for the tunnel. Becomes wss://<host>:8443/tunnel.
   Auth CA path	No	CA used to verify the auth callback.
   Local binary path	No	Installs this local hub binary and skips the download.
   Tunnel cert path	Yes	TLS certificate presented on the public tunnel.
   Tunnel key path	Yes	Private key for the tunnel certificate.
   Skip TLS verification for the binary download	Checkbox	Bypasses certificate checks when fetching the binary. Use only in labs or with self-signed setups.

3. Click Install Hub.

4. Watch the status badge. It shows the install state and exit code only, never the raw command output.

When the install succeeds, the page switches from the install card to the hub dashboard.

Install from a terminal

The UI runs a shell script rendered from the install-hub.sh.blade.php template. The same script can be run manually as root on the rConfig server. In one pass it:

• Installs or updates the hub binary. It downloads https://dl.rconfig.com/download-vector-hub/vector-hub-latest and its .sha256 checksum unless a local binary path was supplied.
• Generates an internal CA and leaf certificates: the loopback API certificate (api.crt, SAN IP:127.0.0.1,DNS:localhost), the tunnel certificate (tunnel.crt), and a Laravel client certificate (laravel-client.crt, with clientAuth).
• Generates the shared secret VECTOR_HUB_AUTH_SECRET, or reuses an existing one.
• Writes the hub environment file and the vector-hub.service systemd unit.
• Copies the client certificate, key, and CA into storage/app/vector-hub/ as client.crt, client.key, and ca.crt, and writes the VECTOR_HUB_* keys into rConfig’s .env.
• Runs a health check and verifies the auth callback.

How does rConfig decide the hub is installed?

rConfig treats the hub as installed when the binary exists at VECTOR_HUB_BIN_PATH (default /usr/local/bin/rconfig/activehub/vector-hub).

Uninstall the hub

Run the install script with --uninstall. It removes the service, the binary, and the TLS material, and strips the VECTOR_HUB_* keys from .env. Agents fall back to timer-based polling.

How do I enable the live channel on an agent?

The live channel is per agent and off by default. Turn it on in either place:

• Agent edit dialog: navigate to Settings > Agents, edit the agent, and set the toggle to Live Channel Enabled. The help text reads “Enables bidirectional connectivity for this agent (hub live channel).”
• Hub page: click the Enable button on the agent’s row in the Agents card.

Enabling sets the agent’s desired state. The agent then dials the hub, and once the tunnel is up rConfig records the observed state and shows the agent as connected. Each enable or disable is written to the agent audit log as Live channel enabled/disabled for agent <name>.

Status	Colour	Meaning
Connected	Green	Enabled and a live tunnel is up.
Enabled · waiting	Amber	Enabled, but the agent has not dialled in yet.
Disabled	Grey	The live channel is off for this agent.

The scheduled command vector:hub-sync-status refreshes the connection state, round-trip latency, and last-seen time every minute.

What does the Hub page show?

The Hub page (/hub, titled Vector Hub) shows KPI tiles, including service status, and an Agents card listing each agent’s live-channel status and actions. The roster is built to stay usable with 100+ agents:

• Server-side pagination: page size between 5 and 100, with “Page X of Y” and Previous/Next controls.
• Search by name or ID: the box labelled “Search agents by name or ID…” matches the agent name or its numeric ID.
• Enabled agents first: rows are ordered with enabled agents at the top, then alphabetically by name.
• Built-in agent hidden: the built-in vector-server agent (ID 1) is not a live-channel participant and does not appear.

The page also holds the Vector Access panel, which sets the Vector Access idle timeout.

The Hub page never shows logs

The Hub UI shows status only: badges, KPIs, and a short error string on failure. There is no SSH transcript viewer, agent log viewer, or hub log viewer. Install and uninstall results appear as a status badge with an exit code. Read SSH transcripts in storage/logs/vector-ssh/ on the server, and audit events in the normal rConfig agent and audit logs.

How do I SSH to a device through its agent?

Use Vector Access. It opens a live, optionally recorded SSH session to a device through its agent’s live channel, run on the rConfig server with php artisan vector:access. The session idle timeout is set in the Vector Access panel on the Hub page.

How do I restart an agent remotely?

1. Open the Hub page and find the agent in the Agents roster.
2. Click Restart. The button is only active when the agent’s live channel is connected.
3. Click Confirm at the “Restart <name>?” prompt.

rConfig pushes the restart over the live channel. The agent acknowledges, exits gracefully, and its supervisor (systemd with Restart=always) starts it again. Agents installed the standard way run under systemd and come back automatically.

Unsupervised agents stay down

An agent that is not running under a service supervisor will stay stopped after a restart. rConfig cannot relaunch a process it does not supervise. Start it again manually on the agent host.

How does auto job pickup work?

Without the live channel, an agent finds new work on its next scheduled poll, so a job can wait up to one poll interval. With the live channel enabled, rConfig nudges the agent to poll the moment a job is queued for it, so jobs start near-instantly.

• It applies only to agents with the live channel enabled. Other agents keep polling on their timer.
• It is best-effort. If the agent is briefly disconnected or the hub is unreachable, the agent still picks the job up on its next normal poll.
• Bursts of queued jobs are debounced into a single nudge within a few seconds, and the agent collapses repeated nudges into at most one extra fetch.

There is nothing to configure. Enabling the live channel is enough.

How do the certificates self-heal?

rConfig talks to the hub using client.crt, client.key, and ca.crt in storage/app/vector-hub/. If those files are lost, for example after a storage wipe, redeploy, or permissions reset, the hub would appear to be not responding. rConfig recovers them automatically:

• Every minute: vector:hub-sync-status checks the hub. If the hub is unreachable, installed, and the client certificates are missing, it dispatches a re-sync job that copies the files back from the hub’s TLS directory (default /etc/vector-hub/tls) with ownership the web server can read. This auto-heal runs at most once every 5 minutes.
• On page load: if the Hub page detects missing certificates, it triggers one re-sync automatically. The service KPI tile shows Certs missing, and an amber Hub client certificates missing banner offers a manual Re-sync certificates button.

Missing certificates are usually restored within about a minute, or immediately when the Hub page is opened.

Common gotchas

Common gotchas

• Agent stuck on Enabled · waiting: the agent cannot reach the tunnel. Confirm the agent site allows egress to the Tunnel host on TCP 8443.
• Restart greyed out: the button needs a connected live channel. Enabling it is not enough; wait for Connected.
• Looking for logs in the UI: the Hub page never shows logs. Vector Access transcripts are on the server in storage/logs/vector-ssh/, and only exist when --log was used.
• Agent ID 1 missing from the roster: the built-in vector-server agent is hidden by design.

Configuration reference

The hub integration lives in the hub block of config/vector-server.php. If hub.api_url is unset, the hub integration is disabled entirely.

Config key	Env var	Example / default	Meaning
hub.tunnel_url	VECTOR_HUB_TUNNEL_URL	wss://rconfig.local:8443/tunnel	Tunnel URL delivered to agents.
hub.api_url	VECTOR_HUB_API_URL	https://127.0.0.1:8444	Control API (loopback mTLS). Unset disables the hub.
hub.session_addr	VECTOR_HUB_SESSION_ADDR	127.0.0.1:8445	Session broker used by vector:access.
hub.auth_secret	VECTOR_HUB_AUTH_SECRET	(generated)	Shared secret between rConfig and the hub.
hub.client_cert	VECTOR_HUB_CLIENT_CERT	storage/app/vector-hub/client.crt	mTLS client certificate.
hub.client_key	VECTOR_HUB_CLIENT_KEY	storage/app/vector-hub/client.key	mTLS client key.
hub.ca_cert	VECTOR_HUB_CA_CERT	storage/app/vector-hub/ca.crt	CA used to verify the hub.
hub.bin_path	VECTOR_HUB_BIN_PATH	/usr/local/bin/rconfig/activehub/vector-hub	Hub binary path. Its presence means installed.
hub.tls_source_dir	VECTOR_HUB_TLS_SOURCE_DIR	/etc/vector-hub/tls	Source directory for the certificate re-sync.

The hub binary reads its own environment:

Env var	Default	Meaning
VECTOR_HUB_TUNNEL_ADDR	:8443	Public tunnel listener.
VECTOR_HUB_API_ADDR	127.0.0.1:8444	Control API listener.
VECTOR_HUB_SESSION_ADDR	127.0.0.1:8445	Session broker listener.
VECTOR_HUB_AUTH_SECRET	(generated)	Shared secret.
VECTOR_HUB_HEARTBEAT_INTERVAL	15s	Tunnel heartbeat interval.

The log level defaults to info.

Two related agent-run watchdogs sit outside the hub block: task_unit_timeout_seconds (VECTOR_TASK_UNIT_TIMEOUT_SECONDS, default 300) limits each device run, and task_run_wait_timeout_seconds (VECTOR_TASK_RUN_WAIT_TIMEOUT_SECONDS, default 900) caps the overall run.

Troubleshooting

Why is the Restart button greyed out?

Cause: the agent’s live channel is not connected. The tooltip reads “Agent must have its live channel connected to restart”.

Fix: enable the live channel and wait for Connected. Status refreshes every minute.

Why does the hub show Certs missing or not responding?

Cause: the client certificates in storage/app/vector-hub/ are missing, usually after a storage wipe, redeploy, or permissions reset.

Fix: wait about a minute for the scheduled re-sync, or open the Hub page and click Re-sync certificates. If it persists, confirm the source files exist in /etc/vector-hub/tls and that the rConfig scheduler is running.

Why wasn’t a job picked up instantly?

Cause: auto job pickup only applies to live-channel-enabled agents, and the nudge is best-effort. If the agent was disconnected or the hub unreachable when the job was queued, the nudge is skipped.

Fix: none needed. The agent picks the job up on its next normal poll. To get instant pickup, enable the live channel and confirm the agent shows Connected.

Where are the Vector Access troubleshooting steps?

See Vector Access troubleshooting for session errors and finding transcripts.

Quick reference

I want to…	Do this
Install the hub	Hub page > fill in the install card > Install Hub (or run the install script as root).
Turn on the live channel for an agent	Settings > Agents > edit agent > Live Channel Enabled (or the Enable button on the Hub page).
See which agents are live	Hub page roster > Connected / Enabled · waiting / Disabled.
SSH to a device through its agent	php artisan vector:access <device> (or run with no argument and pick). See Vector Access.
Record an SSH session	php artisan vector:access <device> --log. Transcript in storage/logs/vector-ssh/.
Change the SSH idle timeout	Hub page > Vector Access panel > Idle timeout (minutes, 0 = never).
Restart an agent	Hub page roster > Restart (active only when connected).
Get jobs picked up instantly	Enable the live channel. Auto job pickup is automatic.
Fix “certs missing”	Wait about a minute, or Hub page > Re-sync certificates.
Remove the hub	Run the install script with --uninstall.

What’s next

• Open SSH sessions with Vector Access →
• Add and configure Vector Agents →
• Choose an agent deployment method →
• Troubleshoot Vector agents and connectivity →