Skip to content
Back to search

treg

OpenRouter for tools - 4,000+ agent-friendly tools, pay for the usage, not subscription

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/superdesigndev--treg/badge.svg)](/listings/superdesigndev--treg)

HTML

<a href="/listings/superdesigndev--treg"><img src="/api/listings/superdesigndev--treg/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Same flow as the dashboard's **Getting started** guide:

# 1. install the CLI — also points it at the registry
curl -fsSL https://treg.to/install.sh | sh

# 2. sign in (GitHub default · --email for a one-time code · --token for agents/CI)
treg login

# 3. do something useful immediately — no key, nothing registered
treg catalog search "backlinks for a domain"     # find a tool by what it DOES
treg call tikhub.tiktok.user.profile --query uniqueId=tiktok
treg balance                                     # exactly what that cost

# (or `treg onboard` for the guided walkthrough)

Fish Audio provides S2.1 Pro speech, public-voice discovery, and private voice cloning. Speech is binary stdout, so redirect it to a file. A discovered voice's `_id` or a team voice id is the TTS `reference_id`; voices created on treg's Fish account are durable team resources:

treg call fishaudio.tts.s2-1-pro --method POST --header model=s2.1-pro \
  --data '{"text":"Hello from treg","format":"mp3"}' > speech.mp3
treg call fishaudio.voices.discover --query self=false --query licensed=false --query language=en
treg resources list --provider fishaudio --kind voice

With your own Fish key, requests are an unmetered upstream relay and Fish owns the account boundary.

A client written for a provider's own API can switch by its base URL alone: `https://treg.to/call/<provider>` in place of the provider's base URL (`https://api.dataforseo.com/v3` → `https://treg.to/call/dataforseo`) runs the catalog tool on that method and path exactly as `/call/<id>` would; a path the catalog does not list is a 404, never relayed.

Catalog tool inputs are described by `treg catalog get <id>`. Tools marked `strict_query` reject undeclared or repeated query parameters, unsupported values and request bodies. Send each declared parameter within its declared type, allowed values and range, each single-valued one once, and a row count such as `limit` as a whole number within its stated maximum: a tool that enforces this answers a 400 `catalog_parameter_invalid` naming the parameter, and nothing is charged. Undeclared fields are forwarded as sent.

Your token identifies you on every call (`X-Treg-Token` header) and is the same for all tools. Discover what your team has shared: `treg tool ls` · check credential health: `treg health`.

Or install it as a Claude Code plugin

/plugin marketplace add superdesigndev/treg
/plugin install treg@treg

Installs the treg skill and treg's tools with no token and no configuration. Run `/mcp`, pick treg and sign in; the tools appear after it. Other agents: `npx skills add superdesigndev/treg -s treg` (or see [Workflow skills](#workflow-skills) for the rest). See [docs/CLAUDE-PLUGIN.md](docs/CLAUDE-PLUGIN.md). MiniMax Code / MiniMax Agent users: the same skill ships via the MiniMax Plugin Marketplace ([docs/MINIMAX-PLUGIN.md](docs/MINIMAX-PLUGIN.md)).

Workflow skills

Ready-made recipes your agent runs end to end, every call through treg:

