On-prem collector

Install the read-only on-prem agent

A small, outbound-only collector for vendors with no cloud API — IBM, Oracle, and VMware. It reads a local export, validates it, and posts it to your tenant over HTTPS. It exposes no inbound ports and runs one cycle then exits.

Security posture

Minimal, auditable, least-privilege

Read-only at the source — never writes, mutates, or deletes anything in your environment.
Outbound-only — no inbound ports. Exactly one call: an HTTPS POST to your INGEST_URL.
Scoped token — write-to-ingest-only, expirable, revocable, read once and never logged.
Bounded + validated locally — record shapes and a 50,000-record cap are checked before anything leaves your network.

How you get it

Provided when you activate on-prem

Your RenewalIntel contact provides the collector image when you activate on-prem collection. It ships as a non-root container intended to run with a read-only root filesystem (docker run --read-only). Wherever you see <image-provided-at-onboarding> below, use the image reference you were given.

Prerequisites

Three things before you run

An agent token — mint one in Settings → Agent Tokens (owner/admin). It is shown once; store it in your secret manager.
A read-only JSON export of your inventory (see the export shapes below).
Docker (or Node ≥ 20 if you were provided the Node bundle).

Configure

Environment variables

Variable	Required	Default	Notes
INGEST_URL	yes	—	Full URL of /api/agent/ingest. Must be https:// (except localhost).
AGENT_TOKEN	yes	—	agt_<64 hex> minted in Settings → Agent Tokens.
SOURCE_FILE	yes	—	Path to the read-only JSON export.
SOURCE_TYPE	no	ilmt	Vendor source: ilmt, oracle-installations, or vmware-hosts.
AGENT_RUN_ID	no	content hash	Idempotency key. Default derives from the data, so an unchanged re-run is deduped.
DRY_RUN	no	false	true validates + prints without sending.
MAX_RETRIES	no	4	Retries for 429/5xx/network with exponential backoff.
TIMEOUT_MS	no	30000	Per-request timeout.

Run

Validate, then send

# Validate locally first — prints the result, sends nothing
docker run --rm --read-only \
  -e INGEST_URL=https://app.yourco.com/api/agent/ingest \
  -e AGENT_TOKEN=agt_… \
  -e SOURCE_TYPE=oracle-installations \
  -e SOURCE_FILE=/data/oracle-installations.json \
  -e DRY_RUN=true \
  -v /path/to/exports:/data:ro \
  <image-provided-at-onboarding>

# Then run for real — drop DRY_RUN
docker run --rm --read-only \
  -e INGEST_URL=https://app.yourco.com/api/agent/ingest \
  -e AGENT_TOKEN=agt_… \
  -e SOURCE_TYPE=oracle-installations \
  -e SOURCE_FILE=/data/oracle-installations.json \
  -v /path/to/exports:/data:ro \
  <image-provided-at-onboarding>

Exit 0: Success — ingested, deduped, or dry-run validated.
Exit 1: Runtime failure — source unreadable, ingest rejected (4xx) or unreachable.
Exit 2: Configuration error — missing/invalid environment.

On success it prints a JSON summary to stdout — { agentRunId, vendorType, sourceType, records, dryRun, result } — and structured logs to stderr.

Schedule

Cron, CronJob, or systemd timer

The collector runs one cycle and exits, so schedule it however you like. An unchanged export re-run is deduped server-side, so overlapping or repeated runs are safe.

# crontab — run nightly at 02:00, one cycle then exits
0 2 * * *  docker run --rm --read-only \
  -e INGEST_URL=https://app.yourco.com/api/agent/ingest \
  -e AGENT_TOKEN=agt_… -e SOURCE_TYPE=vmware-hosts \
  -e SOURCE_FILE=/data/vmware-hosts.json \
  -v /srv/exports:/data:ro <image-provided-at-onboarding>

Export shapes

One JSON shape per vendor

SOURCE_TYPE	Vendor	Export shape	What leaves your network
ilmt	IBM	{ entitlements, deployments }	product names, PVU quantities, host names, processor arch, core counts
oracle-installations	Oracle	{ installations }	product/version, host + cluster names, sockets/cores, core-factor licenses, options in use
vmware-hosts	VMware	{ hosts }	host/cluster/datacenter names, CPU model, sockets/cores, memory, VM counts, ESXi version

Oracle and VMware are inventory-only: the agent sends what is deployed; the matching entitlements come from contracts you upload in the app, not the agent. Point your existing tooling — ILMT, Oracle LMS, or vCenter / RVTools — at the documented shape via a small adapter. Native CSV/API adapters are a later slice.