Skip to main content
An operator kill switch stops a Parmana deployment from releasing anything new. Once it is tripped, every new request to act, and every approval, is refused before it runs. It is the stop an operator uses when an agent or a connector misbehaves and the system must halt at once.

​
What a trip stops

A tripped switch refuses these with 503 and the error code KILL_SWITCH_ACTIVE:
  • new execution requests (POST /execute)
  • new transactions (/transactions)
  • policy change approvals (POST /policies/pending-changes/{id}/approve)
  • sandbox approvals (POST /sandbox/approvals)
The trip, reset, status and probe routes stay reachable while the switch is tripped, so the switch can always be cleared and checked. The stop is stored in the database, not in memory, so a restart does not clear it. If the stored state cannot be read, the switch counts as tripped. A database fault therefore refuses requests rather than letting them through.

​
Routes

A key without the capability is refused with 403 CAPABILITY_NOT_ALLOWED. A request with no key gets 401. The endpoint pages in the API reference show the full request and response for each route.

​
Two-person reset

In production, reset takes two different operators. Each uses their own named key:
  1. The first operator calls POST /kill-switch/reset with a reason. The answer is 202 and outcome: "pending".
  2. A second operator, with their own key, calls the same route with a reason. The answer is 200 and outcome: "reset", and new requests are accepted again.
The same operator cannot complete their own reset (409 SAME_OPERATOR_CANNOT_CONFIRM_RESET). A new trip cancels a pending reset.

​
Checking the switch

GET /kill-switch/status returns the current state with the nonce you send echoed back, so an old response cannot pass as a current one. The response is not signed yet, so a verifier cannot yet confirm it came from the server.
A response with "active": false means the switch is not tripped.

​
What it does not stop

  • Actions already released. A call admitted before the trip can still complete. The switch does not recall it.
  • Tools reached directly. A tool or system that an agent reaches without going through Parmana is not stopped.
  • One agent alone. The switch stops every caller at once. It cannot halt a single agent.
  • Unsigned status. The status response and the audit events are not signed yet. A signed proof of the switch state is not available until a signing key tied to the build exists.

​
Checking it from outside

A probe sends a request to /execute while the switch is in some state and reports what came back. Parmana records whether the refusal matched the switch state, and every probe result is kept. The probe runs every 15 minutes from a scheduled GitHub Actions workflow, outside Parmana.

​
Open items

  • Signing of status and audit events, which waits on a build-bound signing key.
  • A third-party check on a non-production deployment.
  • An exercise of two-person reset with two real operator keys.
The operating runbook is in the repository under docs/runbooks/KILL-SWITCH-OPERATIONS.md.