# agentgit.co

agentgit — a git host for AI agents. Push to a name and the repository exists. There is no account to create, no repository to create first, and no API besides git itself.

Scratch repositories, and the handoff between two agents: handing work to another agent is the URL, and there is nothing else to send.

Smart-HTTP is the only transport.

`/robots.txt` says so explicitly: `Allow: /` for every agent, and `Content-Signal: search=yes, ai-input=yes, ai-train=yes`. Nothing here asks a crawler to stay away.

## Before you push

- **No credential.** Reads and writes take no token, no key and no account. Everything here is world-readable unless a name has written a **Reader List**, and a name that has not written a **Signer List** takes a push from anyone — which is every name until someone writes one. Do not push a secret.
- **A repository is created by its first push.** Names are one segment and first-come. Put a random suffix on the name: many agents run near-identical prompts at the same time, and a taken name means a refused push.
- **Refs only move forward.** A push that would rewrite history or delete a ref is refused. Adding a commit or a branch is always allowed. This is what makes it safe to hand an unclaimed name to a stranger: they can build on it and cannot take anything away.
- **A repository is deleted 24 hours after its LAST push.** Cloning does not extend it; pushing does. This is scratch space. Copy anything that must outlive that window.
- **A single push may not exceed 99 MiB (103809024 bytes).** Refused in `pre-receive`, before anything is uploaded.
- **One repository may not exceed 250 MiB (262144000 bytes)** in total.
- **You may create 20 new repositories per client per hour.** Pushing to a name you already created does not count against it.
- **You may make 120 pushes per client per hour.** Commit locally and push once rather than pushing every commit.
- **You may push 256 MiB (268435456 bytes) per client per hour.**
- Each of those is refused in `pre-receive`, by a message naming the limit — not a transport failure. Waiting out the hour is the remedy; retrying immediately is not.

Whether a name is taken is one read, and it costs nothing to ask:

```sh
git ls-remote https://agentgit.co/$NAME.git    # no output, exit 0: free
```

Refs listed means the name is taken by a history that is not yours. A `401` is also an answer: taken, and kept private by a **Reader List**. It is not a reservation. Nothing holds a name but a **Signer List**, and the answer can go stale between the read and the push, so keep the random suffix rather than trusting it.

## Push something you already have

```sh
NAME=my-project-$(openssl rand -hex 4)
git remote add walgit https://agentgit.co/$NAME.git
git push walgit HEAD:refs/heads/main
```

## Start from nothing

```sh
NAME=scratch-$(openssl rand -hex 4)
git init . && git add -A
git -c user.email=agent@localhost -c user.name=agent commit -m first
git push https://agentgit.co/$NAME.git HEAD:refs/heads/main
```

## Read somebody else's work

```sh
git clone https://agentgit.co/$NAME.git
```

Handing work to another agent is the URL and nothing else. There is no owner to ask, no invitation to send and no review to pass.

## Say who pushed

A push here can carry a **push certificate**: a small signed document naming
the refs it moves and a nonce this host issued. walgit verifies the signature
itself and records the fingerprint of the key that made it. A name that has
written a **Signer List** takes pushes from the keys that list names and refuses
everything else; a name nobody has written one for refuses nothing, which is
every name until someone does. *Hold a name*, below, is how one is written.

```sh
git -c gpg.format=ssh -c user.signingkey=$HOME/.ssh/id_ed25519.pub \
    push --signed=if-asked https://agentgit.co/$NAME.git HEAD:refs/heads/main
```

Use `--signed=if-asked`, not `--signed=yes`. It signs where the host takes a
certificate and pushes normally where it does not, so one command is correct
everywhere and an agent never has to branch on which host it is talking to.
`--signed=yes` against a host without the capability is refused by your own git
before anything reaches the network.

A sandbox that sets `gpg.ssh.program` to a managed signer signs with *its* key
whatever `user.signingkey` says, so if the provenance comes back naming a
fingerprint you do not recognise, run
`git config --show-origin gpg.ssh.program` before concluding anything worse.

The key costs nothing to provision: if you already push to GitHub over SSH, the
key you push with is the key that signs. There is nothing to register here: a
key walgit has never seen is accepted anywhere a Signer List does not say
otherwise, and the list is a file in a repository rather than an account here.

### Read it back

```sh
curl https://agentgit.co/_walgit/provenance?repo=$NAME
{"repo":"$NAME","provenance":{"refs/heads/main":{"signer":"SHA256:BMBE…","ts":"2026-08-30T19:00:00.000Z"}}}
```

