Monitoring & what to watch
Permaura is deny-by-default, so most of what goes wrong shows up as something being refused rather than something escaping. That makes monitoring less about alarms and more about noticing a change in shape.
The useful habit is to know what your normal looks like. Open the dashboard once while everything is fine.
The four signals
Everything you need is on two pages.
1. The denial rate (Dashboard)
The requests-over-time chart splits every request into allowed, held for approval, and denied. The absolute number of denials matters less than the shape:
- A steady low trickle is normal and healthy. Agents probe; policy refuses. That's the system working.
- A sudden spike from one agent usually means a client updated and started calling something new, or somebody widened what an agent tries without widening what it's allowed. Check the audit log for which capability.
- A spike across every agent points at the gateway or a connection rather than at any agent: a credential that stopped working, or a connection that got disabled.
- Denials falling to zero deserves a second look. Either things settled down, or a grant got widened more than intended.
2. Approvals pending (Dashboard and the queue)
A number that only goes up means requests are waiting unanswered, and the agents that raised them are stuck behind them. Either the ladder is set stricter than your team can service, or nobody knows the queue exists.
Held requests are single-use by design: an ignored one never proceeds. An agent's held call does not expire either, so it stays in the queue until someone approves or denies it. Two kinds of hold do lapse: a held vault export, ten minutes after it was requested, and from gateway 1.3.46 a held settings change, such as a device pairing, a device removal or a loosened policy waiting for a device, 24 hours after it was held. That's a safe default, not a silent success, but it does mean held agent calls only leave the queue when you act on them.
3. Chain verified (Audit log)
The audit log verifies its own hash chain continuously and shows a Chain verified pill without you asking. It's a boolean you should never see change.
If it ever reads broken, the log has been altered or truncated on disk. Treat it as an incident: see Playbooks. You can also check it from anywhere:
curl -s http://127.0.0.1:7376/health | jq .audit_chain_intact
An edit made without the signing key breaks the chain, and deleting the whole log is obvious. Someone who also holds the signing key could rewrite it, and on a gateway you run that key sits beside the log. Removing only the newest entries is detectable only against a checkpoint kept elsewhere. Knowing which of those you have matters when you're deciding what to do next.
4. Budget consumption (Grants)
A grant's budget is a cap on calls per rolling day, week, month, or overall. Consumption climbing much faster than usual is the earliest signal of a loop, a retry storm, or an agent doing something repeatedly that it should be doing once.
A grant that has hit its cap starts denying, so this shows up in signal 1 as well, but the budget is where you see it coming.
Reading the audit log
Every decision lands here, hash-chained and ed25519-signed. The gateway never writes a credential into it, and the signed record keeps the size of a call's result rather than its text. A call that failed can also carry error details: the upstream's own error message, up to 500 characters, kept for 30 days and removable with Clear error details. That message gets the same cleaning as the agent's copy of a result, with the same limits, so a credential shorter than 8 bytes, or another secret the upstream quotes outside a field on the redaction list, can still show up there. What Permaura protects lists what the cleaning catches.
- Search across agent, capability and connection to answer "what has this agent been doing" or "who has touched this connection".
- Filter by decision to isolate denials, or the requests that were held.
- Click a row to inspect its request hash, its chain links, and its signature. That's how you show somebody the record is intact rather than asserting it.
The single most useful move: when someone says "the agent can't do X", filter to denials and find it. The entry names the capability and connection that were refused, which tells you exactly what to allow. It's faster than reasoning about your policies. If there is no entry, the call was refused before any policy looked at it (a capability the gateway does not have, agents paused, a rate limit or a call too large), and the error the agent got says which.
There's no export button. If you need records kept beyond the gateway's own store (for a review, or before you rebuild a gateway), read them out with permaura audit or GET /v1/audit-events and keep them somewhere yourself. See the REST API.
A rhythm that works
Not a compliance regime. Just enough to catch things while they're small.
Weekly, a couple of minutes
- Glance at the dashboard: is the allow/hold/deny shape roughly what it was last week?
- Is the approvals queue empty, or at least moving?
- Any connection showing unhealthy?
Monthly, ten minutes
- Re-read your grants. This is the one that pays off. Grants accumulate: a widening added for a one-off task, an agent that no longer exists, an expiry nobody set. Anything you can't justify out loud should be narrowed or removed.
- Check the Agents list against reality. Every agent that's still approved is still a live identity. Remove the ones nobody is using.
- Check budgets are still sized for what these agents actually do now.
- Confirm the Default grant is still as tight as you meant it: every approved agent inherits it, so it's the widest thing you own.
When anything changes
- New agent connected: check what grant it picked up, not just that you approved it.
- New connection added: check which capabilities arrived enabled. Reads generally arrive switched on and anything that spends money arrives switched off, but check rather than assume.
- Someone left: work through offboarding.
What Permaura doesn't do for you
Being straight about the gaps, so you don't discover them during an incident:
- No alerting. There are no emails, webhooks or thresholds that will tell you a denial rate changed. Pending approvals surface as a badge in the console, and on a hosted gateway every held approval is pushed to the phones of the people who can decide it; everything else you have to look at.
- No audit export or SIEM feed. Reading the log out is a scripted
GET /v1/audit-events, not a button. - No cross-workspace view. Each workspace has its own gateway and its own audit log. Watching three workspaces means opening three.
- No cloud copy of the log. A local gateway's audit chain lives in
~/.permaura/gateway.dband nowhere else. If that machine dies, so does the record.
If any of those are load-bearing for you, tell us. Knowing which one is what decides the order they get built in.
The stop switches, in order of blast radius
Worth knowing before you need them, not during.
| Reach | How | Effect |
|---|---|---|
| One agent | Agents → remove | Sessions revoked at once; grants naming only it are deleted |
| One integration | Open the connection → kill switch | Every call through it refused instantly, across every agent and grant |
| One capability | Connection → toggle the capability off | Refused for everyone, whatever any policy says |
| One grant | Grants → pause | That access suspended, definition kept |
| Everything, keep the process | POST /v1/broker/pause | Every call refused while paused |
| Everything | Stop the gateway | Nothing can act at all |
Uninstall & reset has the same list from the "I want it gone" angle.