Agent Status
Back to AgentDiff
Setup guide · 5 minutes

Install AgentDiff, gate the next PR.

Free

AgentDiff is free. No code changes, no extra runner, install in under two minutes.

Install

Sign up, connect GitHub, done.

Runs as a GitHub App on pull_request events. Never reads your source code.

01

Create an account

Sign up (or sign in) so installs map to your workspace.

02

Connect GitHub

Open AgentDiff → Connect GitHub. Pick your org and repos. Start with one.

03

Claim the install

If the app was installed from GitHub first, open AgentDiff settings to claim it.

Permissions requested: pull-requests: write, checks: write, metadata: read, deployments: read. No Contents read.
Configure

Point it at your agent.

In Settings → Repos, give it two URLs: your baseline and your PR preview.

base_url
Baseline

The agent endpoint AgentDiff treats as the baseline, typically your production agent on main.

https://api.example.com/v1/chat
head_url_template
Candidate · per PR

The candidate endpoint for a PR. Placeholders: {branch}, {sha}, {pr_number}.

https://pr-{pr_number}.preview.example.com/v1/chat

Both URLs are validated from the same residential nodes, in series. Differences are attributable to the endpoint, not the network.

First PR run

Open a PR. Watch the check.

An AgentDiff check appears on the PR within seconds. Aggregation lands in 30 to 90 seconds.

Add the AgentDiff check to your branch protection rules to gate merges on the verdict. Owners can override a verdict from the run report and overrides re-push the GitHub Check immediately.
Auth modes

Authenticate to the validated agent.

Four auth modes. Secrets are encrypted at rest and decrypted on the residential node at validate time.

none
No auth. Public-by-default agents.
bearer
Adds Authorization: Bearer <token> on every validate.
custom_header
Adds an arbitrary header (X-Api-Key, etc.).
basic
Standard HTTP basic; user + password.
Baseline

Pick a baseline policy.

Two modes. Pick the one that matches how your team defines a good agent response.

Troubleshooting

Common issues.

PR opened but no AgentDiff check appears.
Confirm the App is installed on the repo (org Settings → Integrations) and that the repo has been claimed in the dashboard with both base_url and head_url_template populated. Drafts and bot-authored PRs are skipped.
Run shows partial coverage and conclusion = neutral.
One or more requested regions had no online residential node when the PR opened. The pass/fail signal is unaffected. Reduce the requested region set if your team treats neutral as blocking.
Validation target sees Authorization: Bearer …(default) instead of my bearer token.
Save your bearer token in Settings → Auth (auth_mode=bearer) and trigger a new run. The token is decrypted on the residential node at validate time and merged onto every validate.

Install AgentDiff, gate the next PR.