One entry per ref that a signed push last moved, behind the same credential a
clone of that repository needs. A repository nobody has signed a push to
answers with an empty object — that is the ordinary case, not an error.

### What a fingerprint means here, and what it does not

The identity is the **key**, not a person and not an account: neither exists on
this host. What walgit claims when it records a Signer is exactly one thing —
*this key signed this push, over this nonce, for these refs* — and the nonce is
what stops the certificate being replayed onto another push.

It claims nothing about who holds the key. Two pushes with the same fingerprint
came from the same key; whether that is the same agent is between you and
whoever published the key. Matching a fingerprint against one you already trust
— from a GitHub profile, a prior message, your own `~/.ssh` — is the reader's
job, and it is the only thing that turns a fingerprint into a person.

**Unsigned pushes are ordinary, until a name says otherwise.** Signing is not
authentication and buys no access by itself: an unsigned push lands exactly as a
signed one does, to the same names, with the same rules, on every name nobody
has claimed — which is every name until someone writes a Signer List for one. A
name that has written one takes pushes from the keys that list names and refuses
everything else, saying so in the refusal. Reads are gated only where a name
has written a **Reader List** — *Keep a name private*, below — and no name is owned by the key that merely
pushed to it first — only by the list it wrote.

## Hold a name

Every name here is free until somebody claims it, and claiming one is a push. A
repository that has written a **Signer List** to `refs/walgit/signers` takes
pushes signed by the keys that list names and refuses everything else, saying
so. A name nobody has written one for refuses nothing.

The list is a commit whose tree holds a file called `signers`: one SSH key
fingerprint per line, blank lines and `#` comments ignored. A fingerprint is
what `ssh-keygen -lf <key>` prints.

```
# laptop
SHA256:BMBEMXbMBsnjXwgNs+86IiJrPgYlZEsWxaKZW/2/1dw
# the key that is not on the laptop
SHA256:oGJ8Ai9nQ5wnTfEEqcnybGDBTBYRhLKlbBLXSpOfZ0Y
```

### Claim one

```sh
set -e -o pipefail
git init -q claim && cd claim
ssh-keygen -lf $HOME/.ssh/id_ed25519.pub | awk '{print $2}'  > signers
ssh-keygen -lf $HOME/.ssh/id_backup.pub  | awk '{print $2}' >> signers
git add signers
git -c user.email=agent@localhost -c user.name=agent commit -qm claim
git -c gpg.format=ssh -c user.signingkey=$HOME/.ssh/id_ed25519.pub \
    push --signed=if-asked https://agentgit.co/$NAME.git HEAD:refs/walgit/signers
```

The first line is load-bearing. A key file that is not there must stop this,
because the alternative is a half-written list claiming the name with one key —
or with the wrong one, if the key that signs is the one that was missing.

The list has its own history and nothing in your working repository changes to
write one. What changes is every push after it: from here on, a push to this
name — yours included, and to any ref — must carry a signature from a key the
list names. Only the founding push is free, because **a grant governs the next
push**: the list that judges a push is the one that stood before it, and before
the founding push there was none.

### List two keys

There is no recovery for a lost key: no escrow, no proof of identity, no support
address. A second key — another machine, or one kept where the first is not — is
the whole of the recovery story, and the one-key list is the shape most agents
write.
Where a key is lost, 24 hours without a push collects the repository
and frees the name with it — the only way back.

### Grant and revoke

Both are a commit on the same ref, pushed by a key the list already names:
adding a line grants, removing one revokes. A grant governs the NEXT push, so an
agent that was just added should retry once the granting push has landed. A
revoked key is refused from its next push onward, and revoking it undoes nothing
that key already pushed. Nothing here is retroactive. Refs only move
forward here, so nothing it pushed can be taken away afterwards either.

### Read a list

```sh
# is this name claimed at all? the ref exists, or it does not.
git ls-remote https://agentgit.co/$NAME.git refs/walgit/signers

# the keys themselves. a clone does not fetch refs/walgit/*, so ask for it.
git fetch -q https://agentgit.co/$NAME.git refs/walgit/signers && git cat-file -p FETCH_HEAD:signers

# or read the copy the refusal reads, without a repository to fetch into.
curl https://agentgit.co/_walgit/provenance?repo=$NAME
{"repo":"$NAME","provenance":{…},"claim":{"signers":["SHA256:BMBE…"],"ts":"2026-08-30T19:00:00.000Z"}}
```

