Hosted agents

Vendor-hosted agents (the GitHub Copilot coding agent, Cursor background agents, Devin, and similar) run in the vendor's infrastructure with the vendor's own GitHub App credential. They never touch the AgentBox workspace or broker, so nothing on the Git path governs them. What AgentBox can do is provider-native: observe every pull request and push through the AgentBox GitHub App's webhooks, evaluate the same policy, and make merge depend on a check run that a branch ruleset requires. This is what the hosted-agents service (Compose service in compose.enterprise.yaml) does.

What is governed, and what is not

	Governed
Merging a hosted agent's pull request into a protected branch	Yes: the ruleset requires the `agentbox/policy` check, which policy sets to success, failure, or leaves pending until a human approves
Which human the run is attributed to	Best-effort: derived from the pull request and recorded with `humanSource`
A hosted agent's direct pushes	Audited only; the ruleset must block pushes to protected branches, and a push that lands there is flagged `hosted-push-unexpected`
The vendor's credential, what the agent reads, its model traffic	No: those are the vendor's

Configuration

"hostedAgents": {
  "agents": [
    { "login": "copilot-swe-agent[bot]", "name": "copilot" },
    { "login": "cursor-agent", "name": "cursor" }
  ],
  "checkName": "agentbox/policy"
},
"rules": [
  { "id": "hosted-main", "action": "github.pr.hosted", "repository": "acme/demo", "ref": "refs/heads/main", "effect": "approval", "reviewerSources": ["oidc"] },
  { "id": "hosted-feature", "action": "github.pr.hosted", "repository": "acme/demo", "ref": "refs/heads/feature/*", "effect": "allow" }
]

agents: 1–20 entries; login is the GitHub login the vendor's agent commits and opens PRs as, name the short agent name used in runtime IDs and audit. Only events whose actor is a configured login are governed.
github.pr.hosted rules match on the pull request's base branch like github.pr.merge; requires, approvals, and reviewerSources work as everywhere else. No matching rule means default deny, and the check fails.

GitHub App permissions in addition to the broker's: Checks: write, Pull requests: read. Subscribe the webhook to pull request and push events. The webhook secret goes in AGENTGATE_HOSTED_WEBHOOK_SECRET_FILE.

Flow

A pull request event arrives

The service verifies X-Hub-Signature-256 timing-safely, drops replayed X-GitHub-Delivery ids (persisted, bounded), and ignores actors that are not configured.

The human is derived

First assignee; else a Requested by: @login line in the PR body; else a Co-authored-by trailer; else unknown with the linked issue number, or none. Every record carries humanSource. human is best-effort and never a verified identity.

Policy is evaluated and a check run posted

github.pr.hosted for the repository and base branch, with the entitlement envelope when a rule uses requires. Allow gives success, deny gives failure with the rule id, approval creates an approval in the broker's store and posts the check as in_progress with the approval id in its summary.

Reviewers decide where they always do

The host CLI, the approval web UI, Slack notifications. The service polls the approval store (AGENTGATE_HOSTED_POLL_MS, default 10 s) and completes the check as success or failure. The delegating human cannot approve. Until then the pull request is unmergeable, never mergeable.

A new head sha starts over

The earlier pending approval is dropped and evaluation repeats; the old check run stays on the old sha, which the ruleset no longer considers.

Audit and rulesets

The service keeps its own state directory (AGENTGATE_HOSTED_STATE_DIR) with a hash-chained audit.jsonl, the replay list, and the map of pending approvals to check runs. It never writes the broker's audit file; point the audit forwarder at both directories. Records carry hosted: true and a runtime of the form hosted:<agent>:<owner/repo>:<pr number>.

With hostedAgents configured, the startup and hourly ruleset verification also requires, for every protected branch, a required_status_checks rule naming checkName, and refuses any ruleset whose bypass actors include a GitHub App. Both fail closed.

Trust

AgentBox trusts GitHub's webhook signature and ruleset enforcement. A leaked webhook secret lets an attacker forge events: at worst a forged pull request creates a pending approval or posts a failing check, never a success without policy saying so. A compromised hosted-agents process holds an App token with checks: write and pull_requests: read, the webhook secret, and the approval-web admin secret; it can post any check conclusion and create hosted approvals, but cannot mint contents tokens, read the workspace, approve anything, or alter the broker's audit chain.