Agent Installation

The Agent Installation tab brings new agents into the fleet. It installs the pipeline agents (extraction, linguistic coherence (LC), and classification), which run as Docker containers on your own hosts, not inside the appliance.

Where: System Operations > Fleet Management > Agent Installation

Agents do not appear in the fleet until they have a key and have booted once. An installed agent appears on the Live Agents tab after its first heartbeat.

The tab also hosts the pipeline agent code package, the container sizing guide, and the AI Risk Pipeline bootstrap keys. They are described later on this page.

Pipeline Agents (Docker)

On a control-plane-only appliance, the compute-heavy agents do not run inside the appliance. They run on machines you supply and connect back to the console.

Host Requirements

• Docker and root access. The installer needs nothing else: no Docker Compose, Kubernetes, Java, or Python.
• Root is required because the installer writes a systemd unit to /etc/systemd/system and symlinks a CLI into /usr/local/bin and /usr/sbin. Neither location can be relocated.
• An x86_64 (amd64) CPU, openssl, and network access to the console.
• The agent directory defaults to /opt/argus-agents. To move it, set ARGUS_INSTALL_DIR and pipe the command into sudo -E bash so that sudo does not discard the variable. The value must be a plain absolute path of letters, digits, and . _ - /. A space or a % breaks every agent start.

The one-liner and the agents it installs use the console address in your browser's address bar. To give the agents a stable hostname that keeps working if the console IP changes, open the console by its DNS name (for example https://console.company.com) before you copy the one-liner.

note

If the console was installed with the Kubernetes Helm chart rather than the OVA appliance, the whole Agent Installation tab is disabled, like Agents Upgrade. The tab is greyed out with an explanation, and the generated installer refuses to run if you call it directly. In a Helm deployment, the pipeline agents are Kubernetes pods managed by the chart. You scale them by changing the pod replica count in your Helm values.

Services and Privileges

Root is needed for the install itself, but not for what runs afterward. The installer creates an unprivileged service account, argus-upgrade. The upgrade watcher (argus-agent-upgrade-watcher@<stage>.service, one per role) runs as that account. The account has no Docker access and no sudo. Its only privilege is permission to restart the installer's own services, granted by a polkit rule scoped to that account, to the restart action, and to those service names.

note

Separating those privileges needs polkit 0.106 or later with JavaScript rule support. RHEL and Rocky 8+, SUSE, Ubuntu 24.04+, and Debian 12+ have it. Ubuntu 22.04 and Debian 11 ship polkit 0.105, which ignores the rule. The installer tests the permission rather than reading a version number. Where the permission cannot be granted, the installer says so and leaves the watcher running as root. Agents and upgrades work as before, and only the watcher's privilege is unreduced. After you upgrade the OS, re-run the same command with -s -- --refresh-watcher to switch it over.

The agents run as systemd services (argus-agent@<stage>.service, one per role). systemd starts them again after a reboot and when Docker restarts. Docker no longer restarts them, so systemd is the only thing that stops or starts an agent.

Task	Command
Stop an agent until the next reboot	sudo systemctl stop argus-agent@<stage>
Stop an agent permanently	sudo systemctl disable --now argus-agent@<stage>
Restart an agent	sudo systemctl restart argus-agent@<stage>
Start an agent after Docker was stopped	sudo systemctl start argus-agent@<stage>

A plain docker stop is undone by systemd within seconds. A docker restart of the container works but restarts the agent twice. Stopping Docker itself stops the agents too. While an agent's service is stopped, the upgrade watcher leaves it alone, and an upgrade or rollback waits until the service runs again.

Ports

Each agent needs its health endpoint and its ingress port free. The upgrade watcher judges every upgrade by the health endpoint, and other agents send work to the ingress port. The agents share the host's network.

Host type	Health	Ingress
Single-role host	9100 (also the node_exporter default)	9101
Host running all three roles	Loopback address only: 19100 (extraction), 19101 (LC), 19102 (classify)	9101 (LC) and 9102 (classify). Extraction uses 9103 on the loopback address and is never sent work.

