Human approval (human-in-the-loop) lets you mark, per credential, the operations that must not run on the credential's own authority. A marked operation does not execute: it becomes an approval request pinned to the exact call, a person with management access approves or denies it in the clientarea, and only then — re-submitted with the approval id — does the operation run. Once.
This exists for the customer who hands an AI agent a credential and still wants a person in front of the irreversible calls. Scopes decide what a credential may do at all; spend ceilings decide how much it may spend; this decides who says yes to the calls that matter.
The policy
A policy is configured per credential in the clientarea (API Management → Approvals), by the account owner. It names:
| Field | Meaning |
|---|---|
classes |
Operation classes to gate: destructive (delete, uninstall, terminate, cancel), spend (orders, upgrades, payments), security (rotate or revoke credentials, mint sub-credentials, export or rotate the .onion key, install the Impreza agent). |
operations |
Individual MCP tool names to gate, e.g. impreza_order_vps. |
ttl_minutes |
How long a request lives: 15–60 minutes, default 30. |
Default is off. A credential with no policy behaves exactly as before — existing credentials change nothing until the owner marks them. A sub-credential never loosens its parent: the effective policy is the union of the parent chain's policies, so a child inherits every requirement and can only add more, and tightening a parent later tightens every child with it.
What happens when an operation is marked
- The agent calls the operation. It does not run. The answer is a stable
approval_requiredresult with theapproval_id, the expiry, and the clientarea link — nothing was executed and nothing was changed. - A webhook event
agent.human_approval_requestedis queued for the account (throttled per credential, like the spend-ceiling notices). - A person approves or denies in API Management → Approvals. The page shows the operation, the credential, and a summary of the call. Argument values that could be secrets were never stored, so the page cannot show them.
- Once approved, the agent re-submits the same call with
approval_id="apr_…". The operation then runs. - Denied and expired requests also become webhook events
(
agent.human_approval_denied,agent.human_approval_expired).
The rules that make it safe
- Pinned to the exact call. The request stores a digest of the normalized arguments. Re-submit with any argument changed and the execution is refused — approving "uninstall dpl_a" approves exactly that, not "uninstall anything".
- Single use. Each approval executes exactly once. Two concurrent re-submissions race on an atomic claim and only one dispatches.
- A credential never approves. There is no API route and no MCP tool that approves, denies, or edits a policy. Decisions exist only as clientarea POSTs behind a session, a team permission and a CSRF token — so an agent cannot approve itself, through a sub-credential, or through an API key. Read-only members see the queue but cannot decide; only a person with the manage products permission can approve or deny, and only the owner changes policies.
- Independent of the other guards. The scope ladder, the two-step confirmation and the daily/monthly spend ceilings all still apply to an approved call. Human approval adds a check; it never removes one.
Plan-bound host request limits
The VPS reinstall pilot requires a separate owner grant for each credential, operation and server, followed by approval of the exact stored plan. Its request limit counts plans created over the last 24 hours across all servers for the credential, rather than starting a new counter for each server. The pending plan/operation limit uses the same shared scope. Denied, expired and completed requests still count toward the 24-hour request limit until they age out.
For a sub-credential, each credential in its parent chain is checked against its shared counts. The selected server grant and the strictest parent limits apply; plans requested by siblings also use the parent's allowance. Granting another server or increasing one server's limit does not reset these counters. A grant never replaces the human decision or permits an operation on another server.
Reading the state
- REST:
GET /v1/approvals(the queue),GET /v1/approvals/{approval_id}(one request),GET /v1/credentials/{id}/hitl-policy(a credential's stored and effective policy). All read-only. - MCP:
impreza_list_approvals,impreza_get_approvalandimpreza_get_credential_policy— the same reads for the agent, so it can tell you what is parked instead of blindly retrying. Approving is not a tool and never will be. - Minting:
impreza_mint_subcredential(andPOST /v1/credentials) accepts ahitl_policyat creation — it can only add requirements, never drop one the parent carries.
Audit trail
The per-credential activity extract (GET /v1/credentials/activity?format=csv,
or impreza_agent_activity) records the whole lifecycle next to the tool
calls: hitl:request, hitl:approve or hitl:deny with who decided,
hitl:execute when the approved call ran, and hitl:expire. Secret values and
sensitive parameters are never written — the rows carry identifiers only.
Revoking plan-bound host permissions
The account owner can revoke the VPS reinstall pilot's explicit host grant even while the owned server is suspended. The credential must still be active and owned by the account. New or renewed grants require an active server.
Reactivation does not undo a revocation. The revoked marker stays stored, so the credential cannot fall back to the legacy reinstall route. A previously approved plan is refused before dispatch. Restoring permission requires a new explicit owner grant after the service is active again; it does not revive an older plan. Revocation does not cancel an operation already submitted to the provider, whose receipt can still be reconciled without restoring the old grant.
Managed ingress reload
Host plans also offer managed_service.reload: a reload of the managed ingress
on a server you own, approved by a person and applied once. It needs Impreza
agent 0.6.36 or later and a managed ingress unit that declares the fixed
reload (ExecReload); the agent version alone is not enough. The loaded unit
and its reload capability must be confirmed on the server before a plan is
offered. Missing or changed reload support is a refusal, not
proof that a reload works, and the capability read answers 503 on a server
where it is not confirmed. VPS reinstall keeps its existing contract.
Managed reload is offered on Ubuntu 24.04 (amd64) servers. The owner grants the exact operation/server in the portal. Every credential ancestor must also grant that
same operation. manage alone is insufficient. Renewing the OAuth credential of a
connected AI tool keeps the same identity and its grants, so a granted
operation is not lost at renewal; an explicit reauthorization revokes the previous
credential. A grant is still not permanent: revoking it removes it. A verified operator recovery and
health binding, active managed ingress unit with explicit reload support, current
agent generation and an independently owned affected-app set are prerequisites.
The agent creates its own maintenance journal directory when it is
missing; you do not prepare it by hand.
Read GET /v1/host/services/{service_id}/maintenance, then prepare:
{"service_id":799,"operation":"managed_service.reload","ttl_seconds":300}
Use POST /v1/host/plans or impreza_prepare_host_plan. Reload accepts only
those three fields; the technical TTL is 30–300 seconds (default 300). No unit,
command, path, environment, template, package or restart fallback is accepted.
The stored preview binds owner, credential, host generation/boot/state,
capability, affected application references, connection-loss warning and deadline.
An independent human must approve that exact immutable plan in the portal.
The approval and the dispatch check compare the plan in a canonical form, so the
way the database stores the preview cannot make a valid approval fail.
Apply through the existing plan endpoint/tool with exactly the returned
plan_id, plan_digest and approval_id. Acceptance means a durable queued
intent, not completion. Revocation/drift/expiry is checked again at poll dispatch.
Other host writers are reserved out while the reload is pending. Reading the plan
never redispatches; repeating apply returns the same plan, not another command.
An uncertain or partial result stays visible for reconciliation. The agent's
reconciliation observes the existing local journal before the next poll. It can
complete only a durably acknowledged successful effect with fresh, matching
agent/generation/boot/state/capability/app identity before and after route health.
A healthy unit alone never proves that the original effect completed. A crash
before the effect acknowledgement was durably saved, failed IPv6 after IPv4,
unknown result, changed identity, cancelled reservation or backward clock is not
certified; it is left for explicit operator reconciliation.
The agent never reloads or restarts during recovery. Its successful observation is saved before transmission and acknowledged by exact receipt, not just command ID. Authenticated result processing admits one monotonic partial-to-completed transition bound to the same plan, command, generation and fence; the original receipt bytes and original partial audit event remain preserved. Lost responses repost the same receipt; late partial/refused or conflicting observations cannot reopen a completed plan. A cancelled plan with a possible effect cannot be certified by a delayed healthy report.
No reset endpoint or automatic retry of the effect exists. A lost poll response
without a local intent still needs operator reconciliation. Older journals
without the effect proof remain blocked rather than being retroactively certified.
Ordinary v1 receipts remain compatible; only a new recovered success adds the
optional boolean reconciled:true. There is no automatic rollback.
When a reload stays partial
If a reload's outcome cannot be certified, the plan stays partial and its
history is kept. While that plan is partial, the same service does not take
another plan, so nothing new is applied on top of the unknown outcome. Other
commands on the host are held only until the plan's expiry plus ten minutes.
That clock does not close the partial plan, and it does not lift the hold on
the same service. The Impreza agent keeps running: it reports the block
locally, without restarting, reloading or retrying anything by itself. The plan
the owner reads shows partial. The reason string is on the server, from
impreza-agent maintenance status. It is not part of the plan payload.
Releasing the block is a deliberate local step. After checking the server, a person with root on it runs:
PLAN_ID='<plan_id>' # the partial plan's plan_id
sudo impreza-agent maintenance status
sudo impreza-agent maintenance release --plan "$PLAN_ID"
statusis read only. It says whether a maintenance blocks the server and what can end it.releasenever reloads, retries, deletes the journal or changes the stored receipt. It refuses unless the open result was already reported, no operation is running, and the agent, generation, unit and reload bindings still match the plan. The stored ingress rules must still be enforced, and every bound route must be healthy at that moment.- A release does not prove that the original reload worked. It cannot repair a server whose root account is compromised.
After the release, the plan shows released, not completed: the
partial outcome stays in the history and is never counted as a success. A new
plan can then be prepared and approved on its own; nothing is replayed.
The Go SDK adds PrepareManagedServiceReload(ctx, serviceID, ttlSeconds);
Python sync/async account resources add
prepare_managed_service_reload(service_id, *, ttl_seconds=300). Preview/status are
typed; these helpers cannot approve a plan.