Operate
Alerts, locks and emergency codes
When someone tampers with the controls, Fidacy tells your owners and admins, and in the two cases that look like an attack it stops the agent until a person gives its authority back.
Security alerts
The connector sends a heartbeat from every machine it runs on. The engine compares each heartbeat with the previous one and raises an alert on a change, never on a steady state.
| Alert | Severity | When it fires |
|---|---|---|
| Connector uninstalled | high | Someone ran npx @fidacy/mcp uninstall on a machine with an account key. From then on, actions on that machine are not checked or recorded. |
| Hook removed | high | The connector still runs, but the hook that checks every agent action disappeared from the host configuration. |
| Connector reinstalled | critical | A different Fidacy installation now speaks for the machine. The machine is locked (see below). |
| Repeated denials | high | The same agent hit denied actions 5 times in 10 minutes. If another alert from the last 24 hours is still open, the agent is locked. |
| Lifted with a code | high | Someone used an emergency code on a machine and a lock was lifted. |
| Wrong codes | critical | 5 wrong emergency codes in an hour. Codes are refused for the rest of that hour. |
Each alert goes to the Security page of the console, to the email of every active owner and admin, to the audit trail, and to your webhooks as the security.alert event. An alert stays open until an owner or admin resolves it in the console. Emails go out within about a minute. Past 30 alerts in an hour for one organization, new alerts are still recorded but no longer emailed.
Heartbeats come from the connector's MCP server while it runs with an account key. A machine with no account key sends none, so these alerts cannot fire for it.
Security locks
A lock takes all authority away from its target until a person gives it back. It works at three levels.
| Scope | What it stops | Who can lift it |
|---|---|---|
| Organization | Every API key of the company. | An owner or admin, in the console. Emergency codes cannot lift it. |
| Agent | One agent, on every machine. | An owner or admin in the console, or an emergency code. |
| Machine | Everything the connector does on one machine, as long as the machine has an account key and its machine identity is on. | An owner or admin in the console, or an emergency code on that machine. |
Locks start in three ways:
- ·Automatically, when a connector is reinstalled with a new identity (machine lock).
- ·Automatically, when an agent keeps hitting denials while another alert is open (agent lock).
- ·By hand, with Lock every agent now on the Security page of the console (organization lock).
What a lock does
- ·Under an organization lock, every API key of the company gets
423with{"error":"security_locked"}. Under an agent lock, so does that agent's connection key. Only the calls that check the lock, lift it with a code and send the heartbeat still go through. - ·Every authority decision for a locked agent comes back as a signed DENY with the reason
security_locked:agent(or:org), whichever key asks. - ·A grant issued before the lock cannot be redeemed after it.
- ·On the machine, the connector's hook refuses every action, even one the policy allows, and tells the agent why and how the lock gets lifted.
- ·The connector refreshes the lock state every 30 seconds. Without a network, the last known lock stays in force. Deleting the local lock file only makes the hook ask the engine again.
Emergency codes
Emergency codes let someone at the machine lift a lock when nobody can open the console. An owner or admin generates them on the Security page.
- ·A set has 10 codes. They are shown once. Fidacy stores only their hashes.
- ·Each code works once, and is spent only when it actually lifts a lock.
- ·Generating a new set stops every unused code of the old one.
- ·A code never lifts an organization lock.
- ·Every use raises the "Lifted with a code" alert, so the owners know.
On the locked machine:
npx @fidacy/mcp unlock XXXX-XXXX-XXXX-XXXX
The command sends the code with the machine's own key. The key alone never lifts anything.
| Answer | Meaning |
|---|---|
| Lifted | The lock on this machine or agent is lifted, and that code is spent. |
| Not valid | Wrong or already used code. |
| Nothing to lift | Nothing here is under a lock a code can lift. The code was not used. |
| Too many wrong codes | 5 wrong codes in an hour. Ask an owner or admin to lift it in the console. |
| No account key | This machine has no Fidacy account key, so there is nothing to lift here. |
| No machine identity | FIDACY_DISABLE_IDENTITY is set on this machine. Lift it in the console. |
| Fidacy unreachable | The command could not reach Fidacy. Check the connection and try again. |
API
Creating and lifting locks, generating codes and resolving alerts need an owner or admin signed in to the console. No API key can do it, so a leaked key cannot lift its own lock. Reading alerts, locks and the code summary needs audit:read. Checking the lock and lifting it with a code work with any key of the organization, even while it is locked.