{
  "markdown": "# Treg (OpenRouter for Tools)\n\n![treg — the tool catalog for your agent](docs/assets/treg-hero.png)\n\n**OpenRouter, but for agent tools instead of models.** Point an agent at one base URL with one token\nand it can do the job: **2,896 catalogued endpoints across 60 providers** — SEO and backlinks,\nsocial and trends, people and company enrichment, ads, scraping — **priced per call, from a cent**,\nwith no provider signup. Plus your own team's keys, skills and CLIs, callable by every teammate's\nagent without the credential ever leaving the server.\n\n**Ask for the task, not the tool.** You do not need to know which vendor sells backlink data, or to\nhold an account with them. Search for what you want to do, read the price, call it.\n\nBuilt for the Superdesign team, live at [treg.to](https://treg.to) — anyone can self-host.\n\n## Why it exists\n\nThe tools an agent needs for real work sit behind subscriptions nobody buys for a single run —\nSemrush $139/mo, Moz $99/mo, Crunchbase $99/mo, Apollo $59/seat — behind signup walls, or behind no\npublic API at all (invite-only, partner-only, app-review-only). treg carries those accounts and\nbills fractions of a cent per call.\n\n## Two kinds of tool, one token\n\n- **The catalog** — external endpoints treg can serve **on its own key**, metered against your\n  team's prepaid balance (**$1.00 free** on every new team). No account with the provider needed.\n- **Your own tools** — anything a teammate registered: a paid API account, an OAuth connection, a\n  vendor CLI, a `SKILL.md`. **Your own key always wins over treg's, and those calls are never\n  metered.**\n\nThe vocabulary for the second half:\n\n- **tool** = something the registry calls for you with the org's credential. Two kinds:\n  - **endpoint** — an upstream `base_url` + credential **bindings** (each binding injects one\n  secret into the request; a request can carry several, e.g. an OAuth bearer *and* a\n  `developer-token` header).\n  - **CLI** — a vendor binary (`stripe`, `gh`, `vercel`, ...) run with the credential injected.\n- **skill / bundle** = a recipe (`SKILL.md`) + its secrets + its tool(s), registered together.\n\n**The one rule:** the proxy **relays, never models** the upstream, and **injects auth server-side**\n— so it survives upstream API changes and callers never hold keys.\n\n---\n\n# Part 1 · Using the registry\n\nVisit [**treg.to**](https://treg.to) (hosted on Render) — the dashboard,\nsign-in, and every URL below live there.\n\n## Quickstart\n\nSame flow as the dashboard's **Getting started** guide:\n\n```bash\n# 1. install the CLI — also points it at the registry\ncurl -fsSL https://treg.to/install.sh | sh\n\n# 2. sign in (GitHub default · --email for a one-time code · --token for agents/CI)\ntreg login\n\n# 3. do something useful immediately — no key, nothing registered\ntreg catalog search \"backlinks for a domain\"     # find a tool by what it DOES\ntreg call tikhub.tiktok.user.profile --query uniqueId=tiktok\ntreg balance                                     # exactly what that cost\n\n# (or `treg onboard` for the guided walkthrough)\n```\n\nYour token identifies you on every call (`X-Treg-Token` header) and is the same for all tools.\nDiscover what your team has shared: `treg tool ls` · check credential health: `treg health`.\n\n### Or install it as a Claude Code plugin\n\n```\n/plugin marketplace add superdesigndev/treg\n/plugin install treg@treg\n```\n\nInstalls with no token and no configuration. The skill loads as `treg:treg` and, on its first run,\nwalks your agent through the rest — the CLI, sign-in, then `treg mcp install` — so you end up with\nthe command line **and** treg's tools. Other agents: `npx skills add superdesigndev/treg -s treg`\n(the `-s` matters — without it you also get this repo's internal dev skills).\nSee [docs/CLAUDE-PLUGIN.md](docs/CLAUDE-PLUGIN.md). MiniMax Code / MiniMax Agent users: the same\nskill ships via the MiniMax Plugin Marketplace ([docs/MINIMAX-PLUGIN.md](docs/MINIMAX-PLUGIN.md)).\n\n### Claude.ai connector\n\nThe Claude Connectors Directory surface is `https://treg.to/mcp/v2/`. It exposes only curated\ncatalog endpoints and separates read calls from write calls so Claude receives accurate safety\nsignals. The existing `/mcp/` surface remains available for catalog endpoints, team-owned tools,\nand imported skills. See the [MCP and OAuth architecture](docs/context/architecture/mcp-oauth.md)\nfor the boundary and implementation, and the\n[submission runbook](docs/CLAUDE-CONNECTOR-SUBMISSION.md) for release gates.\n\n## Call a tool you don't have a key for\n\nThe catalog is grouped by what endpoints **do**: keyword and rank tracking, backlinks and authority,\nAI visibility, trending and discovery, publishing to socials, people and company enrichment, ads\nmanagement and creative, measurement.\n\n```bash\ntreg catalog                                    # every platform, busiest first\ntreg catalog search \"find a work email\"         # by the job, not the vendor\ntreg catalog get hunter.people.email.find       # params, PRICE, example response\ntreg call hunter.people.email.find --query domain=reddit.com --query full_name=\"Alexis Ohanian\"\n```\n\n**How a catalogued call is served** — the credential ladder, in order:\n\n1. your team registered its own tool for that provider → that tool, that key;\n2. your team stored a secret for the provider → injected through a virtual tool;\n3. neither → **treg's own key**, billed to the team's prepaid balance.\n\nYour own credential always beats treg's, so connecting a key you already pay for makes those calls\nfree of the balance rather than duplicating them. An endpoint treg has no published price for is\n**refused**, not served free — you are told to connect your own key instead. Where several providers\nserve one capability, `treg catalog search` shows them side by side with prices; **choosing is\nyours** — treg does not silently pick or fail over between providers for you. (When treg's own\naccount for a provider is out it may serve the *same* endpoint through a treg-owned relay account,\ndisclosed on the response; a team can opt out.) The exception you opt into: `treg.<capability>` routed endpoints, where treg picks the provider for you and names it.\n\n```bash\ntreg balance          # credit left, calls in flight, recent spend\ntreg topup            # add funds, or set up automatic top-ups\n```\n\nOut of balance is an HTTP **402** carrying `balance_micro`, `estimated_cost_micro` and a `topup_url`,\nso an agent can act on it without reading prose.\n\n## Share & use your own tools\n\nThe zero-thought path — point treg at a project and it figures out what's shareable:\n\n```bash\ntreg scan     # read-only preview: the keys, skills & CLIs upload would register\ntreg upload   # register them (encrypted server-side); idempotent, --replace to update\n```\n\n`treg upload` scans the `.env` (matching keys against ~80 known providers), every skill\nsubdirectory, and installed catalog CLIs. Three kinds of things go into the registry — here's how\nto share and use each:\n\n### 1. Endpoints (HTTP APIs)\n\n**Share** — one upstream URL callable with a stored key, or bulk from a `.env`:\n\n```bash\ntreg secret add STRIPE_KEY --value sk_live_123\ntreg add stripe --base-url https://api.stripe.com --secret STRIPE_KEY\n\ntreg upload env --select openai,stripe,resend     # or straight from the .env\n```\n\n**Use** — the agent-native way: build the **real** upstream request and prefix it with the proxy.\ntreg resolves the tool by host, injects the credential, and relays everything else faithfully\n(your `X-Treg-Token` is stripped before the upstream sees it):\n\n```\nReal request:   GET https://api.intercom.io/conversations?per_page=5\nThrough treg:   GET https://treg.to/call/https://api.intercom.io/conversations?per_page=5\n                    header:  X-Treg-Token: <your token>\n```\n\nOr the CLI shorthand — and `treg calls` for the audit log:\n\n```bash\ntreg call intercom conversations --query per_page=5\ntreg call stripe v1/balance\n```\n\n### 2. CLIs\n\n**Share** — automatic: `treg upload` detects installed catalog CLIs (`stripe`, `gh`, `vercel`, …)\nand registers them; a recipe-only catalog CLI skill (e.g. `stripe-cli`) auto-becomes runnable too.\n\n**Use** — `treg run` executes the vendor CLI **with the org's credential injected**, so you never\nhold the key or log in:\n\n```bash\ntreg run stripe -- get /v1/balance\ntreg run gh -- pr list\ntreg run --server agentmail-cli inboxes list   # runs on the registry server: the key never reaches you\n```\n\n`--local` (default) runs on your machine; `--server` runs on the registry and streams output back.\nFor a whole session, `treg shell start` opens a subshell where every registered CLI injects\nautomatically — just use `stripe`, `gh`, … normally; `exit` reverts. `treg runs` is the audit log.\n\n### 3. Skills\n\n**Share** — a skill is a whole capability (`SKILL.md` recipe + its secrets + its tool(s)),\nregistered together so the whole team runs the same skill, maintained in one place:\n\n```bash\ntreg upload skills --dir ~/.claude/skills --all   # register a folder of skills in one pass\n```\n\n**Use** — pull any shared skill into your agent; its API calls go through treg with your token,\nso the key stays on the server, never in the skill:\n\n```bash\ntreg skill install seo-blog-writer      # writes into ./.claude/skills/  (--all for the library)\n```\n\n### Manual registration — when the heuristics can't figure a tool out\n\n```bash\n# multi-credential tool (e.g. google-ads: OAuth bearer + a developer-token header)\ntreg tool add google-ads --base-url https://googleads.googleapis.com \\\n  --bind \"secret=<oauth-id>,injector=oauth\" \\\n  --bind \"secret=<dev-id>,name=developer-token,format={secret}\"\n\n# one skill, step by step\ntreg skill init --dir ./my-skill          # drafts treg.json (guesses base_url, finds secrets)\ntreg skill add  --dir ./my-skill          # registers recipe + secrets + tool, atomically\n\n# OAuth via the browser (mints the first token, treg holds it and auto-refreshes)\ntreg oauth connect gsc --client-secret client_secret.json \\\n  --scopes https://www.googleapis.com/auth/webmasters.readonly\n```\n\nFull options for every command: [`USAGE.md`](USAGE.md).\n\n## Teams\n\nEverything is scoped to an **org**: a token = a `(user, org)` membership, and every secret, tool,\nand skill belongs to the active org. Roles: **owner / admin / member / viewer**.\n\n```bash\ntreg org create \"Acme\"                        # make a team, become owner\ntreg org invite teammate@acme.com             # invite by email (pick role + tool access)\ntreg org join <code> --email you@acme.com     # accept an invite (creates you if new)\ntreg org ls | use <slug> | members            # switch orgs, see the roster\ntreg org access <member> --tools a,b          # per-member tool access (admin+)\n```\n\n## Going deeper\n\n- [`USAGE.md`](USAGE.md) — the full `treg` CLI reference.\n- [`/llms.txt`](https://treg.to/llms.txt) — the agent-onboarding file: call\nprotocol, discovery, auth, CLI, skills. One fetch teaches an agent the whole registry.\n- **The dashboard** at [treg.to](https://treg.to) — full CRUD, a guided\ntutorial (Help → Tutorial), and copyable setup instructions for your agents.\n- **The API** — everything the CLI does is plain HTTP; interactive OpenAPI docs live at `/docs`.\nThe proxy endpoint is `/call/{...}`; all endpoints take the `X-Treg-Token` header.\n\n---\n\n# Part 2 · Self-hosting & development\n\n## Run it locally\n\nOne command (needs `tmux` + [`uv`](https://docs.astral.sh/uv/); it syncs the venv itself):\n\n```bash\nscripts/dev-local.sh up        # server on http://localhost:18790, dev-safe settings\n```\n\nThat runs the server in tmux with hot-reload, its own sqlite DB (`treg-dev.db`), and email OTP dev\nmode (sign-in codes shown on the page — no mail sender needed). Day-to-day:\n\n```bash\nscripts/dev-local.sh cli login   # sandboxed CLI: never touches your real ~/.treg/config.json\nscripts/dev-local.sh logs        # server output          · status / restart / down\nscripts/dev-local.sh reset       # wipe the dev DB + CLI sandbox for a fresh start\n```\n\nOr run the server directly, without tmux:\n\n```bash\nuv sync                        # create the venv from uv.lock (pulls the server deps for dev)\nuv run python -m treg upgrade  # prepare schema + run idempotent release tasks without serving\nuv run python -m treg          # serve on 0.0.0.0:18790 (add --reload for dev)\nuv run python -m treg keygen   # print a fresh Fernet key for TREG_SECRET_KEY\n```\n\n> **Installing to run a server (not from source):** the base package is the **CLI only**. To run a\n> registry, install the server extra — `pip install \"tools-registry[server]\"` — which adds FastAPI, the\n> database drivers, and encryption. `pip install tools-registry` alone gives just the `treg` command for\n> talking to an existing registry.\n\nThe team instance is hosted on **Render** (web service + Postgres) at `treg.to`.\n\n## Configuration\n\nEnvironment variables (prefix `TREG_`, read from `.env`):\n\n\n| Var                                       | Default                         | Purpose                                                                                                                                                                    |\n| ----------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `TREG_DATABASE_URL`                       | `sqlite+aiosqlite:///./treg.db` | DB URL (SQLite for dev, Postgres in prod)                                                                                                                                  |\n| `TREG_SECRET_KEY`                         | *(empty)*                       | Fernet key for secrets-at-rest; empty → an ephemeral key is minted (secrets won't survive a restart)                                                                       |\n| `TREG_PUBLIC_URL`                         | `https://treg.to`  | treg's public base, used to build the OAuth callback URI                                                                                                                   |\n| `TREG_SESSION_SECRET`                     | *(empty)*                       | signs the dashboard session cookie; falls back to `TREG_SECRET_KEY`. Set a real value in prod                                                                              |\n| `TREG_GITHUB_CLIENT_ID` / `_SECRET`       | *(empty)*                       | GitHub OAuth sign-in (callback `<public_url>/auth/github/callback`); empty hides the button                                                                                |\n| `TREG_GOOGLE_CLIENT_ID` / `_SECRET`       | *(empty)*                       | Google OAuth sign-in (redirect `<public_url>/auth/google/callback`); empty hides the button                                                                                |\n| `TREG_INSTAGRAM_CLIENT_ID` / `_SECRET`    | *(empty)*                       | Instagram App ID and secret for direct Instagram Login (redirect `<public_url>/oauth/callback`)                                                                           |\n| `TREG_META_CLIENT_ID` / `_SECRET`         | *(empty)*                       | Meta app credentials for Facebook Pages, Meta Ads, and optional Instagram `page-tools`                                                                                     |\n| `TREG_RESEND_API_KEY` / `TREG_EMAIL_FROM` | *(empty)*                       | transactional email via Resend (OTP codes + invites); From must be a Resend-verified sender                                                                                |\n| `TREG_ADMIN_TOKEN`                        | *(empty)*                       | cross-tenant **super-admin** bearer; authorizes every `/admin/*` endpoint. Empty disables the env path (only `is_superadmin` users reach `/admin`). Keep it long + secret. |\n| `TREG_EMAIL_DEV_MODE`                     | `false`                         | when true, `/auth/email/start` returns the OTP in its response (no mail sender needed) — **dev/local only**, never in prod.                                                |\n\n\nNo `.env` is needed for local dev — every setting has a working default (ephemeral key, sqlite).\n\n> **⚠️ Back these up before moving or redeploying:** the Fernet key (`TREG_SECRET_KEY`) and the\n> database (Postgres in prod; `treg.db` for a local sqlite run). Lose the Fernet key and every\n> stored secret becomes unrecoverable.\n\n## Architecture\n\n**Request flow for `/call`:** resolve tool (by URL host + longest `base_url` prefix, or by name) →\ndecrypt its secret(s) → apply each binding's injector → stream to the upstream → fire-and-forget\naudit record. The proxy does no business logic and never buffers the body.\n\n**Module map** (`src/treg/`):\n\n\n| Module                                     | Role                                                                                                             |\n| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |\n| `proxy.py`                                 | `relay()` — the whole product in one function: a faithful streaming proxy                                        |\n| `injectors.py`                             | the auth-shape seam: `env`, `cli_auth`, `secret_file`, `oauth` place a secret into a header/query                |\n| `oauth.py`                                 | token freshness (single-flight refresh) + the connect flow (consent URL, code exchange)                          |\n| `health.py`                                | credential health: refresh oauth, probe tools, webhook the owner of anything broken                              |\n| `convert.py`                               | scaffold a skill directory into a registerable bundle manifest                                                   |\n| `api.py`                                   | the API — the only brain; CLI + skill are thin clients over it                                                   |\n| `cli.py`                                   | the `treg` CLI                                                                                                   |\n| `models.py`                                | SQLModel tables: `Org`, `User`, `Membership`, `Invite`, `Secret`, `Tool`, `Bundle`, `PendingOAuth`, `CallRecord` |\n| `crypto.py` `config.py` `db.py` `audit.py` | Fernet encryption + tokens · settings · async DB · deferred audit writer                                         |\n\n\n**The 4 auth shapes** (per binding `injector`): `env` (plain string / API key) · `secret_file` (a\nJSON token file, pull a field) · `oauth` (a JSON OAuth token, auto-refreshed if refreshable) ·\n`cli_auth` (material lifted from a CLI's keychain).\n\n**Faithful-relay contract:** the proxy alters **only** three things, everything else is verbatim:\n\n1. hop-by-hop transport headers (re-derived per hop),\n2. treg's own control + edge-forwarding headers (`x-treg-token`, `x-treg-org`,\n`ngrok-skip-browser-warning`, `x-forwarded-*`, `via`, …) and treg's session cookie — all stripped,\nnever leak upstream,\n3. the injected credential(s).\n\n**OAuth, three ways to get the first token:** *manual upload* (drop in a `token.json`) ·\n*auto-refresh* (if the token carries `refresh_token` + client creds, treg keeps it fresh, you never\nre-upload) · *hosted connect flow* (`treg oauth connect` → browser consent → treg captures the\ntoken itself).\n\n**Health checks:** give a tool an optional probe (`{method, path, expect_status}`); a periodic run\n(on demand or via cron) validates every credential, refreshes OAuth, and webhooks the owner of any\nthat break.\n\nDeep design lives in [`docs/context/`](docs/context/README.md) (per-subsystem fragments).\n\n## Tests\n\n```bash\nuv run pytest -q     # 521 tests\n```\n\nCoverage: proxy walking-skeleton, all injector shapes, per-user auth + CRUD + audit, skill composer,\nURL-passthrough + faithful relay, OAuth refresh + connect flow, health checks, `treg run`/shell,\nupload/scan, orgs + invites, the dashboard API, CLI.\n\n## Contributing & docs\n\n```\ntreg/\n├── src/treg/            # the package (api, cli, proxy, injectors, oauth, health, convert, models, …)\n│   └── web/             # dashboard, landing, tutorial, llms.txt, skill.md, install.sh\n├── tests/               # 521 tests\n├── docs/\n│   ├── context/         # design fragments (codemap system) + generated index\n│   └── ONBOARDING.md    # first-time bootstrap\n├── USAGE.md             # full treg CLI reference\n└── pyproject.toml\n```\n\nPer-subsystem design docs are **fragments** in `docs/context/`, each citing its `src/treg/*`\nsources. Working in this repo with an AI agent? The `/tools-registry-context` skill loads the\nright fragment for what you're touching and keeps the docs in sync — run\n`/tools-registry-context sync` before pushing.\n\n**Roadmap:** MCP support · finer permission tiers · at-rest key-management hardening · possible\nLoopni merge.\n\n## License\n\nApache 2.0 with additional terms ([`LICENSE`](LICENSE)): use it freely — including commercially,\ninside your own organization (self-hosting your own registry is encouraged) — but don't offer it\nto third parties as a hosted/managed service or embed it in a commercially distributed product\nwithout written permission (`jason@superdesign.dev`).\n",
  "bytes": 21373,
  "sha": "ef0b4ca785acb7c92e19e86ff79d053f1ad03886b91f7a3c8c831f317049f793",
  "repo_slug": "superdesigndev/treg",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_superdesigndev_treg_4ec4530d/readme"
}