sudo-broker

name	sudo-broker
description	Use unYOLO for approved Unix privilege and identity transitions when sudo-broker is installed. Use for privileged, sudo, root, run-as-user, or cataloged host command requests instead of invoking sudo, su, doas, pkexec, or unrestricted shell escalation directly.
metadata	{"openclaw":{"emoji":"🛡️","requires":{"bins":"[Truncated]"}}}

Sudo Broker

Use sudo-broker for every privileged or cross-user host operation. The broker can execute only an operator-defined command ID with bounded arguments, working directory, target user, timeout, and output.

Do not invoke sudo, su, doas, pkexec, setuid helpers, or container-based privilege escalation as a fallback.

Authenticate to unYOLO

sudo-broker loads its private client V1 document directly from ~/.config/sudo-broker/client.json. Do not source it or copy its credential into the environment. Environment configuration is only for isolated development.

The unYOLO secret authenticates the enrolled client; it is not a Unix password. Never print or persist it elsewhere.

Run a cataloged command

Use the exact command ID and target user approved for the task:

sudo-broker run COMMAND-ID \
  --as TARGET-USER \
  --reason "Concrete reason for this operation" \
  --operation-id STABLE-OPERATION-ID

For typed catalog slots, repeat --arg-json NAME=JSON. Do not invent command IDs, executable paths, environment variables, or free-form shell fragments. If the required command is not cataloged, report that the operator must add a narrow command and policy rule.

Use a stable operation ID for retries. Never retry an ambiguous execution with a new ID. sudo-broker run stays attached until approval and command execution finish. If the caller times out or is interrupted, immediately rerun the exact request with the same operation ID to recover it.

Approval waiting is part of the same agent turn. Do not return control to the user while the operation remains pending. Keep the blocking command alive, or recover it with the same operation ID, until the user clicks or otherwise records a decision and execution reaches a terminal state. Stop only for a terminal result, an explicit user cancellation, or an unrecoverable broker error.

Approval behavior

Requestable commands default to reusable window grants. Every invocation still gets its own immutable command plan, helper reservation, result, and audit record. Policy may select exact execution mode, which is always single-use. A reused window never permits a different command ID, target user, typed slot, host identity, or catalog digest.

A pending request means the operation is waiting for an authorized decision; it does not mean the client credential is missing. Keep the request alive without ending the agent turn. Do not approve your own request, modify policy, or access operator credentials.

After approval, treat the broker's exit status and bounded output as the command result. Confirm the intended host effect separately when the original workflow requires end-to-end verification.