octopool

README

octopool

A shared, org-authenticated GitHub read relay and cache for gitcrawl.

One angry octopus guarding a pool of GitHub identities, so trusted members and agents can run read-heavy maintainer automation without keeping tokens on their machines.

Docs · Relay API · CLI · Spec

---

What it is

Octopool runs on Cloudflare Workers. It accepts a normalized, read-only GitHub request, picks a healthy GitHub identity from a pool, performs the call, caches the result, and returns a clean envelope. Callers never see the underlying GitHub tokens.

It exists to make gh-style reads safe to share:

• Tokens stay server-side. GitHub PATs and App private keys live in Cloudflare secrets, never in local config, logs, or D1.
• One pool, many callers. Requests are routed across identities by remaining rate budget, with short leases and cooldowns to avoid stampedes and abuse flags.
• Public-repository only. Every repo route passes a public-visibility check before any pooled identity or cache entry is used.
• Org-gated. Only verified members of the allowed GitHub org get a caller token, and membership is re-checked as it goes stale.
• Fails safe. The CLI relays only the read shapes Octopool supports and falls through to the real gh for everything else.

Quickstart

Install the CLI (the default endpoint https://octopool.dev is compiled in):

go install github.com/openclaw/octopool/cmd/octopool@latest

Log in with your existing GitHub CLI session — Octopool exchanges your gh token for a caller token and stores it locally:

octopool login
# logged in to https://octopool.dev as you for pool maintainers

Use it like gh api for the supported read routes:

octopool gh api repos/openclaw/openclaw/pulls/85341 --jq .number
# 85341

Symlink it as gh for a transparent shim — supported reads go through the pool, everything else (and any mutation) passes straight to the real GitHub CLI:

ln -s "$(command -v octopool)" ~/bin/gh

How it works

gitcrawl / octopool gh        Cloudflare Worker            GitHub
─────────────────────         ──────────────────          ──────
  octopool gh api  ──▶  authenticate caller (org-gated)
                        classify route + policy
                        public-repo visibility guard ──▶  GET /repos/:o/:r
                        D1 cache lookup ──── hit ──▶  return cached envelope
                        PoolCoordinator picks identity
                        mint token (PAT / App JWT) ──▶  GET api.github.com/...
                        record rate + cooldown
                        write D1 cache
                  ◀──   normalized response envelope

A Durable Object (PoolCoordinator, one per pool) holds per-identity rate snapshots, sticky route leases, and cooldowns so concurrent callers share identities without exhausting or tripping any single one.

Features

Each links to its page on docs.octopool.dev:

• GitHub read relay — POST /v1/github/request, the supported route allowlist, response envelope, and safety caps.
• Octopool CLI — octopool login, the gh shim, and real-gh fallback.
• Pooled identities & routing — PAT and GitHub App identities, scopes, and the coordinator's selection, leases, and cooldowns.
• Cache & public-repo guard — the D1 read-through cache and public-only visibility enforcement.
• Auth & org membership — caller auth, admin auth, website sessions, and the GitHub-CLI login exchange.
• Admin & provisioning — registering callers and identities.
• Landing page & GitHub login — octopool.dev and the OAuth entry.
• Dashboard — GitHub-login-gated browser view for limits, cache, identity, and caller usage stats.
• Deployment & operations — Cloudflare resources, config, migrations, and the deploy flow.

Development

The Worker is TypeScript on Cloudflare Workers; the CLI is Go.

pnpm install
pnpm check        # format + lint + vitest + types + go test + go vet
pnpm test         # vitest only
pnpm deploy       # wrangler deploy
pnpm e2e          # smoke-test the live deployment
pnpm docs:site    # build the docs site into dist/docs-site
go build ./cmd/octopool

The docs site is a dependency-free static generator (scripts/build-docs-site.mjs) that renders docs/*.md into an octopus-themed site, deployed to docs.octopool.dev via GitHub Actions on every push to docs/.

License

MIT © openclaw