| Skill | What your agent can do | |---|---| | [`treg`](skills/treg/SKILL.md) | Find and call any tool in the catalog, plus your own tools | | [`web-access`](skills/web-access/SKILL.md) | When your agent's own web tools fall short, read the live web without local scrapers: free search and page reads first, then the right platform job for social, stores, reviews, maps and papers, with treg falling back to the next vendor when one fails | | [`lead-signals`](skills/lead-signals/SKILL.md) | Find in-market buyers from public signals (complaints, job changes, hiring, funding, tool adoption) and monitor a topic, competitor or account list for them ([treg.to/leads-signals](https://treg.to/leads-signals)) |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 78 lines
  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "treg",
  4. "description": "OpenRouter for tools - 4,000+ agent-friendly tools, pay for the usage, not subscription",
  5. "owner": {
  6. "name": "Superdesign dev, Inc.",
  7. "email": "jason@superdesign.dev",
  8. "url": "https://treg.to"
  9. },
  10. "plugins": [
  11. {
  12. "name": "treg",
  13. "source": "./plugins/treg",
  14. "category": "developer-tools",
  15. "tags": [
  16. "api",
  17. "seo",
  18. "serp",
  19. "enrichment",
  20. "scraping"
  21. ]
  22. },
  23. {
  24. "name": "ai-ugc-video",
  25. "source": "./plugins/workflows/ai-ugc-video",
  26. "description": "\"Make realistic AI UGC videos cheaply: viral research, locked assets, scripts, Seedance/Avatar IV generation, and final edit. Use for AI UGC ads, talking-head videos, or AIGC short films.\"",
  27. "category": "productivity"
  28. },
  29. {
  30. "name": "doomscroll",
  31. "source": "./plugins/workflows/doomscroll",
  32. "description": "Use when the user wants to know what people are posting about a topic right now or since a recent point in time - the last few hours, today, since a launch, since their last check - such as the best clips, tips, reactions, launches, drama or sentiment on X, TikTok, YouTube, Reddit, Hacker News or Product Hunt. Also for \"catch me up on X\", \"what's the internet saying about X\", \"what did I miss\", or keeping up with a live event.",
  33. "category": "productivity"
  34. },
  35. {
  36. "name": "jev-memory",
  37. "source": "./plugins/workflows/jev-memory",
  38. "description": "Use when the user wants Claude Code to remember their preferences across sessions, asks for a memory mod or memory harness for Claude Code, mentions the Jev memory classifier or a \"classifier on every turn\" mod, or wants to build a Claude Code mod on treg and Jev. Installs a ready-made Claude Code mod that has Jev judge each prompt after the turn and saves lasting preferences to .claude/jev-memory.md, or builds the same mod from one prompt.",
  39. "category": "productivity"
  40. },
  41. {
  42. "name": "lead-signals",
  43. "source": "./plugins/workflows/lead-signals",
  44. "description": "Use when the user wants to find buyers, warm or hot leads, or in-market accounts; asks about buying signals, intent signals or trigger events; wants to know who is complaining about a problem, engaging with a post, hiring for a role, changing jobs, raising money or adopting a tool; or wants to monitor a topic, a competitor or a list of accounts for people ready to buy.",
  45. "category": "productivity"
  46. },
  47. {
  48. "name": "make-ugc",
  49. "source": "./plugins/workflows/make-ugc",
  50. "description": "Make AI UGC videos end to end through treg. Pull the trending TikTok and Instagram videos in a vertical, extract the hook patterns, create a character with the same vibe as a presenter the user picks, generate 5-10 talking-head hook clips on Seedance 2.5 (less-restriction route), add a voiced demo clip, burn captions, and report the bill per clip. Use when the user asks for UGC ads, creator-style product videos, TikTok/Reels hooks, or an AI presenter for their product.",
  51. "category": "productivity"
  52. },
  53. {
  54. "name": "rea-growth",
  55. "source": "./plugins/workflows/rea-growth",
  56. "description": "Use when the user wants to know how a company gets its users, reverse engineer a competitor's growth or distribution, copy what a winning company does on each channel, or study a brand's content strategy (titles, thumbnails, covers, captions, graphics) on YouTube, TikTok, Instagram, X, LinkedIn or Reddit. Also for \"how did X grow\", \"teardown of X's marketing\", \"what content works for X\".",
  57. "category": "productivity"
  58. },
  59. {
  60. "name": "rea-marketing",
  61. "source": "./plugins/workflows/rea-marketing",
  62. "description": "\"Use when the user wants to reverse engineer a brand's holiday marketing (Black Friday, Christmas, Singles' Day…): what ran on each channel, when, at what estimated budget, and whether it worked in sales.\"",
  63. "category": "productivity"
  64. },
  65. {
  66. "name": "recruit",
  67. "source": "./plugins/workflows/recruit",
  68. "description": "Use when the user wants candidates for a role; they paste a LinkedIn job post (or a job description) and want the people who fit it, ranked, with a reason for each and a personal email and phone to reach them. Also for \"source candidates\", \"find people for this job\", \"build a shortlist\", or turning a job post into a contactable candidate list.",
  69. "category": "productivity"
  70. },
  71. {
  72. "name": "web-access",
  73. "source": "./plugins/workflows/web-access",
  74. "description": "Use only when the agent's own web tools can't do the job. Use what you already have first (built-in web search and fetch, a browser, MCP servers the user installed); come here when none of them covers it, such as a page they can't read, structured data from a platform they have no tool for (X, LinkedIn, Reddit, TikTok, Instagram, YouTube, Xiaohongshu, Amazon, app stores, Google Maps, papers), or when the user asks for treg. Not for localhost, staging, internal pages or public docs your own fetch can read. Starts free, and treg falls back to the next vendor when one fails.",
  75. "category": "productivity"
  76. }
  77. ]
  78. }
