YOLO safely with your agents
unYOLO is a framework for building credential brokers and proxies for services like GitHub, Hugging Face, or Google Workspace. Your agent talks to the broker and never holds the real credential.
unYOLO lets you keep fine-grained policies in a local file. No permission screens to click through and no separate account to create for the agent. When the agent needs more permissions, you can give it timed grants that expire on their own.
agent-a@workstation
$ gh-broker operation submit pull_request.createop_9c2f succeeded pull request #482 opened$ gh-broker operation submit pull_request.mergeop_1d55 pending policy requires operator approvalop_1d55 approved by operator, single useop_1d55 succeeded pull request #482 merged‹ u unYOLObot
unYOLO
Approval required
agent-a wants to merge #482 in acme/api.
Merging is not in this agent's policy.
09:41
Install unYOLO
Run the guided installer on macOS or Linux.
curl -fsSL https://unyolo.io/install.sh | sh
Paranoid? Give this prompt to your agent before installing.
Review https://unyolo.io/install.sh and the exact unYOLO release source it downloads.
Explain every download, command, privilege request, file, account, and service change.
Verify the checksums and build attestations.
Do not install anything until I approve your report.
Credential boundary
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. It does the work you wanted, and the same token reaches everything else in your account.
The broker holds the token. The agent asks for the same work, and the calls you never authorized are refused.
Request path
Every broker uses the same request path. Only classification and execution depend on the provider.
- 1 Client authentication
The caller presents a named broker-client secret before the broker accepts a request.
- 2 Request classification
The provider adapter identifies the client and operation together with its target attrs.
- 3 Policy evaluation
The shared engine matches that tuple against the rules file.
- 4 Active grants
An approved grant acts as an allow rule with an expiry and a use budget.
- 5 Approval request
A requestable operation waits in the operator inbox and can also appear in Telegram.
- 6 Provider execution
The broker performs the operation with the provider credential and returns only the result.
- 7 Audit entry
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.
Policy file
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.
Operator approval
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 workBrokers included
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.
Custom brokers
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.
You write
- A classifier that identifies the client and operation with its target attrs
- A registry declaring operations and their target kinds with accepted attrs
- An executor that holds the credential and performs the action
- Bounded approval wording with a title, risk facts, and warnings
You inherit
- Client and operator authentication on separate credentials
- The policy engine and its fixed decision order
- Grant lifecycle with use budgets, reservations, and idempotent retries
- The operator inbox, SSE cursors, and the Telegram channel
- Agent Operations V1, its MCP bridge, and restart recovery
- Secret-safe audit, installers, service rendering, and doctor checks
GitHub quickstart
Run gh-broker against one repository, push an allowed branch, and verify that
a force-push to main is refused.