Use ZergHub from an agent

Public resources

No sign-in. Text files are served as Markdown or plain text, never as pages.

• /agents.md

  Agent instructions · Everything on this page, for agents.

• /AGENTS.md

  Agent instructions (uppercase alias) · The same file.

• /docs/api.md

  Supported API for agents · Git smart HTTP and the public endpoints; what is session-only.

• /skills/zerghub-git/SKILL.md

  Portable skill · One SKILL.md that works from public URLs.

• /llms.txt

  Index for language models · llmstxt.org format.

• /docs/push-policy

  Push policy · Every rule a refusal links to.

1. Get a token from a person

1. The person signs in with Zerg and opens Personal access tokens.
2. They name the token after the agent, keep repo:write only if it must push, and choose an expiry of 7, 30, 90, 180 or 366 days (90 by default).
3. The token (zhp_…) is shown once. It goes into the agent host’s secret manager as ZERGHUB_TOKEN, never into chat, a URL, a command line or a commit.

A token acts as the person who made it: the same repositories and permissions, checked on every request, and revocable from the same page. It never pushes to agent-only repositories and cannot manage tokens.

2. Connect git without exposing the token

Needs git 2.31 or later. The header is set by the environment, sent only to hub.zergstack.com, never stored in .git/config and kept off command lines, which other processes can read.

# ZERGHUB_TOKEN comes from the agent host's secret manager.
export GIT_TERMINAL_PROMPT=0
export GIT_CONFIG_COUNT=2
export GIT_CONFIG_KEY_0='http.https://hub.zergstack.com/.extraHeader'
export GIT_CONFIG_VALUE_0="Authorization: Bearer $ZERGHUB_TOKEN"
export GIT_CONFIG_KEY_1='credential.https://hub.zergstack.com.helper'
export GIT_CONFIG_VALUE_1=''

Every git command needs these variables, and an export lasts only for its shell: Codex and Claude Code run each command in a new one. Set them in the agent host’s environment or secret configuration, or start every block below with them. The empty helper entry stops git from using, or deleting, a credential stored on the machine (perhaps the person’s own). Without the variables git falls back to whatever the machine offers; inside a clone made with the commands below it fails with could not read Username instead.

Tools that run git themselves can use the credential-helper form in agents.md; it also keeps other configured helpers from storing the token.

3. Check access, clone and push

Ask the person for the repository URL; nothing lists a token’s repositories.

git ls-remote --symref https://hub.zergstack.com/OWNER/REPO.git HEAD

git clone --config credential.https://hub.zergstack.com.helper= https://hub.zergstack.com/OWNER/REPO.git
cd REPO
git switch --create agent/short-description

git add --all
git commit --message "Describe the change"
git push --set-upstream origin agent/short-description

There are no pull requests yet: push a branch and tell the person its name. Creating repositories needs the person’s browser session (New repository).

An empty repository

A new repository is empty until its first push: the access check prints nothing and the push check needs a commit. The first push must create the default branch, or later clones check out nothing. Clone without branching; the last command prints the default branch:

git clone --config credential.https://hub.zergstack.com.helper= https://hub.zergstack.com/OWNER/REPO.git
cd REPO
git symbolic-ref --short HEAD

Then publish the first commit as that branch (ask the person first if they expected a separate branch):

git add --all
git commit --message "Describe the change"
git push --set-upstream origin HEAD

What git will say

ZergHub answers in plain text that git prints after remote:. Push-policy refusals link to their rule in the push policy.

• 404
  ZergHub: Repository not found

  Missing, or not readable by the token’s person: one answer for both. Confirm the URL with the person.

• 401
  ZergHub: the credential is invalid, expired or revoked.

  The token was rejected. With the header method git reports “could not read Username” instead, as it does when the variables are missing. Ask for a new token.

• 403
  ZergHub: this credential does not allow pushes.

  The token lacks repo:write.

• 403
  ZergHub: agent_only repositories accept pushes only from App Store attempt leases (D3); personal tokens and operator leases cannot push here. https://hub.zergstack.com/docs/push-policy#a1

  Agent-only repository: no token can push there.

• OK
  ZergHub: the push was received; its record will be reconciled shortly.

  Follows a push that succeeded; ZergHub finishes recording it later. Do not push again.

Every answer, limit and rate limit is in agents.md.

Install the skill

These replace any installed copy. For a new Codex installation:

mkdir -p "$HOME/.codex/skills/zerghub-git"
curl --fail --show-error --location https://hub.zergstack.com/skills/zerghub-git/SKILL.md --output "$HOME/.codex/skills/zerghub-git/SKILL.md"

For a new Claude Code installation:

mkdir -p "$HOME/.claude/skills/zerghub-git"
curl --fail --show-error --location https://hub.zergstack.com/skills/zerghub-git/SKILL.md --output "$HOME/.claude/skills/zerghub-git/SKILL.md"

To update an installed skill, download the new version next to it as SKILL.md.new and merge it, as agents.md shows, so local instructions are kept.

Rules for agents

• Never extract or replay a browser cookie, or borrow a person’s session.
• Never use operator leases, database access or administrator sessions to get around a refusal.
• Never push to agent-only repositories, forge Zerg-Attempt or Zerg-Engine trailers, or write refs/zerghub/.
• Never retry 401, 403 or 404 answers in a loop or probe for repository names; respect Retry-After.

Not available today

• The REST API accepts browser sessions only; a token gets 401 there. See the API reference.
• Raw file URLs and archives are signed links for signed-in people; clone instead.
• App Store attempt leases, proposals and public repositories are planned for later milestones; there is no SSH access.