How it works
Trust boundaries, request flow, and what each component holds.
Trust boundaries
Untrusted: the agent, its commands, repository contents, package scripts, prompts, and issue text.
Trusted: the broker process, host operator, configuration, state directory, private key, and container/network administrator.
The daemon serves one runtime identity loaded from host-controlled configuration. Requests cannot choose their identity. Deploy one broker per isolated workspace, and never publish the listener to a shared or public network.
A push, step by step
- Rate limit. A per-client token bucket runs before anything else.
- Host and origin. Browser-origin requests and unexpected
Hostvalues are rejected. - Authenticate. The workspace bearer token (and, in assertion mode, a signed runtime assertion) is verified.
- Parse. The broker buffers only the receive-pack command section (at most 1 MiB) and parses every ref update strictly. Malformed packets and unsupported extensions fail closed.
- Decide. Each ref is checked against policy. If any ref is denied, nothing is forwarded.
- Approve. If a rule requires approval, the broker stores a pending request and returns
403 REQUIRE_APPROVAL. - Scan. For repositories with
scan, the pack is quarantined and every added blob inspected. - Audit. The decision is appended to the hash-chained log. If the write fails, the push is not forwarded.
- Forward. A token scoped to one repository is minted, and the pack streams upstream to a fixed GitHub endpoint. Redirects are rejected.
Where secrets live
| Secret | Holder | Workspace can see it? |
|---|---|---|
| GitHub App private key | agentd, or a KMS via AGENTGATE_SIGN_COMMAND | No |
| Installation tokens | agentd memory | No |
| Workspace client token | workspace + agentd | Yes — identifies the workspace, not a secret from the agent |
| Model API key | model-gateway | No |
| Approval-web admin secret | agentd + approval-web | No |
Networks (Compose)
- workspace — internal only. Workspace, agentd, egress-proxy, model-gateway.
- upstream — internet-facing. agentd, egress-proxy, model-gateway, audit-forwarder.
- approval — internal. approval-web and oauth2-proxy.
- monitoring — fixed subnet for the Prometheus metrics listener.
The workspace has no route to GitHub or the internet. Its DNS points at 127.0.0.1, so external names don't resolve and DNS can't be used for exfiltration.
Supported Git
Unsigned SHA-1 pushes, shallow pushes, allowlisted push options, NFC-normalized Unicode refs (opt-in), and Git LFS. Signed pushes (push certificates), SHA-256 repositories, compressed requests, and LFS locking are refused. Signed commits pass through.