On the host's network, each agent's own analysis service also needs its port free on the loopback address: 9998 (extraction's Tika), 5019 (LC), and 5012 (classify). A service already listening there would answer in its place.

A new install checks these ports, except extraction's 9103. The check runs only where ss is installed. On a re-run the agents already hold their own ports, so the installer does not check them.

• A single-role install stops before it changes anything, and prints the port and the command to see what holds it.
• An install of all three roles stops this way only for a taken health port. For any of its other ports, it uses a private Docker network instead and says which port is taken.

Network Layout for Three Roles

A new install of all three roles goes onto the host's network when the console's agent images are a build that supports it and the ports it needs are free. Otherwise it uses a private Docker network. Health is then published on the same loopback ports, and agents on other hosts cannot send work to its LC and classify agents. The installer says which layout applies, and why, at the end.

• A re-run keeps the layout that the host's agents already have.
• To move a host from the private network onto the host's network, uninstall it with --uninstall and run the one-liner again. The agents keep their identities, because uninstalling keeps their volumes and key.
• Adding all three roles to a host that runs a single-role agent puts all three on the private network, including the existing agent. Agents on other hosts can then no longer send it work, and the installer warns you. To have all three on the host's network, uninstall the host and run the one-liner with role all.

How the Installer Works

When you run the generated one-liner on a Docker host, it performs these steps:

1. Checks the host prerequisites: running as root, Docker installed and running, openssl, an x86_64 (amd64) CPU, and a reachable console. If anything is missing, it stops with a clear message and makes no partial install.
2. Pulls the agent images from the appliance over HTTPS, using a dedicated image-pull token.
3. Generates a per-host encryption key (KEK) that never leaves the machine, creates the argus-upgrade service account, installs the systemd services and the polkit rule, and starts the agents.
4. Enrolls each agent with the console using the register-only enrollment token. The console issues each agent a unique identity, which is cached encrypted on the host. The agent then sends heartbeats and claims pipeline work.

Agents communicate with the console over HTTPS only, on port 443. Data moves directly between agent hosts, from extraction to LC to classification, and never through the appliance.

Status

The top card, External Pipeline Agents, shows:

• Enrollment — whether a credential pair has been generated (configured), and when the credentials were last rotated.
• Will install — for each stage (extraction, lc, classify), the image that the installer pulls: its version, the start of its checksum, and when the console first received it. This is the stage's Prod image. The date is the first upload, or the first boot of the appliance for an image that shipped with it. Uploading the same image again keeps the date.

no image means that there is no version to install yet: none is uploaded, or one is uploaded but not promoted (it is listed as Staged on Agents Upgrade). Installing that role, or all roles, fails until you promote one.

unknown on either line means that the console could not read the status. Reload the page to try again, but first copy any credentials shown on it, because they are shown only once.

New installs and re-runs install these versions. To change them, promote a different build on Agents Upgrade: upload it, then click Promote to Prod. Uploading alone only stages the build, and Update Selected upgrades running agents without changing what installs pull.

A re-run can move a host back to this version even if the host runs a newer build from Update Selected. Check this line before you re-run the installer on such a host.

Enrollment Credentials

Generate credentials creates two tokens and shows each plaintext value only once, so copy it when it appears. The button is labeled Rotate credentials once a pair exists, and Generate / rotate credentials while the status is unknown.

• Enrollment token — accepted only for agent registration. It cannot pull work, send heartbeats, or read anything else, so a leaked token can create an agent entry but cannot move data.
• Image-pull token — authorizes only the image download.

Keeping the two tokens separate limits what a leaked installer token can do.

Rotating invalidates the previous pair immediately.

• Agents that are already enrolled keep working, because they use their own identity.
• Any host that has not yet run the installer must use the new command.
• Rotating also revokes the image-pull token that installed hosts use to download new images. Agents Upgrade cannot update those hosts until you re-run the full installer on each one with the new command.

Install on a Docker Host

1. Select the Role for the host.
2. Copy the command. It carries the tokens only right after you generate them. Otherwise it shows <ENROLL_TOKEN> and <IMAGE_TOKEN> placeholders with an amber note. Enter the tokens you saved, or rotate the credentials to get a new pair.
3. Run the command as root on the Docker host.
4. Open the Live Agents tab and confirm that the agents show Online. Each role registers within about a minute.

Role	Result
all (default)	Runs all three agents on one host.
extraction, lc, or classify	Runs a single role. Use it to scale out a busy stage across hosts.

To push a newer image to agents that are already installed, use Agents Upgrade instead of re-running the installer.

Agent Address

Extraction agents send each file's text directly to an LC agent and a classify agent that the console picks, on any host, at the address that agent advertises. That address is the agent host's own address on the route to the console, which the installer works out. The port is 9101 on a single-role host, or 9101 (LC) and 9102 (classify) on a host running all three roles.

• Other agent hosts must be able to reach those ports. At the end, the installer prints the address and the firewall commands (firewalld and ufw).
• If that is not the address that other agent hosts use to reach this host (NAT, or a separate data network), set ADVERTISE_HOST=<this host's IP or name> before you run the command. On a host running all three roles, its own extraction agent uses that address too, so a NAT address works only if the host can also reach itself through it.
• On a single-role LC or classify host, the installer stops if it cannot work out an address and ADVERTISE_HOST is not set.
• A host running all three roles uses 127.0.0.1 instead and warns you. Only agents on the same host can reach that address.
• Extraction is never sent work, so its own address does not matter.

Earlier installers advertised 127.0.0.1 on a single-role host unless ADVERTISE_HOST was set, and kept a host running all three roles on a private network, so work handed to an agent on another host could not reach it. Re-run the installer on a single-role host to fix it. A host running all three roles must be uninstalled and installed again.

The address is worked out when the installer runs, and the agents keep using it. If the IP address of a host changes (for example, a DHCP lease), re-run the installer on that host, or set ADVERTISE_HOST to a DNS name that follows the host.

On a host running all three roles on the host's network, this matters even with no other agent hosts. Its own agents hand each other work at that address, so after an IP change every file stalls while the agents still show Online, until you re-run the installer. Give such a host a fixed address or a DHCP reservation, or use a DNS name.

To go back to an earlier console build, re-run that build's full one-liner on each agent host. Do not use --refresh-watcher, which keeps the agents' newer arguments.

Verify TLS

Verify TLS (production CA) is off by default, because the appliance ships with a self-signed certificate. With it off, the installer downloads the script with curl -fsSk and the agents do not verify the console certificate.

Turn it on only when the console presents a CA-signed certificate. The installer then verifies the certificate for both the download and the agent connections.

Re-Run, Settings, and Uninstall

The command is idempotent. Re-running it reuses the host key, skips the image download when the local image already matches, and reconciles the services.

• A re-run applies that run's settings (LC_MEM_LIMIT, ADVERTISE_HOST, and so on), so pass the same ones you installed with.
• --refresh-watcher keeps each agent's existing settings and refreshes only the watcher and the services, for the roles already installed on the host, whatever role the command names.
• LC_MEM_LIMIT takes g or m (12g, 8192m). A bare number is read as megabytes.
• CLASSIFY_MEM_LIMIT takes the same form and defaults to 3g. It sizes the classify container. The classifier runs two workers that each load a model of about 560 MB, so the earlier fixed 1 GiB was killed for lack of memory under load. Lower it only on a host that stays lightly loaded.
• The pre-flight check sums the selected roles' limits plus headroom, and refuses a host with too little RAM.
• A host carries one role set. A re-run with a role that would drop agents already installed there is refused. Installing all over a single role is allowed, but moves that agent onto the private network. To change a host's role, uninstall first.

The classify container's Docker health status (docker ps) is its classifier's. It turns unhealthy when the classifier stops answering, even while the agent still reports to the console. Earlier installers also started a second copy of the classifier in that container. Re-run the installer on such a host to drop it.

To uninstall, append -- --uninstall to the piped command, as in ... | sudo -E bash -s -- --uninstall. It stops and removes every agent on the host, whatever role the one-liner names, plus the systemd services, the helper scripts, the polkit rule, and the argus-upgrade account. It keeps the host key and the named volumes that hold each agent's identity, so a later re-install is recognized as the same agent.

If sudo Refuses -E

If sudo returns sorry, you are not allowed to preserve the environment, your sudoers policy grants specific commands rather than ALL. Stock distribution policies are not affected, but hardened or config-managed estates can be. Use one of these options, in order of preference:

1. No overrides set — use plain | sudo bash. The -E option carries ARGUS_INSTALL_DIR, AISEC_KEK_FILE, ADVERTISE_HOST, LC_MEM_LIMIT, CLASSIFY_MEM_LIMIT, and HEARTBEAT_INTERVAL_SEC. If you set any of them, including ADVERTISE_HOST, do not use this option, or they are silently dropped and the installer uses its defaults.

2. Overrides set, and env is permitted — use sudo env VAR=… VAR=… bash to pass every override you set, not only the install directory.

3. Overrides set, and only bash is permitted (for example NOPASSWD: /bin/bash) — option 2 fails too. Download the script instead of piping it, set the values at the top, and run it:

   curl -fsSk "<the URL the console gave you>" -o install.sh
   sed -i 's|^INSTALL_DIR=.*|INSTALL_DIR="/your/path"|' install.sh
   sed -i 's|^KEK_FILE=.*|KEK_FILE="/your/kek/path"|' install.sh
   sudo bash install.sh

   Edit a line for every override you would have exported. Missing one is not harmless: leaving KEK_FILE at its default on a host installed with AISEC_KEK_FILE makes the installer create a new key, and every agent on that host loses its cached identity and registers again as a duplicate.

Installer Result

The installer ends with Done only once every agent it installed has started. If an agent cannot start at all (for example, Docker cannot create its container, or the service refuses to take over a same-named container it did not create), the installer ends with ERROR: the <role> agent did not start and prints the journalctl -u argus-agent@<role>.service command that shows why. The rest of the host is set up by then, so fix the cause and re-run the same command.

The installer does not wait for the agents to become healthy. The LC agent's model load can take minutes.

Pipeline Agent Code Package

The Python Pipeline Agent Package card is where you upload new code for the pipeline agents (extraction, LC, and classify).

1. Prepare a ZIP file that contains manifest.json and the agent code. The manifest's target is all (every stage), common (only the shared library), or a single stage.
2. Upload the ZIP and enter its version. The version is required.

The card shows the hosted version, or "No package uploaded".

Agents poll the hosted version on each heartbeat. When the uploaded version is newer than what an agent runs, the agent downloads it, replaces its code, and restarts.

The package upgrades application code only. Sidecar workloads (Tika, the LC scorer, and presidio) ship in the agent image. To change them, roll out a new image on Agents Upgrade.

Container Sizing

The Python Pipeline Container Sizing card lists reference Kubernetes requests and limits for each pipeline stage.

AI Risk Pipeline Agent Bootstrap Keys

The AI Risk Pipeline — Agent Bootstrap Keys card holds the console URL and the three bootstrap registration keys that the data-classification containers (Extraction, Linguistic Coherence (LC), and Classify) read on first boot.

Field	Purpose
Console URL	Where the containers reach the console. On Docker Desktop use host.docker.internal. On Linux use the host's LAN IP.
Extraction Agent Key	Bootstrap token for the Extraction stage.
Linguistic Coherence Agent Key	Bootstrap token for the LC stage.
Classify Agent Key	Bootstrap token for the Classify stage.

Each key field has an eye toggle to show or hide the value.

A bootstrap key authenticates a container the first time it registers. After registration, the agent stores its own per-instance key at /var/lib/argus/agent.key and ignores the bootstrap value.

Each of the three keys also appears as a row in Settings > Security > API Token Management, named pipeline-extraction, pipeline-lc, and pipeline-classify. This card mirrors those tokens. Auto-mint also creates a second key for each stage (pipeline-extraction-2, pipeline-lc-2, and pipeline-classify-2), which the card does not show. See Security Settings.

Buttons

• Auto-mint missing keys — creates any stage key that is not yet set (up to six: the three shown here plus the second key for each stage), saves them at once, writes data/pipeline-agents.env, and reloads the fields with the new values. Use it for a first-time setup instead of generating each key by hand.
• Save — writes the console URL and the three keys, and writes data/pipeline-agents.env. On success, the card shows "Saved."

You can also paste keys that were created elsewhere with POST /api/agents/keys instead of auto-minting.

Workflows

Bring Up the AI Risk Pipeline Classification Agents

1. In AI Risk Pipeline — Agent Bootstrap Keys, set the Console URL that the containers use.
2. Click Auto-mint missing keys to fill the three stage keys, or paste your own.
3. If you pasted your own keys, click Save. This writes the keys and data/pipeline-agents.env. Auto-mint has already saved its keys.
4. Start the pipeline containers. They register on first boot and then store their own per-instance keys.

Troubleshooting

• A pipeline-agent host misbehaves (agents offline, upgrades stuck or rolling back, or a Docker host after an OS or credential change) — Superna support can run a host check script on it, as root. The script checks the upgrade account and its permission, whether the console still accepts the host's credentials, each agent's service, container, and health, pending or failed upgrades, and leftover image files. For each problem, it says what to do. It changes nothing on the host unless it is asked to run its restart checks.
• Pipeline containers do not register — confirm that the Console URL is reachable from inside the container (host.docker.internal on Docker Desktop, the host LAN IP on Linux) and that the three bootstrap keys are saved.
• Upgrades stay on Pending — see the troubleshooting section on Agents Upgrade.