README.md · README · 521 lines · 1 finding marked
  1. # Treg (OpenRouter for Tools)
  2. ![treg — the tool catalog for your agent](docs/assets/treg-hero.png)
  3. **OpenRouter, but for agent tools instead of models.** Point an agent at one base URL with one token
  4. and it can do the job: **a curated catalog of thousands of endpoints across many providers** — SEO and backlinks,
  5. social and trends, people and company enrichment, ads, scraping, image and video generation —
  6. **priced per call, from a cent**,
  7. with no provider signup. Plus your own team's keys, skills and CLIs, callable by every teammate's
  8. agent without the credential ever leaving the server.
  9. **Ask for the task, not the tool.** You do not need to know which vendor sells backlink data, or to
  10. hold an account with them. Search for what you want to do, read the price, call it.
  11. Built for the Superdesign team, live at [treg.to](https://treg.to) — anyone can self-host.
  12. ## Why it exists
  13. The tools an agent needs for real work sit behind subscriptions nobody buys for a single run —
  14. Semrush $139/mo, Moz $99/mo, Crunchbase $99/mo, Apollo $59/seat — behind signup walls, or behind no
  15. public API at all (invite-only, partner-only, app-review-only). treg carries those accounts and
  16. bills fractions of a cent per call.
  17. ## Two kinds of tool, one token
  18. - **The catalog** — external endpoints treg can serve with its own key or through a verified public
  19. route that needs no provider key. Own-key calls use the team's prepaid balance; anonymous calls
  20. are free. No account with the provider is needed. New verified accounts receive **$1.00 free**
  21. once, when they create an eligible team.
  22. - **Your own tools** — anything a teammate registered: a paid API account, an OAuth connection, a
  23. vendor CLI, a `SKILL.md`. **Your own key always wins over treg's, and those calls are never
  24. metered.**
  25. The vocabulary for the second half:
  26. - **tool** = something the registry calls for you with the org's credential. Two kinds:
  27. - **endpoint** — an upstream `base_url` + credential **bindings** (each binding injects one
  28. secret into the request; a request can carry several, e.g. an OAuth bearer *and* a
  29. `developer-token` header).
  30. - **CLI** — a vendor binary (`stripe`, `gh`, `vercel`, ...) run with the credential injected.
  31. - **skill / bundle** = a recipe (`SKILL.md`) + its secrets + its tool(s), registered together.
  32. **The one rule:** the proxy **relays, never models** the upstream, and **injects auth server-side**
  33. — so it survives upstream API changes and callers never hold keys.
  34. ---
  35. # Part 1 · Using the registry
  36. Visit [**treg.to**](https://treg.to) (hosted on Render) — the dashboard,
  37. sign-in, and every URL below live there.
  38. ## Quickstart
  39. Same flow as the dashboard's **Getting started** guide:
  40. ```bash
  41. # 1. install the CLI — also points it at the registry
  42. curl -fsSL https://treg.to/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 59 on GitHub
  43. # 2. sign in (GitHub default · --email for a one-time code · --token for agents/CI)
  44. treg login
  45. # 3. do something useful immediately — no key, nothing registered
  46. treg catalog search "backlinks for a domain" # find a tool by what it DOES
  47. treg call tikhub.tiktok.user.profile --query uniqueId=tiktok
  48. treg balance # exactly what that cost
  49. # (or `treg onboard` for the guided walkthrough)
  50. ```
  51. Fish Audio provides S2.1 Pro speech, public-voice discovery, and private voice cloning.
  52. Speech is binary stdout, so redirect it to a file. A discovered voice's `_id` or a team voice id is
  53. the TTS `reference_id`; voices created on treg's Fish account are durable team resources:
  54. ```bash
  55. treg call fishaudio.tts.s2-1-pro --method POST --header model=s2.1-pro \
  56. --data '{"text":"Hello from treg","format":"mp3"}' > speech.mp3
  57. treg call fishaudio.voices.discover --query self=false --query licensed=false --query language=en
  58. treg resources list --provider fishaudio --kind voice
  59. ```
  60. With your own Fish key, requests are an unmetered upstream relay and Fish owns the account boundary.
  61. A client written for a provider's own API can switch by its base URL alone: `https://treg.to/call/<provider>` in place of the provider's base URL (`https://api.dataforseo.com/v3` → `https://treg.to/call/dataforseo`) runs the catalog tool on that method and path exactly as `/call/<id>` would; a path the catalog does not list is a 404, never relayed.
  62. Catalog tool inputs are described by `treg catalog get <id>`. Tools marked `strict_query` reject undeclared or repeated query parameters, unsupported values and request bodies. Send each declared parameter within its declared type, allowed values and range, each single-valued one once, and a row count such as `limit` as a whole number within its stated maximum: a tool that enforces this answers a 400 `catalog_parameter_invalid` naming the parameter, and nothing is charged. Undeclared fields are forwarded as sent.
  63. Your token identifies you on every call (`X-Treg-Token` header) and is the same for all tools.
  64. Discover what your team has shared: `treg tool ls` · check credential health: `treg health`.
  65. ### Or install it as a Claude Code plugin
  66. ```
  67. /plugin marketplace add superdesigndev/treg
  68. /plugin install treg@treg
  69. ```
  70. Installs the treg skill and treg's tools with no token and no configuration. Run `/mcp`, pick
  71. treg and sign in; the tools appear after it. Other agents: `npx skills add superdesigndev/treg -s treg`
  72. (or see [Workflow skills](#workflow-skills) for the rest).
  73. See [docs/CLAUDE-PLUGIN.md](docs/CLAUDE-PLUGIN.md). MiniMax Code / MiniMax Agent users: the same
  74. skill ships via the MiniMax Plugin Marketplace ([docs/MINIMAX-PLUGIN.md](docs/MINIMAX-PLUGIN.md)).
  75. ### Workflow skills
  76. Ready-made recipes your agent runs end to end, every call through treg:
  77. | Skill | What your agent can do |
  78. |---|---|
  79. | [`treg`](skills/treg/SKILL.md) | Find and call any tool in the catalog, plus your own tools |
  80. | [`web-access`](skills/web-access/SKILL.md) | When your agent's own web tools fall short, read the live web without local scrapers: free search and page reads first, then the right platform job for social, stores, reviews, maps and papers, with treg falling back to the next vendor when one fails |
  81. | [`lead-signals`](skills/lead-signals/SKILL.md) | Find in-market buyers from public signals (complaints, job changes, hiring, funding, tool adoption) and monitor a topic, competitor or account list for them ([treg.to/leads-signals](https://treg.to/leads-signals)) |
  82. | [`recruit`](skills/recruit/SKILL.md) | Turn a LinkedIn job post into a ranked shortlist: criteria from the post, people search, filters with reasons, one line on why each fits, cited evidence (posts, GitHub, talks, tenure, job change) under a per-candidate spend cap, then a checked personal email and phone, with a run file of counts, evidence and the vendor trail per candidate |
  83. | [`doomscroll`](skills/doomscroll/SKILL.md) | Catch up on any topic over the last hours: the best posts, clips and reactions from X, TikTok, YouTube, Reddit, Hacker News and Product Hunt, grouped into stories with links, only what is new since the last scroll |
  84. | [`make-ugc`](skills/make-ugc/SKILL.md) | Make AI UGC videos: trending hooks, a presenter, talking-head clips, captions ([treg.to/ugc](https://treg.to/ugc)) |
  85. | [`jev-memory`](skills/jev-memory/SKILL.md) | Give Claude Code a memory: a Claude Code mod where Jev judges each prompt after the turn and keeps your lasting preferences, installed ready-made or built from one prompt ([the mod](examples/claude-code-mods/jev-memory)) |
  86. `install.sh` installs only `treg` and names the others in one line; your agent offers them after
  87. sign-in and the first call. Name the ones you want with
  88. `sh -s -- --skills lead-signals,recruit` (or `--skills all`; the opt-in `jev-memory` and `rea-growth` are never in that set). In Claude Code each one is
  89. also its own plugin in treg's marketplace: `/plugin install recruit@treg`, or pick them from `/plugin`. To add
  90. them to an existing agent instead ([skills.sh](https://skills.sh) CLI):
  91. ```bash
  92. npx skills add superdesigndev/treg # every public skill
  93. npx skills add superdesigndev/treg --skill lead-signals # just one
  94. treg skill bootstrap --skills all # the installer's set, with the treg CLI you already have
  95. ```
  96. The workflow skills run on treg, so set it up first (the Quickstart above, or point your agent at
  97. [treg.to/llms.txt](https://treg.to/llms.txt)).
  98. ### Claude.ai connector
  99. The Claude Connectors Directory surface is `https://treg.to/mcp/v2/`. It exposes only curated
  100. catalog endpoints, without image, video or audio generation, and separates read calls from write
  101. calls so Claude receives accurate safety signals. The existing `/mcp/` surface remains available for catalog endpoints, team-owned tools,
  102. and imported skills. See the [MCP and OAuth architecture](docs/context/architecture/mcp-oauth.md)
  103. for the boundary and implementation, and the
  104. [submission runbook](https://github.com/superdesigndev/treg-internal/blob/main/docs/distribution/CLAUDE-CONNECTOR-SUBMISSION.md) for release gates.
  105. ## Call a tool you don't have a key for
  106. The catalog is grouped by what endpoints **do**: keyword and rank tracking, backlinks and authority,
  107. AI visibility, trending and discovery, publishing to socials, people and company enrichment, ads
  108. management and creative, measurement.
  109. ```bash
  110. treg catalog # every platform, busiest first
  111. treg catalog search "find a work email" # by the job, not the vendor
  112. treg catalog search --new # tools added in the last 30 days, newest first
  113. treg catalog get hunter.people.email.find # params, PRICE, example response
  114. treg call hunter.people.email.find --query domain=reddit.com --query full_name="Alexis Ohanian"
  115. ```
  116. **How a catalogued call is served** — the credential ladder, in order:
  117. 1. your team registered its own tool for that provider → that tool, that key;
  118. 2. your team stored a secret for the provider → injected through a virtual tool (never for a keyless
  119. public API, which has nothing to connect);
  120. 3. neither, and the endpoint has a verified public route → **no provider key**, free;
  121. 4. otherwise → **treg's own key**, billed to the team's prepaid balance.
  122. The anonymous price assumes the caller does not send a provider credential header. The faithful
  123. relay preserves caller headers, so a caller-supplied provider key can use that key's credits.
  124. Your own credential always beats treg's, so connecting a key you already pay for makes those calls
  125. free of the balance rather than duplicating them. An endpoint treg has no published price for is
  126. **refused**, not served free — you are told to connect your own key instead. Where several providers
  127. serve one capability, `treg catalog search` shows them side by side with prices; **choosing is
  128. yours** — treg does not silently pick or fail over between providers for you. (When treg's own
  129. account for a provider is out it may serve the *same* endpoint through a treg-owned relay account,
  130. disclosed 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. For common jobs (scraping a page, web search, Google results, finding an email) start with the routed endpoint, such as `treg.web.extract` or `treg.web.search`, rather than a provider you remember by name. On `treg.people.email.find` and `treg.people.phone.find`, `X-Treg-Route-Verify: true` also checks the found address or number in the same call, as its own charge, and says what the check found.
  131. ```bash
  132. treg balance # credit left, calls in flight, recent spend
  133. treg topup # add funds, or set up automatic top-ups
  134. ```
  135. Out of balance is an HTTP **402** `error: insufficient_balance` carrying `balance_micro`, `estimated_cost_micro` and a `topup_url`,
  136. so an agent can act on it without reading prose.
  137. **No account at all?** When the operator switches agent payments on, an agent with a stablecoin
  138. wallet can pay for catalog calls one at a time over HTTP, with MPP (Tempo) or x402 (Base): a
  139. `/call/<id>` without a treg token answers 402 with the payment challenge, and a client such as pympp
  140. or the mppx library pays it and sends the call again. What the call does not use stays as that
  141. wallet's credit for its next calls; it is never paid back as money. The agent-facing rules are in
  142. the skill's "Pay with a wallet" section, the design in
  143. [agent payments](docs/context/architecture/agent-payments.md).
  144. **Enrich Arena** lives at `/enrich-arena`, outside the dashboard. Compare enrichment answers with each vendor’s cost and speed,
  145. vote for the best answer in one click, or watch a sequential waterfall. Capability-compatible
  146. async providers participate too; Arena handles submit and polling internally. Browsing is
  147. public; submitting requires login, and billable attempts use your team's credits. See the
  148. [Arena guide](docs/context/interface/enrich-arena.md).
  149. **Web Arena** compares Web Search, Web Fetch, and Sitemap providers at `/web-arena`.
  150. Battle calls selected providers for the same input; Waterfall tries them in order. The
  151. live leaderboard combines direct provider-call hit rates and response times with checked
  152. Web Arena quality results over a rolling 30-day window. The pages open when the feature
  153. is enabled. See the
  154. [Web Arena guide](docs/context/interface/web-arena.md).
  155. ## Share & use your own tools
  156. The zero-thought path — point treg at a project and it figures out what's shareable:
  157. ```bash
  158. treg scan # read-only preview: the keys, skills & CLIs upload would register
  159. treg upload # register them (encrypted server-side); idempotent, --replace to update
  160. ```
  161. `treg upload` scans the `.env` (matching keys against ~80 known providers), every skill
  162. subdirectory, and installed catalog CLIs. Three kinds of things go into the registry — here's how
  163. to share and use each:
  164. ### 1. Endpoints (HTTP APIs)
  165. **Share** — one upstream URL callable with a stored key, or bulk from a `.env`:
  166. ```bash
  167. treg secret add STRIPE_KEY --value sk_live_123
  168. treg add stripe --base-url https://api.stripe.com --secret STRIPE_KEY
  169. treg upload env --select openai,stripe,resend # or straight from the .env
  170. ```
  171. **Use** — the agent-native way: build the **real** upstream request and prefix it with the proxy.
  172. treg resolves the tool by host, injects the credential, and relays everything else faithfully
  173. (your `X-Treg-Token` is stripped before the upstream sees it):
  174. ```
  175. Real request: GET https://api.intercom.io/conversations?per_page=5
  176. Through treg: GET https://treg.to/call/https://api.intercom.io/conversations?per_page=5
  177. header: X-Treg-Token: <your token>
  178. ```
  179. Or the CLI shorthand — and `treg calls` for the audit log:
  180. ```bash
  181. treg call intercom conversations --query per_page=5
  182. treg call stripe v1/balance
  183. ```
  184. ### 2. CLIs
  185. **Share** — automatic: `treg upload` detects installed catalog CLIs (`stripe`, `gh`, `vercel`, …)
  186. and registers them; a recipe-only catalog CLI skill (e.g. `stripe-cli`) auto-becomes runnable too.
  187. **Use** — `treg run` executes the vendor CLI **with the org's credential injected**, so you never
  188. hold the key or log in:
  189. ```bash
  190. treg run stripe -- get /v1/balance
  191. treg run gh -- pr list
  192. ```
  193. `--local` (default) runs on your machine. Server-side CLI execution (`--server`) is disabled globally.
  194. `treg runs` is the audit log.
  195. ### 3. Skills
  196. **Share** — a skill is a whole capability (`SKILL.md` recipe + its secrets + its tool(s)),
  197. registered together so the whole team runs the same skill, maintained in one place:
  198. ```bash
  199. treg upload skills --dir ~/.claude/skills --all # register a folder of skills in one pass
  200. ```
  201. **Use** — pull any shared skill into your agent; its API calls go through treg with your token,
  202. so the key stays on the server, never in the skill:
  203. ```bash
  204. treg skill install seo-blog-writer # writes into ./.claude/skills/ (--all for the library)
  205. ```
  206. ### Manual registration — when the heuristics can't figure a tool out
  207. ```bash
  208. # multi-credential tool (e.g. google-ads: OAuth bearer + a developer-token header)
  209. treg tool add google-ads --base-url https://googleads.googleapis.com \
  210. --bind "secret=<oauth-id>,injector=oauth" \
  211. --bind "secret=<dev-id>,name=developer-token,format={secret}"
  212. # one skill, step by step
  213. treg skill init --dir ./my-skill # drafts treg.json (guesses base_url, finds secrets)
  214. treg skill add --dir ./my-skill # registers recipe + secrets + tool, atomically
  215. # OAuth via the browser (mints the first token, treg holds it and auto-refreshes)
  216. treg oauth connect gsc --client-secret client_secret.json \
  217. --scopes https://www.googleapis.com/auth/webmasters.readonly
  218. ```
  219. Full options for every command: [`USAGE.md`](USAGE.md).
  220. The CLI and its installer send anonymous usage to PostHog when using treg.to (which command ran and
  221. how it ended, never request content or credentials).
  222. Disable with `TREG_TELEMETRY=0` or `DO_NOT_TRACK=1`.
  223. See [analytics details](USAGE.md#anonymous-usage-analytics).
  224. ## Teams
  225. An account can own up to 10 teams. Joining other teams as a member does not count toward this limit.
  226. Everything is scoped to an **org**: a token = a `(user, org)` membership, and every secret, tool,
  227. and skill belongs to the active org. Roles: **owner / admin / member / viewer**.
  228. ```bash
  229. treg org create "Acme" # make a team, become owner
  230. treg org invite teammate@acme.com # invite by email (pick role + tool access)
  231. treg org join <code> # accept an invite (sign in as the invited email first)
  232. treg org ls | use <slug> | members # switch orgs, see the roster
  233. treg org access <member> --tools a,b # per-member tool access (admin+)
  234. ```
  235. Team owners can enable enterprise SSO from the dashboard's **Team → SSO** tab. WorkOS connects the
  236. company's identity provider; owners can invite their IT admin to finish setup. Employees can enter
  237. their work email in any sign-in dialog or use the team's direct sign-in link. treg keeps its team roles and API keys. The
  238. Directory Sync plan removes a deactivated employee's team access. See
  239. [enterprise SSO setup](docs/enterprise-sso.md).
  240. ## Going deeper
  241. - **Feedback:** `treg feedback submit friction "The pagination example is unclear."`
  242. Share problems or suggestions without private information. See [feedback instructions](https://treg.to/feedback.md).
  243. - **Review:** `treg review CALL_ID useful`
  244. Rate an invited catalog call after using its result; `not_sure` is fine. Omit private data and continue the task.
  245. - [`USAGE.md`](USAGE.md) — the full `treg` CLI reference.
  246. - [`/llms.txt`](https://treg.to/llms.txt): the agent entry point, in the [llms.txt](https://llmstxt.org)
  247. format: what treg is, setup for each kind of agent, the search-read-call loop and the rules, with
  248. links to [`/skill.md`](https://treg.to/skill.md), the operating guide, for everything else.
  249. - **The dashboard** at [treg.to](https://treg.to) — full CRUD, a guided
  250. tutorial (Help → Tutorial), and copyable setup instructions for your agents.
  251. - **The API** — everything the CLI does is plain HTTP; interactive OpenAPI docs live at `/docs`.
  252. The proxy endpoint is `/call/{...}`; all endpoints take the `X-Treg-Token` header.
  253. ---
  254. # Part 2 · Self-hosting & development
  255. ## Run it locally
  256. One command (needs `tmux` + [`uv`](https://docs.astral.sh/uv/); it syncs the venv itself):
  257. ```bash
  258. scripts/dev-local.sh up # server on http://localhost:18790, dev-safe settings
  259. ```
  260. That runs the server in tmux with hot-reload, its own sqlite DB (`treg-dev.db`), and email OTP dev
  261. mode (sign-in codes shown on the page — no mail sender needed). Day-to-day:
  262. ```bash
  263. scripts/dev-local.sh cli login # sandboxed CLI: never touches your real ~/.treg/config.json
  264. scripts/dev-local.sh logs # server output · status / restart / down
  265. scripts/dev-local.sh reset # wipe the dev DB + CLI sandbox for a fresh start
  266. ```
  267. Or run the server directly, without tmux:
  268. ```bash
  269. bash scripts/build-dashboard.sh # Node 22.12+ and npm; build the Dashboard
  270. uv sync # create the venv from uv.lock (pulls the server deps for dev)
  271. uv run python -m treg upgrade # prepare schema + run idempotent release tasks without serving
  272. uv run python -m treg # serve on 0.0.0.0:18790 (add --reload for dev)
  273. uv run python -m treg keygen # print a fresh Fernet key for TREG_SECRET_KEY
  274. ```
  275. > **Installing to run a server (not from source):** the base package is the **CLI only**. To run a
  276. > registry, install the server extra — `pip install "tools-registry[server]"` — which adds FastAPI, the
  277. > database drivers, and encryption. `pip install tools-registry` alone gives just the `treg` command for
  278. > talking to an existing registry.
  279. The official hosted service is available at `treg.to`. Its production topology and live settings are
  280. maintained in the private [operator runbook](https://github.com/superdesigndev/treg-internal/blob/main/docs/production/deploy.md).
  281. ## Configuration
  282. Environment variables (prefix `TREG_`, read from `.env`):
  283. | Var | Default | Purpose |
  284. | ----------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  285. | `TREG_DATABASE_URL` | `sqlite+aiosqlite:///./treg.db` | DB URL (SQLite for dev, Postgres in prod) |
  286. | `TREG_READ_DATABASE_URL` | *(empty)* | Optional SQLite / PostgreSQL read datasource; empty reuses the primary. Requires callers to opt in; existing queries are unchanged. See [read datasource setup](docs/context/ops/deploy.md#optional-read-replica). |
  287. | `TREG_SECRET_KEY` | *(empty)* | Fernet key for secrets-at-rest; empty → an ephemeral key is minted (secrets won't survive a restart). During a rotation, a comma-separated list: the first key encrypts, every key decrypts |
  288. | `TREG_AWS_SECRET_ID` | *(empty)* | ARN of an AWS Secrets Manager secret holding a JSON object of `TREG_*` settings, read once at startup and winning over the environment; AWS credentials come from the standard `AWS_*` variables |
  289. | `TREG_KMS_KEY_ID` | *(empty)* | KMS key or alias ARN for stored credentials: this process can open KMS-sealed values (AWS credentials from the standard `AWS_*` variables) |
  290. | `TREG_KMS_ENCRYPT_NEW` | `false` | also seal new credential writes with that key; set only once every process that reads credentials has `TREG_KMS_KEY_ID` |
  291. | `TREG_PUBLIC_URL` | `https://treg.to` | treg's public base, used to build the OAuth callback URI |
  292. | `TREG_SESSION_SECRET` | *(empty)* | signs the dashboard session cookie; falls back to `TREG_SECRET_KEY`. Set a real value in prod |
  293. | `TREG_GITHUB_CLIENT_ID` / `_SECRET` | *(empty)* | GitHub OAuth sign-in (callback `<public_url>/auth/github/callback`); empty hides the button |
  294. | `TREG_GOOGLE_CLIENT_ID` / `_SECRET` | *(empty)* | Google OAuth sign-in (redirect `<public_url>/auth/google/callback`); empty hides the button |
  295. | `TREG_WORKOS_API_KEY` / `_CLIENT_ID` / `_WEBHOOK_SECRET` | *(empty)* | WorkOS enterprise SSO; configure callback and signed directory webhook as described in [enterprise SSO setup](docs/enterprise-sso.md) |
  296. | `TREG_ENTERPRISE_SSO_BUNDLE_ONLY` | `true` | Show only the SSO + Directory Sync plan by default; set to `false` to offer both monthly plans. |
  297. | `TREG_ENTERPRISE_SSO_BUNDLE_PRICE_ID` / `TREG_ENTERPRISE_SSO_ONLY_PRICE_ID` | *(empty)* | Reusable monthly Stripe Price IDs in the same account as `TREG_STRIPE_SECRET_KEY`; an unset or unusable Price hides its plan. Stripe's Price supplies the displayed amount and Checkout charge. |
  298. | `TREG_ENTERPRISE_SSO_BUNDLE_MIN_PRICE_USD` / `TREG_ENTERPRISE_SSO_ONLY_MIN_PRICE_USD` | `0` | Optional whole-dollar minimum for each monthly Stripe Price; lower prices are hidden and rejected at Checkout. |
  299. | `TREG_AGENT_PAYMENTS_ENABLED` | `false` | Keyless callers pay per catalog call with MPP or x402. Startup checks the rest of the `TREG_AGENT_PAYMENTS_*` set (secret, rails, recipients, settlement) and names every problem; see [agent payments](docs/context/architecture/agent-payments.md#settings). |
  300. | `TREG_INSTAGRAM_CLIENT_ID` / `_SECRET` | *(empty)* | Instagram App ID and secret for direct Instagram Login (redirect `<public_url>/oauth/callback`) |
  301. | `TREG_META_CLIENT_ID` / `_SECRET` | *(empty)* | Meta app credentials for Facebook Pages, Meta Ads, and optional Instagram `page-tools` |
  302. | `TREG_OAUTH_REVIEW_PENDING` | `instagram-login,page-messages` | Comma-separated registry review keys whose capabilities must remain gated; hosted review state is maintained privately. |
  303. | `TREG_RESEND_API_KEY` / `TREG_EMAIL_FROM` | *(empty)* | transactional email via Resend (OTP codes + invites); From must be a Resend-verified sender |
  304. | `TREG_BLOCKED_EMAIL_DOMAINS` | *(empty)* | comma-separated email domains refused at every sign-up/sign-in door and at team creation (subdomains included, case-insensitive). Empty blocks nothing — no list ships in the code |
  305. | `TREG_CLIENT_IP_HEADER` | *(empty)* | a header only your edge can set, used as the client address for every per-IP limit (`cf-connecting-ip` behind Cloudflare) |
  306. | `TREG_TRUSTED_PROXY_HOPS` | `1` | without that header: the `X-Forwarded-For` entry this many hops from the RIGHT (the one your nearest proxy appended); `0` when clients connect directly. The first entry is client-written and never trusted |
  307. | `TREG_RATE_LIMIT_EXEMPT_IPS` | *(empty)* | comma-separated addresses or CIDR blocks exempt from every per-IP limit (an authorized security test, a monitoring probe); per-email, per-user and deployment-wide limits still apply. A malformed entry refuses to start |
  308. | `TREG_REQUIRED_EXTENSIONS` | *(empty)* | comma-separated policy extensions (`treg.extensions` entry points) that must be installed, else startup fails. treg.to runs a private abuse-policy extension this way; it can only restrict ([policy extensions](docs/context/architecture/policy-extensions.md)) |
  309. | `TREG_TURNSTILE_SITE_KEY` / `_SECRET` | *(empty)* | Cloudflare Turnstile on every email sign-in form and on a new address's first GitHub/Google sign-in; either empty = off. The site key is served in `/captcha.js`, the secret only reaches siteverify |
  310. | `TREG_TURNSTILE_MODE` | `observe` | `observe` logs each outcome and changes nothing; `enforce` refuses a code to a missing or invalid token, gives no signup credit when Cloudflare cannot answer, and gives a new GitHub/Google user signup credit only on a passed check |
  311. | `TREG_TURNSTILE_SOCIAL` | `true` | `false` skips the check on a new address's first GitHub/Google sign-in, which then gets signup credit as with no widget; the email door is unchanged |
  312. | `TREG_TURNSTILE_HOSTNAMES` | *(empty)* | comma-separated hosts a token must be solved on; empty = the `TREG_PUBLIC_URL` host (and its known aliases) |
  313. | `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. |
  314. | `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. |
  315. | `TREG_KV_URL` | *(empty)* | shared key-value store (Redis protocol) for counters every worker must agree on, today the per-team review-invitation budget. Empty = an in-process fallback, fine for one worker |
  316. No `.env` is needed for local dev — every setting has a working default (ephemeral key, sqlite).
  317. > **⚠️ Back these up before moving or redeploying:** the Fernet key (`TREG_SECRET_KEY`) and the
  318. > database (Postgres in prod; `treg.db` for a local sqlite run). Lose the Fernet key and every
  319. > stored secret it sealed becomes unrecoverable; the same holds for a KMS key that is deleted.
  320. ## Architecture
  321. **Request flow for `/call`:** resolve tool (by URL host + longest `base_url` prefix, or by name) →
  322. decrypt its secret(s) → apply each binding's injector → stream to the upstream → fire-and-forget
  323. audit record. The infra relay streams bytes without business logic. The call application buffers
  324. responses needing settlement or ownership evidence up to 8 MiB; larger responses return a 502
  325. without charging instead of a truncated success. Endpoints that inline media (Gemini images)
  326. declare `spooled_response`: their metered answer is read to a temp file instead, settled from its
  327. reported usage, and relayed whole. Authorized free final downloads needing no body
  328. evidence stream in full, as do own-key and own-tool responses.
  329. **Module map** (`src/treg/`):
  330. | Module | Role |
  331. | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
  332. | `proxy.py` | `relay()` — the whole product in one function: a faithful streaming proxy |
  333. | `injectors.py` | the auth-shape seam: `env`, `cli_auth`, `secret_file`, `oauth` place a secret into a header/query |
  334. | `oauth.py` | token freshness (single-flight refresh) + the connect flow (consent URL, code exchange) |
  335. | `health.py` | credential health: refresh oauth, probe tools, webhook the owner of anything broken |
  336. | `convert.py` | scaffold a skill directory into a registerable bundle manifest |
  337. | `api.py` | the API — the only brain; CLI + skill are thin clients over it |
  338. | `cli.py` | the `treg` CLI |
  339. | `models.py` | SQLModel tables: `Org`, `User`, `Membership`, `Invite`, `Secret`, `Tool`, `Bundle`, `PendingOAuth`, `CallRecord` |
  340. | `crypto.py` `config.py` `db.py` `audit.py` | Fernet encryption + tokens · settings · async DB · deferred audit writer |
  341. **The 4 auth shapes** (per binding `injector`): `env` (plain string / API key) · `secret_file` (a
  342. JSON token file, pull a field) · `oauth` (a JSON OAuth token, auto-refreshed if refreshable) ·
  343. `cli_auth` (material lifted from a CLI's keychain).
  344. **Faithful-relay contract:** the proxy alters **only** three things, everything else is verbatim:
  345. 1. hop-by-hop transport headers (re-derived per hop),
  346. 2. treg's own control + edge-forwarding headers (`x-treg-token`, `x-treg-org`,
  347. `ngrok-skip-browser-warning`, `x-forwarded-*`, `via`, …) and treg's session cookie — all stripped,
  348. never leak upstream,
  349. 3. the injected credential(s).
  350. **OAuth, three ways to get the first token:** *manual upload* (drop in a `token.json`) ·
  351. *auto-refresh* (if the token carries `refresh_token` + client creds, treg keeps it fresh, you never
  352. re-upload) · *hosted connect flow* (`treg oauth connect` → browser consent → treg captures the
  353. token itself).
  354. **Health checks:** give a tool an optional probe (`{method, path, expect_status}`); a periodic run
  355. (on demand or via cron) validates every credential, refreshes OAuth, and webhooks the owner of any
  356. that break.
  357. Deep design lives in [`docs/context/`](docs/context/README.md) (per-subsystem fragments).
  358. ## Tests
  359. ```bash
  360. uv run --with pytest-xdist pytest -n auto -q # daily local default (same shape as CI)
  361. uv run --frozen python -m pytest -q # serial: debugging one test, or order
  362. ```
  363. Coverage: proxy walking-skeleton, all injector shapes, per-user auth + CRUD + audit, skill composer,
  364. URL-passthrough + faithful relay, OAuth refresh + connect flow, health checks, `treg run`/shell,
  365. upload/scan, orgs + invites, the dashboard API, CLI.
  366. ## Contributing & docs
  367. ```
  368. treg/
  369. ├── src/treg/ # the package (api, cli, proxy, injectors, oauth, health, convert, models, …)
  370. │ └── web/ # dashboard, landing, tutorial, llms.txt, skill.md, install.sh
  371. ├── tests/ # pytest suite (CI + local default: pytest-xdist -n auto)
  372. ├── docs/
  373. │ └── context/ # design fragments (codemap system) + generated index
  374. ├── USAGE.md # full treg CLI reference
  375. └── pyproject.toml
  376. ```
  377. Per-subsystem design docs are **fragments** in `docs/context/`, each citing its `src/treg/*`
  378. sources. Working in this repo with an AI agent? The `/tools-registry-context` skill loads the
  379. right fragment for what you're touching and keeps the docs in sync — run
  380. `/tools-registry-context sync` before pushing.
  381. **Roadmap:** MCP support · finer permission tiers · at-rest key-management hardening · possible
  382. Loopni merge.
  383. ## License
  384. Apache 2.0 with additional terms ([`LICENSE`](LICENSE)): use it freely — including commercially,
  385. inside your own organization (self-hosting your own registry is encouraged). The restriction: don't
  386. redistribute the code to third parties as a competing hosted/managed registry service without written
  387. permission (`jason@superdesign.dev`). **Using the hosted treg.to API** inside your own product —
  388. with pass-through billing via `X-Treg-Meta` and `usage/by-tag` — is allowed without permission;
  389. that's calling our API, not redistributing our software.
  390. ### Pinned customer read scopes
  391. For a restricted customer agent, `treg org agent-new bot --pin customer=cust_A` enforces attribution
  392. and scopes call/run history, archived results and shared-provider async ownership to that pin.
  393. Foreign or unattributed ids return 404; an unpinned operator keeps the org-wide view and shared
  394. balance. BYOK account access and public media URLs retain their existing permissions. See the
  395. [multi-tenancy contract](docs/context/architecture/multi-tenancy.md#caller-tags-and-pinned-read-scopes)
  396. for multiple pins, migration and replay behavior.
.agents/skills/ugc-talking-head-video/scripts/host_file.py · Bundled script · 52 lines · 4 findings marked
  1. #!/usr/bin/env python3
  2. """Host a local file at a public URL that PiAPI can fetch, and PROVE the hosted bytes are identical.
  3. Usage: host_file.py <path> -> prints the URL on stdout, exits 1 if no host served identical bytes.
  4. Why this exists (lessons from the first build):
  5. - replicate.delivery URLs served fine to us but PiAPI's fetcher got "fetch object not found".
  6. - catbox stored a TRUNCATED copy and de-duplicates by hash, so re-uploading returned the same broken file.
  7. - tmpfiles.org returned HTML on download.
  8. So: upload, download back, byte-compare, only then trust the URL. Try hosts in order.
  9. """
  10. import subprocess
  11. import sys
  12. import json
  13. import os
  14. import filecmp
  15. import tempfile
  16. UA = "Mozilla/5.0 (Macintosh) ugc-skill"
  17. def curl(*args):
  18. return subprocess.run(["curl", "-s", "-A", UA, *args], capture_output=True, text=True).stdout
  19. def verify(url, path):
  20. if not url.startswith("http"): return False
  21. with tempfile.NamedTemporaryFile(delete=False) as t: tmp = t.name
  22. subprocess.run(["curl", "-sL", "-A", UA, "-o", tmp, url])
  23. ok = os.path.getsize(tmp) == os.path.getsize(path) and filecmp.cmp(path, tmp, shallow=False)
  24. os.unlink(tmp); return ok
  25. def uguu(path):
  26. r = curl("-F", f"files[]=@{path}", "https://uguu.se/upload")
    • Note: Quoted as data in code: Downloads from an anonymous file host (uguu.se), so what it fetches can change unseen
    • Warning: Talks to a raw IP address or throwaway host, where malware is often staged
    • Line 32 on GitHub
  27. try: return json.loads(r)["files"][0]["url"]
  28. except (ValueError, KeyError, IndexError, TypeError): return ""
  29. def catbox(path):
  30. return curl("-F", "reqtype=fileupload", "-F", f"fileToUpload=@{path}", "https://catbox.moe/user/api.php").strip()
    • Note: Quoted as data in code: Downloads from an anonymous file host (catbox.moe), so what it fetches can change unseen
    • Warning: Talks to a raw IP address or throwaway host, where malware is often staged
    • Line 37 on GitHub
  31. def litterbox(path):
  32. return curl("-F", "reqtype=fileupload", "-F", "time=72h", "-F", f"fileToUpload=@{path}",
  33. "https://litterbox.catbox.moe/resources/internals/api.php").strip()
  34. def main():
  35. path = sys.argv[1]
  36. for name, fn in (("uguu", uguu), ("catbox", catbox), ("litterbox", litterbox)):
  37. url = fn(path)
  38. if verify(url, path):
  39. print(url); print(f"[host_file] {name} OK: {url}", file=sys.stderr); return 0
  40. print(f"[host_file] {name} failed or served different bytes: {url[:80]!r}", file=sys.stderr)
  41. print("[host_file] no host served identical bytes", file=sys.stderr); return 1
  42. if __name__ == "__main__": sys.exit(main())

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.