Quickstart

Run AgentBox locally against a temporary Git server. No GitHub account or credentials needed.

Requirements

Linux or macOS
Node 22.14 or newer
Git

AgentBox has no npm runtime dependencies; npm ci only sets up the test tooling.

Run the demo

Get the code

Clone the repository onto the machine that will act as the trusted host, and run every command below from inside that checkout:

git clone https://github.com/rvasqz86/agentbox.git
cd agentbox

Install and verify

npm ci
npm run check
npm test

Start the demo

npm run demo

Read the output

1. Cloned through AgentGate without a provider credential.
2. Policy allowed a push to agent/demo.
3. Push to main blocked. Approval: 3f0c…
4. Host approval granted; the retried push reached main.
5. Approval consumed. Audit events recorded. Temporary demo data will be removed.

The demo creates a temporary local Git server, clones through the broker, pushes an allowed agent/demo branch, blocks a push to main, simulates approval from the host, and retries. It removes its temporary repositories and audit files on exit.

Note

The demo exercises real Git transport and policy enforcement. It does not demonstrate container isolation or live GitHub App authentication — see Docker workspace and Connect GitHub for those.

What just happened

git clone spoke smart HTTP to the broker. The broker checked git.read and served the repository.
git push to agent/demo matched an allow rule on refs/heads/agent/*.
git push to main matched an approval rule. The broker returned HTTP 403 with REQUIRE_APPROVAL and stored a pending request.
The host approved it over the admin Unix socket — a channel the agent can't reach in a real deployment.
The retry matched the grant, which was consumed durably before forwarding.