---
title: "Set the agent kill switch"
method: PUT
path: "/agent-kill-switch"
tags: ["agent-activity"]
---

# Set the agent kill switch

`PUT /agent-kill-switch`

## Request

- Base URL: `https://api.opal.dev/v1`
- URL: `https://api.opal.dev/v1/agent-kill-switch`
- Auth: HTTP bearer

**Prototype (AG-297).** Turns the org-level agent kill switch on or off. Admin only.

While it is on, Opal answers every `PreToolUse` hook POST to `/agent-activity` with a `deny` decision, so a cooperating Claude Code client stops running tools.

**It is not a security boundary, and it fails open.** It reaches only clients that are configured to POST to `/agent-activity` and that honour the answer; a client on a non-default base URL, an older build, or with no hook deployed is unaffected. If Opal is unreachable or slow the tool call proceeds, because Claude Code treats a failed `PreToolUse` hook as a non-blocking error by design.

Activation is always time-bound: `duration_minutes` is capped, and an activation that reaches `expires_at` stops denying on its own.

## Request body

- SetAgentKillSwitchRequest: # SetAgentKillSwitchRequest Object ### Description Turns the agent kill switch on or off. Setting `active` to `true` while it is already on supersedes the current activation rather than extending it: the old row keeps its own reason and window as part of the audit trail, and a new one starts.
  - `active` boolean, required: True denies agent tool calls for this organization; false lifts the denial.
  - `duration_minutes` integer: How long the denial lasts, from now. Ignored when `active` is false. Capped server-side - a kill switch with no end is how an organization discovers months later that its engineers have been quietly working around it.
  - `reason` string: Why. Shown verbatim to the developer whose tool call is denied, so write it for them rather than for the audit log - it is the only explanation they get.

## Response `200`

The state of the kill switch after the change.

- AgentKillSwitch: # AgentKillSwitch Object ### Description The org-level agent kill switch, and the activation that is in force or last was. `active` is what matters; the rest is the record of how it got that way. An activation is in force only while it has not been deactivated AND `expires_at` is still in the future, and that is evaluated on every read - so `active` can be `false` on a row that was never explicitly turned off. Everything below `active` describes the LATEST activation whether or not it is still in force, so an admin reading an inactive switch can still see who last turned it on and when it ended.
  - `active` boolean, required: Whether agent tool calls are being denied right now. This is the field to read; it already accounts for expiry.
  - `activated_at` string, date-time: When the latest activation was turned on. Absent if it never has been.
  - `activated_by_user_id` string, uuid: The admin who turned it on. Absent when that user has since been hard-deleted - the activation record outlives them deliberately.
  - `expires_at` string, date-time: When the latest activation stops denying on its own. In the past for an activation that already ran out.
  - `deactivated_at` string, date-time: When the latest activation was turned off before its expiry, either by an admin or by being superseded. Absent when it ended at `expires_at`, or has not ended.
  - `reason` string: The admin's stated reason. Not an internal note - it is shown to the developer whose tool call is denied, in their own terminal.

## Other responses

- `400`: The body was unparseable, or `duration_minutes` was out of range.
- `403`: The caller is not an admin, or the agent kill switch is not enabled for this organization.

## Changes

- **2026-10-22** `8fce5da23873`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/opal/apis/opal-api/changes/agent-kill-switch/put.md)

---

[API](https://skmtc.dev/opal/apis/opal-api.md) - [All operations](https://skmtc.dev/opal/apis/opal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/opal/apis/opal-api/revisions/e7877ea96eab?raw)