RepoWolf lets an AI coding agent use GitHub without putting GitHub credentials or SSH keys in the agent sandbox. A broker that you control holds the provider credentials and enforces repository policy. The sandbox receives only the RepoWolf client, a scoped RepoWolf token, and the public CA certificate.
RepoWolf does not create, inspect, register, or attest sandboxes.
Most developers give a coding agent the same SSH key that they use for Git. That key can reach every repository the developer can access. If the agent or sandbox is compromised, every reachable repository is at risk.
Fine-grained access tokens reduce this blast radius, but they are a pain to create and manage. Each repository needs a token, scopes, and an expiration date. Teams must distribute, renew, and revoke these tokens as access changes.
RepoWolf keeps the developer’s SSH key and provider credentials outside the agent sandbox. A local YAML policy grants each sandbox access to only the repositories and actions it needs. The agent gets scoped access without receiving the underlying credentials.
RepoWolf loads policy at startup. Restart the broker after each policy change.
1. Agent sandbox
- Runs gh or repowolf-git-ssh
- Uses a RepoWolf token and CA
- Has no GitHub token or SSH key
|
| TLS
v
2. RepoWolf broker
- Enforces repository policy
- Authenticates with the provider
- Writes JSONL audit records
|
v
3. GitHub
- API and Git
- RepoWolf enforces explicit capabilities for each principal and repository.
- The
ghcompatibility client restricts GitHub operations. repowolf-git-sshprovides Git over SSH.- RepoWolf protects refs and deletes. It limits ref updates.
- RepoWolf loads strict configuration at startup.
- It writes JSON Lines audit output.
| Host | Recommended setup | Notes |
|---|---|---|
| Linux | Docker for the quickest start. Native for a long-running broker. | Native packages support amd64 and arm64 |
| macOS | Docker Desktop from Terminal | No native RepoWolf package |
| Windows | Docker Desktop through WSL2 | Run commands inside WSL2; PowerShell and cmd are not supported |
Docker Compose is the recommended first setup because it needs no host RepoWolf installation.
You need Git, Bash, Docker with Compose v2, and a GitHub token. Use a GitHub
token that can read the repository. Replace rochecompaan/repowolf with a
repository that this token can read.
git clone https://github.com/rochecompaan/repowolf.git
cd repowolf/examples/docker
cp .env.example .env
chmod 0600 .env
# Edit .env. Set GH_TOKEN and leave REPOWOLF_TOKEN_AGENT empty.
export REPOWOLF_REPO=rochecompaan/repowolf
./bootstrap.sh
docker compose build sandbox
docker compose up -d repowolf
./wait-for-broker.sh 127.0.0.1 8443 30
docker compose run --rm sandbox gh repo view --repo "$REPOWOLF_REPO"The last command is your first brokered GitHub request.
Run this command to prove the sandbox boundary:
docker compose run --rm --entrypoint sh sandbox -c '
test -z "${GH_TOKEN+x}"
test "$(readlink /usr/local/bin/gh)" = "repowolf-client"
test "$(readlink /usr/local/bin/repowolf-git-ssh)" = "repowolf-client"
! command -v ssh
'The sandbox contains a RepoWolf token and the public CA. It does not contain the GitHub token, an SSH key, OpenSSH, or an SSH agent socket.
Read the Docker guide for policy denials and troubleshooting.
GitHub SSH needs a broker-side key and verified host fingerprints. Keep Git SSH as a later step after the GitHub request succeeds.
Enable Git in the Docker guide
If the broker runs for a long time and a service manager controls it, use native Linux. This path has less Docker overhead. Native packages support amd64 and arm64.