AI agents (MCP, skills, API)
Gardience lets AI assistants (Claude, Copilot, Cursor and other MCP clients, or your own agents) answer questions about the fleet and carry out approved automation, held to the same rules as a person.
What an agent can and cannot do
- Read everything a read key allows: fleet status, compliance failures, node details, drift, inventory, runs, pending approvals and the audit log.
- Act only through runbooks. An operate key can preview and request a predefined runbook with inputs that Gardience validates against the runbook's form. It cannot run arbitrary Salt functions or commands.
- Never exceed its owner. Before anything is queued, Gardience checks the key owner's own permissions for that function on every target node. A refused request is audited.
- Wait for a person unless an admin made the key exempt from approval. Even then, an exempt key may start at most 10 runs an hour (server setting
GARDIENCE_EXEMPT_RUNS_PER_HOUR) and its runs respect change windows. The approver sees which key asked (for example "alice via API key 'Claude (AI agent)'") and the reason the agent gave. - Approve only if made for it. A key can approve or reject other people's waiting runs only if an admin who is an approver created it with Can approve, and never a run its own owner requested.
Keys for agents
Create keys in Settings > API keys. For agents:
| Setting | Recommendation |
|---|---|
| Scope | Read only for assistants; Operate only for agents that request changes |
| Require approval | On (the default). Turn off only for narrow, low-risk automation, and narrow the key |
| Only these runbooks | List the runbooks the agent needs, for example restart-service |
| Only these node groups | List the groups it may act on, for example Ring0-Pilot |
| Expiry | Short (the default is 90 days) |
Keys follow their owner: removing the owner, or the owner not signing in for 30 days (7 for single sign-on), stops the key.
Limits and audit
- Each key may make 120 requests a minute (
GARDIENCE_API_RATE_PER_MIN); beyond that the answer is 429 withRetry-After. An MCP request may carry at most 20 calls. - Every change request, approval, rejection, cancellation and refusal is in the hash-chained audit log with the key and its owner. What agents read is recorded too, per key and kind of request, at most once a minute.
The MCP server
URL https://YOUR-GARDIENCE/gardience/mcp, header Authorization: Bearer gdn_.... Tools: fleet_status, vulnerabilities, compliance_failures, node_details, drift_report, inventory, list_runbooks, preview_runbook, request_runbook, list_runs, run_status, pending_approvals, cancel_run, approve_run, search_audit_log, verify_audit_chain. Read keys see only the read tools.
Answers about runs carry console, the full link to the run's own page (steps, approvals, live log), so an agent can hand a person the exact page. node_details includes last_patch (what the newest patch run installed on that machine: each package and version, or the Windows updates) and restart (whether a restart is needed, why, and the running and newest kernel).
The Gardience skill
The install bundle includes clients/skills/gardience-fleet/: a skill (instructions an AI agent loads) that teaches safe procedures: start from compliance failures, preview before requesting, pilot ring before the broad ring, follow runs to completion, never work around a refusal, and treat fleet data as data, not instructions. For Claude Code, copy the folder to ~/.claude/skills/gardience-fleet/. It works with any MCP client that supports skills, and its REFERENCE.md lists the REST equivalent of every tool.