# Handlers

> Handlers are the people who sign off, pause and command agents.

A **handler** is a person who acts on agents from LightHouse: pausing and resuming them, setting their spending caps, granting standing pre-approvals, deciding on outputs that wait for sign-off, and making a released version current. In LightHouse this is the `handler` role, and `client_admin`, which includes it.

## What a handler may do

| Command                                                         | What it does in your deployment                                                                                                                        |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent.pause`                                                   | Turns the kill switch on for that agent                                                                                                                |
| `agent.resume`                                                  | Turns it off again                                                                                                                                     |
| `budget.set`                                                    | Sets the agent’s cap (`total`, `month` or `day`). Lowering is always allowed; raising needs a role your policy names, and never goes above its ceiling |
| `preapproval.grant`, `preapproval.limits`, `preapproval.revoke` | A standing pre-approval: grant one, change its limits, revoke it                                                                                       |
| `approval.decide`                                               | Approve or reject an output waiting for sign-off                                                                                                       |
| `release.add`                                                   | Make a released version the current one; refused unless that version passed the release gate                                                           |
| `limit.set`, `limit.clear`                                      | A spending limit, sent from **Spend → Limits**                                                                                                         |

Every command needs a `reason`.

## Both sides must allow

A command is created only if your tenant’s **command settings** switch its type on (**Setup and admin → Commands**), and carried out only if your deployment’s own policy file allows it. Both are off by default. Atlantic can switch neither on.

## How a command travels

1. A handler, signed in with a second factor, issues the command in LightHouse.
2. LightHouse signs it and queues it for your deployment. It expires if no engine takes it in time (five minutes by default, at most fifteen).
3. Your deployment’s command channel, which dials out to LightHouse, verifies the signature, the tenant, the expiry and your policy, and only then acts.
4. The engine answers each step, signed with your deployment’s key: `queued`, `delivered`, `accepted` or `refused`, then `applied` or `failed`.

Every command, and every final status, is in your tenant’s audit log.

## Why a machine key can never act as a handler

Commands are made by a person signed in with a second factor, never by a key. A machine key, or the Access service token, is refused on every command route with `403 person_required`, whatever its role. No MCP tool issues a command. This is what stops an AI agent holding a key from approving its own work or loosening its own limits.

## In the API

- `POST /api/v1/agents/{agent_id}/commands` and `POST /api/v1/approvals/decisions`: a person’s session only.
- `GET /api/v1/commands`, `GET /api/v1/commands/{command_id}`: any role from `viewer`.
- See the [Handler commands reference](/api/reference/handler-commands/), and [Idempotency](/api/idempotency/) for safe retries.

Source: https://docs.atlanticagenticlabs.com/concepts/handlers/