Headless agents
An AI agent with no person at the keyboard holds a key of its own, enrolls without a browser, and has a destructive command denied by your policy.
- Who
- Admin
- Where
- Console or strazactl, and a terminal on the agent's machine
In short
An AI agent with no person at the keyboard gets an identity of its own and an Ed25519 key, which the Straza background service on its machine holds, so the private half never reaches the agent. An admin registers the public key, the agent enrolls with no browser, and straza exec puts each command it runs under your policy.
On this page
You give an AI agent that runs with no person at the keyboard, such as a build job or an always-on service, a key of its own. You work as the admin on the server, and in a terminal on the agent’s machine. At the end, the agent enrolls without a browser, and your Straza policy has denied it a destructive command.
straza service, the Straza background service on the agent’s machine, holds the agent’s Ed25519 key, and you register the matching public key on the agent’s identity. At each session start the service checks in without a device or a browser, with a fresh proof from that key, so the session token is bound to it. The ID token that check-in carries comes from an assertion the key signs, which the service signs again once the ID token it holds runs out. That ID token names the key it was issued for, so the server refuses it once you replace or remove the key, and refuses a check-in proof from any other key. The agent’s own files and environment hold no key and no token, so there is nothing long-lived for the agent to copy.
Before you start
- The
strazabinary on the agent’s machine, a Linux, macOS or Windows machine, withstraza servicerunning. Run the service under an OS account other than the agent’s, as the sandbox and the demo stack do with a service container of their own, so the agent cannot read its key. Thestrazapackage for Linux does that too, because it runs the service under the straza-service OS account, as Install shows. On Windows the service always runs under its own OS account, as the Windows service that Install sets up, and on a Mac the Straza package for macOS runs it under its own OS account, as Install shows. On a Linux or macOS machine with no system service and no managed install, a service the agent’s own user starts withSTRAZA_HOMEset works too, and then the key sits where the agent can read it. - An admin’s console sign-in, or
strazactlon an admin API token inSTRAZA_API_TOKEN, minted in the console as Mint an admin API token shows. - A role to assign the agent. The example assigns the role
developer, which the demo stack seeds onhttp://127.0.0.1:8420. A fresh enterprise server holds no such role and no PolicySet, and it denies every local tool that no rule allows, so an admin first creates the roles and the PolicySet of Give agents their local tools. A standalone server has nodeveloperrole, and the agent needs none there, because the seededstandalone-starterPolicySet governs every identity, one with no roles included. - For the
curlcalls, an admin API token inADMIN_API_TOKEN, minted withstrazactl api-token create --name docs --scope identity:read,identity:write. The token belongs to a person and never to the agent, because an AI agent is refused on every admin route, whatever role it holds.
Create the agent identity
When an identity manager feeds your server, it creates the identity and gives it its roles, as AI agents as identities shows. In that case, start at Generate the agent’s key. Assigning a role here whose membership the identity manager writes is drift, and the identity manager’s next full write of that role’s membership removes it.
CLI onlyThe console has no way to add a user, because identities arrive over SCIM or through
strazactl.Otherwise, create an agent user yourself. The
kindisnhi, the same signal the identity manager carries over SCIM. Setuser_typetoagentfor an AI agent that acts for a person, or toservicefor a technical account with no agency. When the field is left out, the server storesagent.curl -s -X POST http://127.0.0.1:8420/v1/admin/users \ -H "Authorization: Bearer $ADMIN_API_TOKEN" -H 'Content-Type: application/json' \ -d '{"username":"build-bot","kind":"nhi","user_type":"agent","display":"Build bot"}'You should see
The new identity’s
id, which the key step needs.{"id":"01a15d8e-8320-768e-81ea-8a38ddf6fa7d","username":"build-bot","status":"active","kind":"nhi"}The response is trimmed here to those four fields.
strazactl users create-nhi build-bot --type agentcreates the same identity from a terminal. A standalone server has no identity manager feeding it, so one of these two is how its agent identities are made.Assign the agent a role
On the Users screen, open build-bot’s sheet, pick the role under Assign, press Assign role, and confirm.
- Users
- build-bot
- Assign
- developer
- Assign role
- Assign role
You should see
build-bot holds developer now.Put an admin API token that holds
identity:readandidentity:writeinSTRAZA_API_TOKEN.strazactl assign developer --user build-botYou should see
assigned developer to build-botThe identity then shows
effective_roles["demo-tools-sandbox","developer","midpoint-self-service","views-demo-tools"], becausedevelopercomposes the other three. With the starter of Give agents their local tools on an enterprise server, they aredeveloperand thelocal-toolsit composes. On a standalone server, skip this step, or assign a role you created withstrazactl roles create.Generate the agent’s key
CLI onlyThe key is made in a terminal on the agent’s machine.
On the agent’s machine, run
straza keygenas the agent’s user. The service makes the key and keeps the private half in its state directory, so the private half never reaches the agent. The command prints the public half and the exact registration line an administrator runs. A second keygen for the same user is refused until you add--force, because a new key stops the registered one from working.straza keygen --user build-botYou should see
The public key, and the
strazactl users nhi-key setline that registers it.NHI key generated (the Straza background service holds the private half). Public key: huw3t4+Vrf69fExt1wBKWkQB9bZMD+eSAVsCs03+cTc= An administrator registers it with: strazactl users nhi-key set build-bot huw3t4+Vrf69fExt1wBKWkQB9bZMD+eSAVsCs03+cTc= (or: PUT /v1/admin/users/{id}/nhi-key {"public_key":"huw3t4+Vrf69fExt1wBKWkQB9bZMD+eSAVsCs03+cTc="}) Then enroll headless: straza enroll --server <strazad-url> --headless --user build-botOn a machine with a managed install, the last line leaves out
--server, because the managed configuration names the server and the service enrolls there.If this fails
A key for you already exists on this machine. Run `straza keygen --force` to replace it, and then have an admin register the new public key, because the old one stops working.- The agent’s user already has a key with the service. Keep it, or replace it with
--forceand register the new public half. This OS account holds a person's enrollment on this machine, so an agent's key or enrollment cannot replace it. Only `straza enroll` replaces a person's machine key. Run the agent under its own OS account.- A person enrolled this OS account. If an agent’s key could replace that enrollment, an agent that runs as the person could unenroll the person’s machine. So neither
straza keygen, with or without--force, norstraza enroll --headlessruns here, and no command removes a person’s enrollment. Create an OS account for the agent and run its commands there, or have an administrator hand this account to the agent, as Hand an enrolled OS account to an agent shows.
Register the public key
Register the public half on the agent’s identity. Each agent has one key, so registering again rotates it. A human identity is refused outright.
On build-bot’s sheet, the Assertion key section says
Cannot start a session until a key is registered.Press Register key, paste the public key under Public key, base64, 32 bytes, and press Register key again.- Users
- build-bot
- Register key
- Register key
The Assertion key section of build-bot, with the public key pasted and Register key. Show the whole screen You should see
The assertion key of build-bot is registered.The section then showsregisteredand the key’s fingerprint.Run the
strazactl users nhi-key setline that keygen printed, or call the API with the identity’sid:curl -s -X PUT http://127.0.0.1:8420/v1/admin/users/01a15d8e-8320-768e-81ea-8a38ddf6fa7d/nhi-key \ -H "Authorization: Bearer $ADMIN_API_TOKEN" -H 'Content-Type: application/json' \ -d '{"public_key":"huw3t4+Vrf69fExt1wBKWkQB9bZMD+eSAVsCs03+cTc="}'You should see
"status":"set"and the identity’s id.{"status":"set","user_id":"01a15d8e-8320-768e-81ea-8a38ddf6fa7d"}A
GETon the same path reports the posture,registered: truewith the created time and asha256:fingerprint, and never the key itself.Enroll the agent
CLI onlyEnrolling runs on the agent’s machine.
Enroll headless on the agent’s machine, as the agent’s user. There is no browser and no device. The service proves the key works by minting a token, pins the keys that verify policy snapshots, and keeps the enrollment beside the key.
straza enroll --server http://127.0.0.1:8420 --headless --user build-botYou should see
Enrolled headless as build-bot., followed by a sentence that the Straza background service holds this agent’s key and starts each of its sessions.Enrolled headless as build-bot. The Straza background service holds this agent's key and starts each of its sessions.If this fails
straza: the identity provider refused the agent's sign-in (invalid_client): the key that signed the request is not the key registered for build-bot. On the agent's machine, run `straza keygen --force --user build-bot` to make a new key. Have an admin register the public key it prints, with `strazactl users nhi-key set` or in the console. Then run `straza enroll --server http://127.0.0.1:8420 --headless`. Check the registered key or client, and that the user is an active agent- The service on this machine holds a different key from the one registered for build-bot, for example after
straza keygen --forcewithout a new registration. Make a new key, register it, and enroll again.
Prove a governed call
CLI onlyThe proof runs on the agent’s machine.
Run one safe and one destructive command through the wrapper. The session starts from the key with no interaction.
straza exec -- date straza exec -- rm -rf /tmp/probeYou should see
The date, then the policy’s reason for the deny. The
rm -rfline exits 2.Sat Sep 19 10:33:01 UTC 2026 Straza: destructive command denied by the agent guardrailsAgainst a standalone server, the denied line carries the reason of the seeded
standalone-starterPolicySet,Straza starter policy: this sample rule denies commands that start with rm -rf. Delete files individually, or an admin can edit the standalone-starter PolicySet.On the demo stack, the always-onagent-samcontainer runs as the AI agentsam-sre-agentand enrolls the same way at boot, through a service container of its own. Its logs show the signed assertion accepted, a session bound to the service’s key, and a destructive command denied with the same reason.Check the agent’s setup with the doctor.
straza doctorYou should see
An
enrollmentline that namesbuild-bot (AI agent, no device)with the server and the start of the key’s thumbprint.An agent has no device, because the key mints each token.
straza statusshows each live session once a call has run.
Hand an enrolled OS account to an agent
A person’s enrollment stays with their OS account, and no command removes it. To run an agent in an OS account that a person enrolled, such as a build account someone once enrolled by hand, an administrator of the machine clears that account’s folder in the state directory of straza service:
- In that OS account, run
straza statusand wait until itsauditline readsnothing waiting to upload, because the folder holds the audit records the service has not uploaded yet. - Revoke the person’s device on the server with
strazactl devices revoke <username> <device-id>. Theidentityline ofstraza statusnames the device, andstrazactl devices list <username>lists them all. - Stop the service, delete the account’s folder, and start the service again, with the commands for your system below.
On Linux, id -u build prints the uid of the OS account, here build with the uid 1001. Stop the socket as well, because a connection to it starts the service again.
sudo systemctl stop straza-service.socket straza-service.service
sudo rm -r /var/lib/straza-service/u/1001
sudo systemctl start straza-service.socket
id -u build prints the uid on a Mac too, here 502.
sudo launchctl bootout system/ai.straza.service
sudo rm -r /var/db/straza-service/u/502
sudo launchctl bootstrap system /Library/LaunchDaemons/ai.straza.service.plist
On Windows the folder is named for the SID of the Windows account. In an elevated PowerShell, print it first, with DOMAIN\build in place of build for a domain account:
(New-Object System.Security.Principal.NTAccount('build')).Translate([System.Security.Principal.SecurityIdentifier]).Value
Then remove the folder of that SID, here S-1-5-21-1004336348-1177238915-682003330-1001:
Stop-Service straza-service
Remove-Item -Recurse C:\ProgramData\straza-service\u\S-1-5-21-1004336348-1177238915-682003330-1001
Start-Service straza-service
Check the uid or the SID before you delete, because each folder there holds one account’s enrollment. When the person started the service themselves with STRAZA_HOME, stop that service and delete $STRAZA_HOME/service/u/<uid> instead. The account then holds no enrollment, and straza status in it reports it as not enrolled. Generate the agent’s key there and enroll it, as the steps above show.
Retire the agent
To retire the agent, soft-delete the user with DELETE /v1/admin/users/{id}. Neither the console nor strazactl has this. The delete revokes its sessions, ends its assignments, and removes its assertion key and per-user OAuth grants, with audit records for the changes.
The delete, the end of the assignments, the revocation record and the event that tells the other servers commit as one write. When the database refuses it, nothing changes, and the answer says so.
If this fails
user build-bot was not deleted: Straza could not write the delete to its database, so nothing changed. This server already refuses the user, and the other servers still treat the user as before. Run the delete again. Without a saved delete, this server's refusal lasts until it restarts, or until strazactl users unlock build-bot lifts it. The strazad log names the cause under request id REQUEST-ID.- Send the same request again once the database answers, and look up REQUEST-ID in the strazad log for the cause. A later status change does not lift the server’s refusal, because the user still reads active. When the answer instead says Straza could not tell whether its database saved the delete, read the user back first: a deleted user answers 404.
To end the agent’s sessions and stop new ones, and keep the identity, revoke only the key.
- Users
- build-bot
- Revoke key
- Revoke key
The dialog says The running sessions of build-bot end now, and it can no longer mint sessions with the client_credentials grant.
strazactl users nhi-key unset build-bot
The API form is DELETE /v1/admin/users/{id}/nhi-key.
Revoking the key ends the sessions that already run, with one session.end record each. The service still holds the agent’s last ID token, but the server refuses it, because the token names the removed key, and the service then cannot get a new one. Registering a different key ends the running sessions the same way. After straza keygen --force on the agent’s machine and the registration of its new public key, run straza enroll --headless there again, and the agent starts new sessions with the new key. To stop the agent’s access on every lane at once, lock the user, as the Kill-switch runbook shows.
Protect the key
The key in the service’s state directory is the agent’s durable secret. Protect that directory and its backups as you would a password, and rotate the key with straza keygen --force and a new registration. Humans are excluded from this grant on purpose, so a stolen key can never become a password-equivalent human login.
An enterprise server offers two ways to enroll an agent. One is a per-agent key at the built-in issuer, as on this page, which needs no identity-provider step. The other is the identity provider’s own client-credentials grant, with a client id and secret, and then that secret is the durable credential. The service reads it from a file that only the service can read, agent-<uid>.json with client_id and client_secret, named by the agent’s uid. That file sits in the directory systemd names in CREDENTIALS_DIRECTORY, or else in credentials/ under the service’s state directory. The service never reads it from the agent’s environment, and it makes a key of its own for the proofs that bind each session. A standalone server has only the key, because the built-in issuer is the only issuer there.
On a machine with the straza package, an administrator passes that file to the service with a systemd drop-in. Put the JSON in a file only root can read, here /etc/credstore/agent-1001.json for an agent whose OS account has the uid 1001, which id -u prints in the agent’s shell. Then run sudo systemctl edit straza-service, add the lines below, and run sudo systemctl restart straza-service. systemd copies the file into the service’s credentials directory each time it starts the service, where the agent’s account cannot read it.
[Service]
LoadCredential=agent-1001.json:/etc/credstore/agent-1001.json
On Windows an administrator puts the file in C:\ProgramData\straza-service\credentials, named for the SID of the agent’s Windows account, such as agent-S-1-5-21-1004336348-1177238915-682003330-1001.json. whoami /user in the agent’s own PowerShell prints that SID. Files there take the folder’s access rules, so only the service, SYSTEM and Administrators can read them.
An agent that an older Straza client enrolled kept its key in a file of its own home or its client secret in its environment. A standalone server still accepts that agent’s check-in without a proof. An enterprise server refuses it with a sentence that starts Straza refused this session because the user and says to enroll the agent with a current straza service. After you update Straza on the agent’s machine, run straza keygen through the service and have an admin register the new public key with strazactl users nhi-key set, which replaces the old one. Rotate every identity provider client secret that sat in an agent’s environment.
Next
- AI agents as identities provisions agents from your identity manager.
- Hookless processes runs the agent inside the sandbox image, where the wrapper is the only way to run a process.
- Who may draft and publish shows how an agent proposes a config change. It uses the drafting tools of the built-in
strazaapp, which the gateway lists to holders of thestraza-draft-configrole, and a person publishes the draft. - People, agents and sponsors explains the identity model behind people and agents.
Walked on v1.0.0-1570-gaf326165-dirty on 2026-10-21, except the console forms, the session end at a key change, the fresh enterprise server and the OS account handoff, none walked.
An Alpine 3.20 container against a standalone server, both built from a development working tree before its commit, where straza service ran with STRAZA_HOME in the agent's home directory, every curl and strazactl step ran with the page's admin API token, the assign step ran on a developer role made with strazactl roles create, and keygen, the headless enrollment, both wrapper calls and doctor ran through that service. The key revoke was run on 2026-10-06 at v1.1.0-117-g106081a8. The sentences that say a key change ends the agent's sessions and that the server refuses an ID token issued for an old key were written from the code on 2026-10-27 and not walked. The console forms were checked against the console's source and not clicked, and the demo stack's role list was read there and its guardrails reason and wrapper output come from its seed policy and the walk of 2026-09-19, because the demo stack takes no writes. The sentences on a fresh enterprise server and the section that hands an enrolled OS account to an agent were written from the code on 2026-11-01 and not walked. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.