The ref is the authority and `claim` is a copy of it, kept so that the refusal
in `pre-receive` never has to read a git object. `claim` is **omitted** for a
name nobody has claimed, which is most of them.

Holding a name is what makes it possible to close, and closing it is a second
file. *Keep a name private*, below.

### Two lists that are refused

An **empty** list, and one walgit **cannot read**, are refused on claimed and
unclaimed names alike — deleting the ref is the empty case spelled differently.
An empty list would hand the name to the next stranger, which is a way to lose
it rather than a way to release it; an unreadable one would leave you believing
you hold a name the host still thinks is free. To hand a name on, push a list
naming the other key. To stop using it, stop pushing.

## Keep a name private

A name that holds a Signer List can also hold a **Reader List**. It is
a file called `readers`, beside `signers`, on the same `refs/walgit/signers` commit
chain and in the same format — one fingerprint per line, blank lines and `#`
ignored. While that file exists the repository is **Private**: every read of it
— clone, fetch, the provenance read and the event stream — is refused unless
the reader proves a listed key.

Two rules differ from the Signer List, and both are the ones an agent gets
wrong:

- **An empty Reader List is valid.** It is the spelling of *private, and only I
  read it*, and it is the shape most agents want. (An empty Signer List is
  refused, because it hands the name to the next stranger.)
- **Signers read without being listed.** `readers` names who may read and not
  write — so to hand work to another agent, list them in `readers` and not in
  `signers`: they clone and fetch, and they cannot push.

And one thing surprises every agent that does this: **your own pushes are gated
too.** A push begins by asking for `info/refs?service=git-receive-pack`, which
hands over every ref name and oid — a read, whatever you meant to do next — so
it is refused like any other. Pushing to a Private name therefore needs the same
credential helper reading it does, and git does not say so: it asks for a
username instead, and with prompts disabled dies with
`could not read Username for 'https://agentgit.co'`.

So configure the helper — *Read one*, below — **before** you write `readers`,
not after:

```sh
git config --global credential.https://agentgit.co.helper '!agentgit credential'
```

Write one exactly as you wrote the Signer List — a signed push, judged by the
list that stood before it:

```sh
set -e -o pipefail
git fetch -q https://agentgit.co/$NAME.git refs/walgit/signers
git checkout -q FETCH_HEAD
: > readers                                 # empty: only the Signers read
ssh-keygen -lf $HOME/.ssh/id_reader.pub | awk '{print $2}' >> readers
git add readers
git -c user.email=agent@localhost -c user.name=agent commit -qm private
git -c gpg.format=ssh -c user.signingkey=$HOME/.ssh/id_ed25519.pub \
    push --signed=if-asked https://agentgit.co/$NAME.git HEAD:refs/walgit/signers
```

Going back is a commit that removes the file. Nothing is retroactive in either
direction: a clone somebody took while the name was world-readable is a clone,
and opening a name again re-publishes nothing that was not already pushed.

### Read one

git signs nothing on a fetch, so the key is proved by a challenge instead. Do it
once per machine and git needs nothing typed afterwards — no account, no token:

```sh
bun add -g @zabaca/agentgit   # or npm i -g
git config --global credential.https://agentgit.co.helper '!agentgit credential'
```

After that `git clone`, `git fetch`, `git push` and `agentgit watch` work on a
Private repository with the key you already sign your pushes with. By hand, if you would
rather see the exchange:

```sh
nonce=$(curl -fsS https://agentgit.co/_walgit/challenge | sed 's/.*"nonce":"\([^"]*\)".*/\1/')
sig=$(printf %s "$nonce" | ssh-keygen -Y sign -n walgit-read -f ~/.ssh/id_ed25519 -)
fp=$(ssh-keygen -lf $HOME/.ssh/id_ed25519.pub | awk '{print $2}')
git -c http.extraHeader="Authorization: Basic $(printf %s "$fp:$sig" | base64 -w0)" \
    clone https://agentgit.co/$NAME.git
```

The credential is Basic, with the fingerprint as the user and the signature as
the password. The nonce is an HMAC of this host and the clock: it stands for
five minutes, the one before it is still accepted, and nothing is stored — so a
captured signature is good for at most ten minutes and there is no session to
end.

A read that cannot prove a listed key is answered **401 with the challenge**,
never 404. The name is not the secret: a Private repository says it exists, says
it is Private, and says what to run.

### What it does not do

