[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81999":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":22,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":15,"starSnapshotCount":15,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},81999,"octopool","openclaw\u002Foctopool","openclaw","A shared, org-authenticated GitHub read relay and cache.","https:\u002F\u002Foctopool.dev",null,"TypeScript",85,6,27,0,3,41,2.54,"MIT License",false,"main",true,[24,25,26],"cache","github","shared","2026-06-12 02:04:22","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"docs\u002Fassets\u002Foctopool-github-app-512.png\" alt=\"octopool\" width=\"128\" height=\"128\">\n\n# octopool\n\n**Pool your org's GitHub identities behind a shared Cloudflare cache.**\n\nA self-hosted GitHub read relay. One Cloudflare Worker holds your team's PATs and GitHub App installations, picks the healthiest one per request, and caches the response in D1 so the next caller doesn't burn a single token of rate limit.\n\n[App](https:\u002F\u002Foctopool.openclaw.ai) · [Docs](https:\u002F\u002Fdocs.octopool.dev) · [Relay API](https:\u002F\u002Fdocs.octopool.dev\u002Frelay.html) · [CLI](https:\u002F\u002Fdocs.octopool.dev\u002Fcli.html) · [Spec](https:\u002F\u002Fdocs.octopool.dev\u002Fspec.html)\n\n\u003C\u002Fdiv>\n\n![Octopool banner](docs\u002Fassets\u002Freadme-banner.jpg)\n\n---\n\n## Why octopool\n\nA maintainer team plus a few bots can chew through GitHub's primary rate limit fast. Every developer carries their own PAT, every GitHub App installation has its own budget, and they all run the same handful of read shapes (`gh pr view`, `gh pr checks`, `gh run list`, `gh issue list`, `gh api repos\u002F...\u002Fpulls\u002FN`) against the same repos, over and over.\n\nOctopool moves that traffic off individual machines and onto Cloudflare:\n\n- **One pool, one cache.** PATs and GitHub App private keys live as Cloudflare Worker secrets, not on laptops or in CI logs. The Worker routes each cache miss to one healthy identity and writes the result into a D1 read-through cache that every other caller hits next.\n- **Rate budgets add up.** Each identity keeps its own GitHub rate-limit bucket. Five PATs + one GitHub App ≈ five-plus-one combined headroom. A per-pool Durable Object picks the identity with the most remaining budget for the target resource and holds a short sticky lease so concurrent callers don't stampede the same one.\n- **Cache hits cost zero GitHub quota.** Fresh D1 hits return straight from Cloudflare without touching GitHub at all. Repeated maintainer reads stop consuming any pooled identity's budget.\n- **Tokens stay server-side.** Callers authenticate to octopool with a short caller token (issued in exchange for their `gh auth token`). The underlying PATs and App private keys never leave the Worker — not into responses, not into audit rows, not into the cache.\n- **Org-gated, public-repo only.** Only verified members of one GitHub org can mint a caller token, and every repo route is checked against GitHub's public-visibility endpoint before a pooled identity or cache entry is used. Private-repo callers fall back to their own `gh`.\n- **Fails open to real `gh`.** The CLI is a drop-in `gh` shim. Safe read-shaped calls try Octopool first, so the server owns cache, app\u002FPAT routing, and pool policy. Mutations and secret-bearing requests stay local; safe reads run your real `gh` only when Octopool explicitly returns `fallback_local`.\n\nIf you're not running a maintainer team and you don't care about GitHub rate limits, you don't need this.\n\n## Architecture\n\n```text\n   developers \u002F bots                Cloudflare                          GitHub\n   ─────────────────                ──────────                          ──────\n   octopool gh ...   ── caller ──▶  Worker (octopool)\n                       token        ├── auth + org-membership check\n                                    ├── route classify + per-pool policy\n                                    ├── public-repo guard ─────────────▶ GET \u002Frepos\u002F:o\u002F:r\n                                    ├── D1 cache lookup ─── hit ───────▶ return cached\n                                    │                       miss\n                                    ├── PoolCoordinator (Durable Object)\n                                    │     picks one identity ──────────▶ GET \u002Frepos\u002F...\u002Fpulls\u002FN\n                                    │     records rate + cooldowns       with pooled PAT\u002FApp token\n                                    ├── write D1 cache (public 200s)\n                                    └── audit row (no secrets)\n```\n\n- **Worker** (`src\u002Findex.ts`) — HTTP, auth, policy, response shaping.\n- **PoolCoordinator** Durable Object (one per pool) — per-identity rate snapshots, sticky route leases, cooldowns.\n- **D1** — pools, callers, identities, audit events, public-repo proofs, read-through cache.\n- **Cloudflare Worker secrets** — pooled PATs and GitHub App PKCS#8 private keys. Never in D1, never in logs.\n\n## Use it (CLI)\n\nIf your org already runs octopool, install the CLI and log in:\n\n```sh\nbrew install openclaw\u002Ftap\u002Foctopool\n# or: go install github.com\u002Fopenclaw\u002Foctopool\u002Fcmd\u002Foctopool@latest\n\noctopool login                                  # default endpoint: https:\u002F\u002Foctopool.dev\noctopool login https:\u002F\u002Foctopool.your-org.dev    # self-hosted endpoint\noctopool whoami\n```\n\nUse it like `gh` for common read shapes:\n\n```sh\noctopool gh pr view 85341 -R openclaw\u002Fopenclaw --json number,title,url\noctopool gh pr checks 85341 -R openclaw\u002Fopenclaw --json name,state,bucket\noctopool gh issue list -R openclaw\u002Fopenclaw --state open --json number,title,url\noctopool gh run list -R openclaw\u002Fopenclaw --branch main --limit 10 --json databaseId,status\noctopool gh api repos\u002Fopenclaw\u002Fopenclaw\u002Fpulls\u002F85341 --jq .number\noctopool stats\n```\n\nSymlink it as `gh` for a transparent shim — safe reads try Octopool first, while mutations, unusual flags, and explicit server fallback signals pass through to your local `gh`:\n\n```sh\nln -s \"$(command -v octopool)\" ~\u002Fbin\u002Fgh\n```\n\nFull command surface, fallback rules, and discovery details: [docs.octopool.dev\u002Fcli](https:\u002F\u002Fdocs.octopool.dev\u002Fcli.html).\n\n## Deploy it (Cloudflare)\n\nOctopool is built to be self-deployed per org. You'll need:\n\n- a Cloudflare account on the Workers Paid plan (Durable Objects + D1),\n- a domain you can route at a Worker (Cloudflare-managed, or with a CNAME you control),\n- a GitHub org you can verify membership against, and\n- at least one GitHub identity to pool — a PAT or a GitHub App installation.\n\n### 1. Clone and configure\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002Fopenclaw\u002Foctopool.git\ncd octopool\npnpm install\n```\n\nEdit `wrangler.jsonc` for your account:\n\n- `account_id` — your Cloudflare account id.\n- `vars.ALLOWED_GITHUB_ORG` — the GitHub org whose members may mint caller tokens.\n- `vars.DEFAULT_ALLOWED_OWNERS` — comma-separated GitHub owners (orgs\u002Fusers) whose repos this pool may read.\n- `vars.GITHUB_OAUTH_CLIENT_ID` — the OAuth client id of your GitHub App (for browser sign-in).\n- `vars.GITHUB_OAUTH_CALLBACK_ORIGIN` — optional HTTPS origin registered as the GitHub OAuth callback when browser sign-in starts on a different host.\n- `routes[]` — the custom domain you want octopool served on.\n\nIf you don't need OpenClaw's second-host proxy, you can ignore `wrangler.openclaw-proxy.jsonc` and deploy only the main Worker.\n\n### 2. Create the data plane\n\n```sh\nwrangler d1 create octopool\n# copy the printed database_id into wrangler.jsonc d1_databases[].database_id\n\nwrangler d1 migrations apply octopool --remote\n```\n\nThe `PoolCoordinator` Durable Object class is created by the migration tag in `wrangler.jsonc` on first deploy — no separate step.\n\n### 3. Put secrets in Cloudflare\n\nNever in `wrangler.jsonc`, never in D1, never in logs:\n\n```sh\nwrangler secret put OCTOPOOL_ADMIN_TOKEN              # used to provision callers\u002Fidentities\nwrangler secret put GITHUB_OAUTH_CLIENT_SECRET        # browser GitHub login (companion to GITHUB_OAUTH_CLIENT_ID)\nwrangler secret put OCTOPOOL_GITHUB_ORG_TOKEN         # background org-membership + public-repo proofs\nwrangler secret put OCTOPOOL_GITHUB_APP_ID            # only if you use GitHub App identities\n# one secret per pooled identity, referenced by name from D1:\nwrangler secret put OCTOPOOL_PAT_ALICE                # raw PAT value\nwrangler secret put OCTOPOOL_GITHUB_APP_PRIVATE_KEY   # PKCS#8 (BEGIN PRIVATE KEY) PEM\n```\n\nFull secret list and rotation notes: [docs.octopool.dev\u002Foperations](https:\u002F\u002Fdocs.octopool.dev\u002Foperations.html).\n\n### 4. Deploy the Worker\n\n```sh\nwrangler deploy\n```\n\nDNS-managed-by-Cloudflare domains register the custom domain in `routes[]` automatically; otherwise CNAME your domain at the Worker once.\n\n### 5. Provision a caller and at least one identity\n\n```sh\nexport OCTOPOOL_ADMIN_TOKEN=...                              # the value you put above\nexport OCTOPOOL_URL=https:\u002F\u002Foctopool.your-org.dev\n\n# Register a teammate (verified against ALLOWED_GITHUB_ORG by GitHub user id):\noctopool admin caller --pool maintainers --github-login alice --name \"Alice\"\n\n# Pooled PAT identity:\noctopool admin identity \\\n  --pool maintainers \\\n  --id pat_alice --login alice \\\n  --secret-ref OCTOPOOL_PAT_ALICE \\\n  --scope your-org\n\n# Or a GitHub App identity (PKCS#8 private key under secret-ref):\noctopool admin identity \\\n  --pool maintainers \\\n  --kind github_app --installation-id 135990630 \\\n  --id ghapp_your-org_core --login your-cache-app \\\n  --secret-ref OCTOPOOL_GITHUB_APP_PRIVATE_KEY \\\n  --scope your-org\u002Fcore\n```\n\nThe first reference to a pool by name (here, `maintainers`) creates it with the default policy (owners = `DEFAULT_ALLOWED_OWNERS`, `allow_search: false`, `allow_logs: true`). Teammates can now `octopool login https:\u002F\u002Foctopool.your-org.dev` and start using the relay; the identities you registered take turns serving cache misses.\n\n### 6. Verify\n\n```sh\ncurl https:\u002F\u002Foctopool.your-org.dev\u002F.well-known\u002Foctopool\n# {\"service\":\"octopool\",\"version\":1,\"api_base\":\"...\",\"default_pool\":\"maintainers\", ...}\n\noctopool stats     # cache hit rate, top routes, per-caller usage\npnpm e2e           # smoke-test the live deployment\n```\n\nA browser-side operator dashboard lives at `\u002Fdashboard` — GitHub-OAuth gated, requires `dashboard_role = 'admin'` on the caller row. See [docs.octopool.dev\u002Fdashboard](https:\u002F\u002Fdocs.octopool.dev\u002Fdashboard.html).\n\n## What's in the box\n\nAll docs are on [docs.octopool.dev](https:\u002F\u002Fdocs.octopool.dev):\n\n- [GitHub read relay](https:\u002F\u002Fdocs.octopool.dev\u002Frelay.html) — `POST \u002Fv1\u002Fgithub\u002Frequest`, the supported route allowlist, response envelope, and safety caps.\n- [Octopool CLI](https:\u002F\u002Fdocs.octopool.dev\u002Fcli.html) — `octopool login`, the `gh` shim, cache stats, and real-`gh` fallback.\n- [Pooled identities & routing](https:\u002F\u002Fdocs.octopool.dev\u002Fidentities.html) — PAT and GitHub App identities, scopes, and the coordinator's selection, leases, and cooldowns.\n- [Cache & public-repo guard](https:\u002F\u002Fdocs.octopool.dev\u002Fcache.html) — the D1 read-through cache and public-only visibility enforcement.\n- [Auth & org membership](https:\u002F\u002Fdocs.octopool.dev\u002Fauth.html) — caller auth, admin auth, website sessions, and the GitHub-CLI login exchange.\n- [Admin & provisioning](https:\u002F\u002Fdocs.octopool.dev\u002Fadmin.html) — registering callers and identities.\n- [Dashboard](https:\u002F\u002Fdocs.octopool.dev\u002Fdashboard.html) — browser view for limits, cache, identity, and caller usage stats.\n- [Deployment & operations](https:\u002F\u002Fdocs.octopool.dev\u002Foperations.html) — Cloudflare resources, config, migrations, observability, and the deploy flow.\n\n## Development\n\nThe Worker is TypeScript on Cloudflare Workers; the CLI is Go.\n\n```sh\npnpm install\npnpm check        # format + lint + vitest + types + go test + go vet\npnpm test         # vitest only\npnpm run deploy   # wrangler deploy for the backing Worker (and openclaw proxy)\npnpm e2e          # smoke-test the live deployment\npnpm docs:site    # build the docs site into dist\u002Fdocs-site\npnpm sql:generate # regenerate sqlc-backed query artifacts\ngo build .\u002Fcmd\u002Foctopool\n```\n\nThe docs site is a dependency-free static generator (`scripts\u002Fbuild-docs-site.mjs`) that renders `docs\u002F*.md` into an octopus-themed site, deployed to [docs.octopool.dev](https:\u002F\u002Fdocs.octopool.dev) via GitHub Actions on every push to `docs\u002F`.\n\n## License\n\n[MIT](LICENSE) © openclaw\n","octopool是一个共享的、组织认证的GitHub读取中继和缓存服务。它通过Cloudflare Worker管理团队的个人访问令牌和个人GitHub应用安装，智能选择最健康的令牌处理请求，并将响应结果缓存在D1数据库中，从而有效减少对GitHub API的直接调用次数，避免快速消耗API配额。该项目使用TypeScript开发，支持在需要频繁访问GitHub公开仓库信息且面临API速率限制挑战的场景下使用，如维护者团队或运行多个自动化脚本的情况。通过将身份验证信息集中管理和缓存机制，octopool能够显著提高GitHub API的使用效率与安全性。",2,"2026-06-11 04:07:26","CREATED_QUERY"]