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 agent 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 need to 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.

The first three steps below need an administrator of the tenant this agent will serve: a Tenant Administrator or Platform Administrator (on installations without tenant management, an organization administrator). If you are not one, ask one to do them.

1. Sign in to the web app in the tenant the agent will serve. The agent joins the tenant you are signed in to when you generate its key; Agent Multi-Tenancy covers installations with more than one tenant.

2. Open Agents and select Generate Key. In the New Agent Access Key dialog, enter an Agent name (optional) if you want one, then select Generate. This one action registers a new agent identity on the platform and issues the key the agent will use. The agent appears under All Agents only after you start it in step 4. The name you entered labels the key. The agent's name under All Agents is assigned by the platform, unless you set your own as described in Confirm it registered.

3. 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.

   Send the key file securely

   If someone else installs the agent, send them this file as securely as you would a password. It holds the agent's private key: anyone who has the file can act as the agent, and the web app cannot show the key again.

4. 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

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

6. 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

Ask an administrator of the agent's tenant to check that the same name appears under All Agents in the web app. If it does, the agent reached the platform.

If the name does not appear, 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.

Choose the agent's name from the host

Set istari_digital_agent_display_name under agent: in istari_digital_config.yaml and restart the agent. All Agents then shows that name, and the log reports it.

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.