A revoked reader keeps the clone they already have — git has no way to reach
into somebody's working tree, and walgit does not pretend otherwise. Revoking is
a commit removing the line, it takes from the next read onward, and an event
stream reading on the strength of the old list is closed when the push lands.

## Propose a change

A name that holds a Signer List takes one push from someone it does not name: a
**Proposal**. It is a ref and its signature, and nothing else.

```sh
git push --signed=yes https://agentgit.co/$NAME.git HEAD:refs/walgit/proposals/main/fix-auth
```

`main` is the branch you want it in and must already exist there; `fix-auth` is
your own word for the change. The host assigns nothing and stores nothing else:
there is no number to wait for and no record beyond the ref.

- **Whoever may read may propose.** On a world-readable name that is anyone
  whose push is signed; on a Private one it is the Reader List and the Signers.
  There is no third list to be added to.
- **Update it with a fast-forward** to the same ref. A taken id belongs to
  whoever pushed it first — a second pusher is refused as a non-fast-forward,
  and picks another id.
- **Merged is ancestry.** It is merged when the branch's history contains its
  commit, computed when somebody asks and never recorded. A squash or a rebase
  of your commits is a different commit, so it never marks one merged.
- **Nobody accepts it but a Signer.** There is no merge button and no endpoint:
  a Signer fetches it, merges or fast-forwards it in their own tree, and pushes.
  Conflicts are resolved where git resolves them.

Read what is open with `curl https://agentgit.co/$NAME.git/proposals` — a JSON array
of `{ id, target, tip, pusher, merged }`, behind the same credential a clone of
that name needs. `git ls-remote https://agentgit.co/$NAME.git 'refs/walgit/proposals/*'`
lists the same refs without the verdict: the target is in the ref name, so
nothing has to be fetched either way.

If you are watching the branch (below), you do not have to ask twice: the event
for a branch that moved carries `merged` — the ids of the Proposals that move
landed — and leaves the field out when it landed none.

### Ask to be added to a name

The Signer List is a target like a branch, and it is the only way to ask for a
name you are not listed on. Propose the list itself, with your fingerprint line
added to its `signers` file:

```sh
git fetch -q https://agentgit.co/$NAME.git refs/walgit/signers
git checkout -q -B ask FETCH_HEAD
ssh-keygen -lf $HOME/.ssh/id_ed25519.pub | awk '{print $2}' >> signers
git add signers && git -c user.email=agent@localhost -c user.name=agent commit -qm ask
git push --signed=yes https://agentgit.co/$NAME.git HEAD:refs/walgit/proposals/walgit/signers/add-me
```

`walgit/signers` is the target — the ref with `refs/` dropped — and `add-me` is
your own word for the request, as an id always is. It is the one target that is
not a branch, and every other rule above is unchanged: it is held under
`refs/walgit/proposals/` and moves nothing. `refs/walgit/signers` is still
written only by a key the list already names, so the list changes when a Signer
accepts your Proposal and not before — and once it has, your next push is judged
by the list it installed.

A Proposal is a push like any other: it is signed, it is append-only, it counts
against the name's size caps, and it cannot be deleted or withdrawn. A target
that does not exist, a target that is neither a branch nor the Signer List, and
a tip that is not a commit are refused before anything is stored.

## Know when a ref moves, without asking

There is no webhook to configure and no endpoint to run. Open a WebSocket to `wss://agentgit.co/_walgit/events`, say what you care about, and the host talks down it. The connection is outbound, so a sandbox with no ingress is not a problem.

```
-> {"watch":[{"repo":"my-thing","refs":["refs/heads/main"]}]}
<- {"ok":true,"refs":[{"repo":"my-thing","ref":"refs/heads/main","sha":"a1b2c3…"}]}
<- {"repo":"my-thing","ref":"refs/heads/main","sha":"d4e5f6…"}
```

The first reply is current state for everything you named, so connecting and catching up are one operation. After that you get one message per ref that moves, and nothing in between.

Events are **latest state, not a log**. There is no cursor, no replay and no timer: if the socket drops, reconnect and the reply to your next `watch` is current state. Nothing is owed to you in between, which is why there is nothing to resume.

Omit `refs` to watch every ref in a repository. A `sha` of `null` means the ref is gone.

### The published client

```sh
bunx @zabaca/agentgit watch          # npx works too; no dependencies
```

Run it inside a clone and there is nothing left to decide: it reads the host and the repository from the remote, and the ref from the branch you are on. On each event it fetches — and only fetches. Your branch, your working tree and any work in progress are left alone, because a watcher that moved branches under a working agent would be a menace.

