Skip to main content
Version: 2026.09

Install the agent on macOS

This page takes a macOS host from nothing to a proven agent: prepare the machine, install the agent, give it credentials, start it, then test it with Open Text. Hosts running Windows or Linux have their own pages.

Before you start, the control plane must be installed, and you need administrator rights 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 agent is distributed for Apple Silicon (arm64) hosts. No further host preparation is required beyond keeping the machine awake: the agent is meant to run continuously so users get 24/7 service, so configure Energy Saver to minimize sleeping and automatic restarts. The agent stays offline after a restart until someone starts it again.

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_macos-arm64.pkg 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, then double-click it and follow the prompts. To install from the command line:

sudo installer -pkg /PATH/TO/istari-agent_X.Y.Z_macos-arm64.pkg -target /

The install runs as root, whichever way you start it, so it asks for your password and everything it writes under /Applications/istari_agent/ is owned by root.

Where things land​

The agent installs as a version-suffixed application bundle, /Applications/istari_agent/istari_agent_X.Y.Z.app, with the executable at Contents/MacOS/istari_agent_X.Y.Z. The bundle is owned by root and readable and executable by everyone, so the agent can run under a normal account. Runtime files — logs, agent identity, and installed modules — live in ~/Library/Application Support/istari_agent, and belong to whichever account created them.

Upgrades install the new bundle alongside the old one instead of replacing it, so update whatever launches the agent to point at the new version, then delete the bundles you no longer need.

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.

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 account that will run the agent owns, and close it to everyone else:

    mkdir -p ~/.istari_digital
    mv ~/Downloads/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 ~/Library/Application Support/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: "/Users/<you>/.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: "Mac 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. Both files belong to the account that will run the agent: it derives that directory from its own home, so an agent started by a different account looks somewhere else, finds nothing, writes a placeholder file, and exits a few seconds later — see Which user owns the configuration.

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​

Run the executable inside the application bundle:

# Replace X.Y.Z with the installed version — `ls /Applications/istari_agent/` shows it
export AGENT_VERSION=X.Y.Z
"/Applications/istari_agent/istari_agent_${AGENT_VERSION}.app/Contents/MacOS/istari_agent_${AGENT_VERSION}"

Run it as the account that owns the configuration and credentials from step 3, with no sudo. The bundle is root-owned but executable by everyone, and the files the agent writes then belong to that account rather than to root.

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

Starting the agent also puts an application icon in the Dock and a menu in the macOS menu bar, because the agent builds a system tray menu unless you tell it not to. To run without any of that — the right choice on a Mac with no one logged in at the screen, or when the icon is simply unwanted — add istari_digital_agent_headless_mode to the agent section of istari_digital_config.yaml before starting:

agent:
  istari_digital_agent_headless_mode: true

To see which versions are installed, and which one is running:

ls -1 /Applications/istari_agent/istari_agent_*.app
pgrep -lf istari_agent

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 ~/Library/Application Support/istari_agent/istari_agent.log, alongside the agent's identity and module files. An agent started with sudo writes those files as root, so a later run under your own account cannot update them — sudo chown -R "$(id -un)" ~/Library/Application\ Support/istari_agent hands them back. 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 macOS.
  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​

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