unYOLO keeps provider credentials in separate broker processes. Your agent can use the operations allowed by policy without receiving the token or privilege behind them.
$ git push origin agent-a/parser-fix 4d1e07c..9f2c1ab agent-a/parser-fix -> (new branch) $ gh-broker operation submit pull_request.create \ --target-json '{"kind":"repo","owner":"acme","name":"api"}' \ --arguments-json '{"head":"agent-a/parser-fix"}' op_01JQ8W3M succeeded pull request #482 opened # The same agent cannot rewrite main. $ git push --force origin main ! [remote rejected] main -> main (gh-broker: no rule allows git.push.force) # And it never held a GitHub token. $ git config --get credential.helper gh-broker git credential
Agent tools often receive the same account-wide token a person would use. A mistaken command can then reach every repository and operation covered by that token.
A broker keeps the provider token in another process. The agent receives a client credential whose authority comes from policy, so an unauthorized force-push fails before GitHub sees it.
You hand the token to the agent. Now the agent reaches everything the token reaches.
The broker holds the token. The agent can only ask, and only the wire your policy allows carries anything.
Every broker uses the same request path. Only classification and execution depend on the provider.
The caller presents a named broker-client secret before the broker accepts a request.
The provider adapter identifies the client and operation together with its target attrs.
The shared engine matches that tuple against the rules file.
An approved grant acts as an allow rule with an expiry and a use budget.
A requestable operation waits in the operator inbox and can also appear in Telegram.
The broker performs the operation with the provider credential and returns only the result.
The broker records the decision and matching rule IDs without including secrets.
Decision order, fixed regardless of rule order in the file
deny active grant allow request no_match Deny wins over everything, including an approved grant, and a request that matches no rule at all is refused.
A broker loads one JSON rules file at startup as its authorization source. You can read it directly and review changes in a pull request. unYOLO does not infer permissions from traffic.
Attrs provide the useful narrowing. The rule beside this text allows pushes to
refs/heads/agent-a/**. It leaves refs/heads/main uncovered, so a
push to the default branch is denied. Unknown fields, duplicate rule IDs, unsupported
operations, and invalid globs prevent the service from starting.
{
"rules": [
{
"id": "agent-a-read-and-branch",
"effect": "allow",
"clients": ["agent-a"],
"operations": [
"contents.read",
"git.fetch",
"git.push.fast_forward"
],
"targets": [
{ "kind": "repo", "owner": "acme", "name": "api" }
],
"attrs": {
"refs": ["refs/heads/agent-a/**"]
}
}
]
}{
"rules": [
{
"id": "request-force-push-to-main",
"effect": "request",
"clients": ["agent-a"],
"operations": ["git.push.force"],
"targets": [
{ "kind": "repo", "owner": "acme", "name": "api" }
],
"attrs": {
"refs": ["refs/heads/main"]
},
"grant_policy": {
"mode": "window",
"default_minutes": 5,
"max_minutes": 10,
"default_max_uses": 1,
"max_uses": 1
}
}
]
}{
"rules": [
{
"id": "never-delete-refs",
"effect": "deny",
"clients": ["*"],
"operations": ["git.ref.delete"],
"targets": [{ "kind": "repo" }],
"description": "Deletion is never delegated, even under an approved grant."
}
]
}
Marking an operation request creates a durable approval record and keeps the
original call open. Once approved, a git push resumes as the same push. A
denial, expiry, or change in upstream state returns an ordinary Git failure and forwards
nothing.
Operators decide through a protected inbox on a separate listener with its own credential. Telegram can display the same approval record. Either interface closes the request exactly once, and approval may only narrow its duration or use count.
How approvals work$ curl -sS --unix-socket "$OPERATOR_SOCK" \ -H "Authorization: Bearer $OPERATOR_TOKEN" \ localhost/api/operator/v1/requests?status=pending { "items": [{ "id": "g_01JQ8W3M", "revision": 3, "requester": "agent-a", "operation": "git.push.force", "presentation": { "title": "Rewrite history on acme/api", "risk": "high", "warnings": ["Removes 2 commits from main"] } }] } # Approve, narrowing the window to two minutes. $ curl -sS -X POST .../g_01JQ8W3M/approve -d '{ "expected_revision": 3, "constraints": {"duration_seconds": 120} }' 200 state=active uses_remaining=1
The repository includes GitHub and Hugging Face brokers. sudo-broker handles
approved Unix commands. Each runs as a separate process and cannot reach another
provider's credentials.
Holds GitHub App credentials. For a repo-scoped request it mints a short-lived installation token narrowed to that one repository and the minimum permissions the operation needs.
Holds a Hugging Face token for Hub repositories and Router inference. It parses Git and LFS pushes before forwarding them, so history rewrites stop at the broker.
Runs one exact command from a root-owned catalog as another Unix user. It rejects shell strings and arbitrary executables along with TTYs or caller-supplied environments.
The included brokers use the same framework available to custom providers. To protect an internal API key or cloud role, implement the provider-specific classifier and executor. Shared packages supply the policy and approval machinery. The architecture check rejects shared code that imports a provider.
Run gh-broker against one repository, push an allowed branch, and verify that
a force-push to main is refused.