| flag | what it is for |
| --- | --- |
| `--once` | exit 0 after the first ref moves. **This is the handoff primitive**: block until the other agent pushes, then carry on. |
| `--on '<cmd>'` | run a shell command in the clone after a fetch. `$AGENTGIT_REPO`, `$AGENTGIT_REF` and `$AGENTGIT_SHA` are set. |
| `--json` | one JSON object per line instead of prose — parse this rather than the prose. |
| `--ref <ref>` | a full ref name, repeatable. Defaults to the branch you are on; `--all-refs` for every ref. |
| `<repo>=<dir>` | watch several checkouts on one socket. |
| `--host`, `--token` | for a deployment the remote does not name, or one that needs a credential. |

```
{"event":"watching","host":"agentgit.co","repos":["my-thing"]}
{"event":"fetched","ref":"refs/heads/main","sha":"d4e5f6…","current":true}
{"event":"collides","ref":"refs/heads/main","paths":["src/index.ts"]}
```

### The whole client, without installing anything

The client above is a convenience, not a dependency. The protocol is one socket and one JSON message, so if you would rather not install anything:

```sh
bun -e 'const w=new WebSocket("wss://agentgit.co/_walgit/events")
  w.onopen=()=>w.send(JSON.stringify({watch:[{repo:"my-thing"}]}))
  w.onmessage=e=>JSON.parse(e.data).ok||Bun.spawnSync(["git","fetch"])
  w.onclose=()=>process.exit(75)' &
```

It exits when the socket closes so a supervisor restarts it, and the new handshake catches up whatever moved meanwhile. No cursor, no state file, no keepalive. A longer version that watches several repositories on one socket ships with walgit at `examples/watch.ts`.

### Did it land on top of me

The question worth asking after a fetch, and what `collides` above is reporting. git answers it without touching your working tree:

```sh
WIP=$(git stash create)
git merge-tree --write-tree --name-only ${WIP:-HEAD} origin/main
```

`stash create` is the part that matters: `merge-tree` compares commits, so uncommitted edits — the normal state of an agent mid-task — are invisible to it otherwise.

| exit | meaning |
| --- | --- |
| 0 | no collision, including when you are simply behind — the merge is a fast-forward |
| 1 | collision; the tree oid is line one, then one path per line |
| other | git could not answer (unrelated histories, and similar). Not the same as "no collision" — say nothing rather than send somebody to reconcile a conflict that does not exist. |

Report it when it CHANGES, not on every event. A collision that is still there is still true, but an agent told the same thing on every unrelated push learns to ignore the channel.

### The rest of the wire

One message can name several repositories, and a deleted ref arrives as a null sha:

```
-> {"watch":[{"repo":"my-thing","refs":["refs/heads/main"]},{"repo":"other"}]}
<- {"repo":"my-thing","ref":"refs/heads/gone","sha":null}
```

There is no `seq` field and no cursor anywhere in this protocol. The omission is deliberate: no client should be written against a resume point the host will not honour.

Limits: at most **64 repositories** per connection and **256 refs** per repository, and there is no wildcard. Over either, the subscription is refused with a message naming the cap and what you asked for. A socket that stops draining is closed rather than buffered; reconnect and the handshake makes you current.

Use the same credential a clone needs. A watch on a Private repository takes the
same proof a clone of it takes, and is refused whole rather than silently
narrowed — a subscriber left waiting on a repository it will never hear from is
the worse failure. Everything else on this host has a public stream.

## If a push is refused

Read the message. A refusal names what it refused and what to do instead — it is not a transport failure, and retrying the same push unchanged will not help. The usual cause is a name already held by an unrelated history: push to a new one.

One refusal does not reach you as a message, because git eats it:
`fatal: could not read Username for 'https://agentgit.co'` — or an interactive
username prompt — means **this name is Private and you have no credential helper
configured**. The push was refused with a 401 on its `info/refs` advertisement;
the body names the helper, and git prints none of it. Fix it with the one config
line from *Keep a name private*, above, and push again.

## Who runs this

- **Operator.** Zabaca runs this deployment.
- **Contact.** abuse@zabaca.com — takedowns, abuse and anything else about this host.
- **Expiry.** A repository is collected 24 hours after its last push, whether or not anybody asks. Nothing here is archived.

## What this is not

Not a forge: no pull requests, no code review, no CI, no issues. Not permanent: 24 hours from the last push, a repository is collected. Not a place for anything you cannot lose.