Skip to main content
Version: 2026.08

Creating a New Agent with a Key

New in 2026.08.03

stari key generate followed by stari key create-agent creates a new Agent from a keypair generated on the Agent's own host. The first command writes the keypair; the second asks the Istari Digital Platform to create the Agent from it, and the Platform assigns the Agent's ID.

Because the keypair is generated on the host, the private key never leaves the machine — there is no credentials file to download and hand off. This is the CLI equivalent of Generate Key on the Agents page in the web app, which does the same thing but requires you to copy the credentials file onto the host afterwards.

Prerequisites​

Agents can only be created from a key when the Identity Service is enabled.

  • The Istari CLI is installed on the Agent's host and configured with stari client init. You do not need to be using key-based authentication yourself — an administrator still authenticating with a PAT can create the first key-based Agent.
  • istari_digital_api_url is set in istari_digital_config.yaml. It is found as the API URL in the Endpoints section under Settings > Developer Settings in the Istari Digital Platform. See --configure below for why this matters.
  • You are running as an administrator. Agents are created in the tenant of the user who creates them, so run the commands as an administrator of the tenant the Agent should belong to — see Agent Multi-Tenancy.

Creating the Agent​

Run both commands on the Agent's host:

# 1. Generate a keypair into the Agent's install folder (offline)
stari key generate --agent release

# 2. Create the Agent from that keypair and point the Agent's config at it
stari key create-agent --key-file /path/from/step/one/istari_digital_credentials.json --configure

stari key generate prints the path it wrote and the exact stari key create-agent command to run next, so you can copy it directly rather than assembling the path yourself.

stari key generate --agent writes into the install folder of the Agent for the named installation environment — for a standard install that is release, giving /opt/local/istari_agent/ on RHEL and Ubuntu, /Applications/istari_agent/ on macOS, and %LOCALAPPDATA%\istari_agent\ on Windows. On RHEL, Ubuntu, and macOS that usually requires elevated privileges. Run both commands the same way: the second command rewrites the same file, so generating it with sudo and then creating the Agent without it fails on the write.

To keep the credentials somewhere else, use stari key generate --output <path> instead and pass that path to --key-file.

What --configure writes​

--configure sets these values in the agent section of istari_digital_config.yaml, so you do not have to set them by hand (see Agent Configuration):

  • istari_digital_agent_identity_service_enabled
  • istari_digital_agent_identity_service_secret_file
  • istari_digital_agent_digital_api_url

istari_digital_agent_digital_api_url is copied from your own istari_digital_api_url. If you are still authenticating with a PAT and have only istari_digital_registry_url set, set istari_digital_api_url before running with --configure — otherwise the Agent is left without a Platform URL and you will have to add it by hand.

--configure replaces stari agent init for key-based Agents. stari agent init writes PAT credentials only.

After creating the Agent​

The command prints the new Agent's client ID, user UUID, tenant ID, key ID, and key name, and confirms that the credentials file was rewritten to the assigned client ID.

The Agent itself appears on Agents → All Agents in the web app once you start it and it registers itself. Its key is listed under the Keys tab of its detail panel, where it can also be revoked.

warning

Do not re-run stari key create-agent to retry. Each run creates a new Agent, so a second run leaves an extra, unused Agent behind.

If the Agent is created but rewriting the credentials file fails — a file-permissions error on the install folder, for example — the command prints the assigned client ID and key ID so you can repair the file by hand instead.

More details​

See the stari key generate and stari key create-agent references for the full set of options.