Install the agent on Linux

This page takes a RHEL or Ubuntu host from nothing to a proven agent: prepare the machine, install the agent, give it credentials, start it — including running it under systemd so it survives logout — then test it with Open Text. Hosts running Windows or macOS have their own pages.

Before you start, the control plane must be installed, and you need sudo on the host and an administrator account in the Istari Digital Platform. You download the agent package from the Customer Portal and create the agent's key in the web app, so have both open. Plan about an hour.

Where a filename contains X.Y.Z, substitute the agent version you downloaded. Angle brackets mark values you supply.

1. Prepare the host

The host should run one of:

• RHEL 9
• Ubuntu 22.04 LTS

On Ubuntu, install the agent's prerequisite first:

sudo apt-get update && sudo apt-get install -y libmpv1

The agent is meant to run continuously so users get 24/7 service, so configure the host to minimize sleeping, hibernation, and automated shutdowns and restarts. Running the agent under systemd is what keeps it available across logouts and reboots.

If outbound traffic on this host must pass through a forward proxy, or the firewall blocks direct access to object storage, set the proxy before you start the agent — see Proxy configuration.

One agent can host any number of modules, and modules add requirements of their own. Check each module's Prerequisites before you commit to a host.

2. Install the agent

Download istari-agent_X.Y.Z_amd64.rpm or istari-agent_X.Y.Z_amd64.deb from the Istari Customer Portal — choose the agent assets under dist, open Asset details, then Download. See Download Istari software from the Customer Portal.

Copy the package onto the host and install it.

On RHEL:

sudo rpm -i /PATH/TO/istari-agent_X.Y.Z_amd64.rpm

On Ubuntu:

sudo dpkg -i /PATH/TO/istari-agent_X.Y.Z_amd64.deb

Either way the agent installs to /opt/local/istari_agent/, owned by root. The binary is executable by everyone, so the agent itself can run under a service account.

3. Give the agent its credentials

The process you install in step 2 is not yet known to the platform. You register it from the web app at the same time as you give it a key to sign in with — there is no separate “create agent” form, and you do not pick a name or ID first.

Decide first which account will run the agent — your login, a dedicated service account, or root for a systemd unit with no User=. Everything below belongs to that account, because the agent looks for its configuration in that account's home directory.

1. Open Agents in the web app (organization administrators only). Select Generate Key. In the New Access Key dialog, optionally enter a Key name (a label for you, not an identifier), then select Generate. That one action registers a new agent identity on the platform and issues the key the host will use. The agent does not appear under All Agents until this host starts in step 4.

2. Select Download credentials while the key is on screen. The browser saves agent-credentials-<key id>.json, which holds the private key and is shown only once — losing it means generating another key.

3. Copy that file onto the host, into a directory the agent's account owns, and close it to everyone else:

   mkdir -p ~/.istari_digital
   mv /PATH/TO/agent-credentials-<key id>.json ~/.istari_digital/
   chmod 600 ~/.istari_digital/agent-credentials-<key id>.json

4. Copy your platform's API URL from Settings → Developer Settings → Endpoints in the web app.

5. Create ~/.config/istari_digital/istari_digital_config.yaml as that same account, with the URL and the path to the file you just moved:

   default: {}
   agent:
     istari_digital_agent_digital_api_url: "https://api.example.istari.app"
     istari_digital_agent_identity_service_secret_file: "/home/<account>/.istari_digital/agent-credentials-<key id>.json"
     istari_digital_agent_identity_service_enabled: true
     # Optional. Name shown under All Agents; omit it and the platform assigns one.
     # istari_digital_agent_display_name: "Linux lab 01"

The configuration stores the path to the credentials file rather than its contents, so the agent reads it on every start and fails if the file moves. An agent that reads a different account's configuration finds nothing, writes a placeholder file, and exits a few seconds after starting — the most common failure on Linux, where a systemd unit runs as root while the operator set the file up under their own login. See Which user owns the configuration, and set User= in the unit to match.

The clientId inside the credentials file is the agent's Client ID, the identity it presents when it authenticates. Which identifier is which separates it from the Agent ID and the other values you will meet, and Agent keys covers rotating a key later or migrating an agent off a deprecated PAT.

4. Start the agent

/opt/local/istari_agent/istari_agent_X.Y.Z

Start it as the account that owns the configuration and credentials from step 3. If any module on this host requires environment variables, make sure they are set in that shell: modules run as child processes of the agent and read its environment.

On a host with no desktop session, turn on headless mode first. The agent builds a system tray menu at startup unless told otherwise, which needs a GUI to exist — so a server, an SSH session, or a systemd unit all want this in the agent section of istari_digital_config.yaml:

agent:
  istari_digital_agent_headless_mode: true

See istari_digital_agent_headless_mode.

The agent may take up to a minute to start, and prints its log output to the terminal.

Run the agent as a service

Running the agent from a terminal stops it when the session ends. For a host that should serve jobs continuously, run it under systemd — the .deb and .rpm packages ship a unit file at /etc/systemd/system/istari-agent.service:

sudo systemctl daemon-reload
sudo systemctl enable --now istari-agent
sudo systemctl status istari-agent

Two things to check when you set the service up:

• Run the service as the account that owns the configuration. A unit with no User= directive runs as root and looks for the configuration in /root/.config/istari_digital/. Either set User= to the account you set up in step 3, or put the configuration and credentials in root's home.
• Enable lingering for that account, so its runtime directory exists when nobody is logged in: sudo loginctl enable-linger <user>. Without it, /run/user/<uid> disappears at logout and jobs fail with Permission denied: '/run/user/<uid>'.

Modules that need environment variables get them from the unit, through Environment= or EnvironmentFile=.

The unit's ExecStart points at a version-suffixed binary (/opt/local/istari_agent/istari_agent_X.Y.Z), so after upgrading the agent package, update that line to the new version and run sudo systemctl daemon-reload before restarting.

5. Confirm it registered

On a successful start the log records the name the platform assigned, for example:

INFO - Got display name 'iconic-morgoth-9091' from server

An organization administrator should see that same name under All Agents in the web app. That is how you know the host reached the platform.

To choose the name instead of a platform-assigned one, set istari_digital_agent_display_name under agent: in istari_digital_config.yaml and restart the agent. The log then reports the name you set.

If it does not, read the log at ~/.local/share/istari_agent/istari_agent.log. Under systemd, sudo journalctl -u istari-agent -n 50 shows the same output, plus anywhere the unit's StandardOutput= sends it. Common failure modes are in Troubleshooting.

6. Test with an open-source module

Prove this agent can run a job before you add licensed tools. Open Text needs no commercial license and no module YAML keys, and it runs on Windows, Linux, and macOS.

1. Install and authenticate stari if it is not already on this host.
2. Deploy Open Text (portal name textract) following the Module deployment instructions.
3. In the web app, upload a small .txt (or .csv) file.
4. Run @istari:extract with tool Open Text. Set Operating system to match this host (Linux).
5. When the job completes, open the artifacts (extracted text and metadata report).

If the job stays pending, the agent OS or installed modules do not match the job — see How agents match jobs. Then add Open PDF and Open Spreadsheet the same way if the team needs everyday documents.

Next steps

• Agent configuration reference for every configuration key, including module configuration and log level.
• Proxy configuration if outbound traffic must pass through a forward proxy.
• Agent multi-tenancy if this host serves more than one tenant.

If you get stuck, contact support@istaridigital.com.