Skip to the content

Keep agent versions in check

List your installed agents against the versions AgentGarm verified their hooks for, and bring an agent that updated past that range back in range.

Steps marked preview rely on a package that has not passed its release gate.

List the agents installed on your machine with the version AgentGarm verified each one's hooks against, see what happens when an agent updates past that range, and bring it back in range. Agent hook APIs change often, so a version AgentGarm has not checked lowers the assurance of every task that runs it.

1. List your installed agents

agentgarm agents finds every agent executable with an AgentGarm adapter on your PATH and prints its version, its status, its hook tier and its path. The version is read from the install path or the npm package.json, never by running the agent: running an unsandboxed agent to ask its version would be the very code execution the launcher exists to contain. --json prints the same with each agent's verified range, for scripts.

agentgarm agents
agentgarm agents --json

Checked by the walk: these commands ran as written on a no-root Linux install.

2. Read the status of each agent

supported is inside the range the adapter was verified against. newer than verified and older than supported are drift: the agent's hook contract may have changed, and agentgarm agents exits 1 so a script can stop on it. version unknown is shown but does not change the exit code. The hook tier is C today for every agent: no adapter records a live run against a real agent yet, so none is rated higher. In --json, each agent has support, a drift flag and its verified_range, so a script can list only the agents that drifted.

agentgarm agents
agentgarm agents --json | jq -r '.[] | select(.drift) | "\(.agent) \(.version) (verified \(.verified_range))"'

Checked by the walk: this command ran as written on a no-root Linux install, and the output showed supported.

3. See what drift does to a task

When agentgarm run launches an agent that is newer than verified, older than supported, or whose version cannot be read, it says so on stderr and reports CLI drift to agentgarmd before the agent starts; the launch goes ahead at a lower assurance. agentgarmd also reads the agents it governs at start and every 10 minutes, so an agent that updates itself while running raises the same alert and lowers its live tasks. agentgarm status shows each task's level and the installed agents against their verified ranges, and agentgarm doctor checks the versions too.

agentgarm status
agentgarm doctor

Checked by the walk: these commands ran as written on a no-root Linux install.

See also

Check that protection is on

See whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.

4. Check installed agents against advisories

preview

With a signed advisory pack in force, agentgarm agents also lists an ADVISORY line for each installed agent whose version an advisory names, and exits 1. agentgarm status adds the desktop AI apps the inventory found, and agentgarm doctor warns once per match. A matching agent is reported, never refused: it still launches and is governed as before. Without a pack, agentgarm agents says the advisories were not checked; AgentGarm does not ship a signed advisory pack yet.

5. Find AI runtimes and apps outside governed sessions

preview

agentgarm-session also looks for local model runtimes (Ollama, vLLM, LM Studio and the llama.cpp server, probed only on loopback, on the ports the catalog lists) and desktop AI apps, every 10 minutes. agentgarm status --inventory runs a sweep now and lists each one with its address or path and whether a governed session used it (UNMANAGED or governed); the dashboard's Overview counts them in one line, and its Agents screen lists them under “Other AI on this machine”. It is inventory, not enforcement: nothing is blocked, nothing counts as a denial, and prompts and model output are never read.

agentgarm status --inventory

6. Bring the agent back into range

AgentGarm reports versions; it does not pin them, and no policy setting refuses a version. To clear drift, install a version inside the range agentgarm agents --json shows, or turn off the agent's automatic updates where it has them, then run agentgarm agents again. A version newer than verified is covered once an AgentGarm release verifies the agent's hooks at that version. For an agent installed from npm, such as Codex CLI, install a version inside the range by its number.

npm install -g @openai/codex@<version>
agentgarm agents