Treg（面向工具的 OpenRouter）

OpenRouter，但服务对象不是模型，而是 Agent 工具。 让 Agent 指向一个基础 URL、使用一个 Token，它就能完成工作：覆盖 60 多家供应商的 3,000 多个已编目端点——SEO 与反向链接、社交媒体与趋势、个人和公司数据补全、广告、抓取、图像和视频生成——按调用计费，最低从一美分起，无需注册供应商账户。此外，你还可以接入自己团队的密钥、技能和 CLI；团队中每位成员的 Agent 都可以调用它们，而凭据始终不会离开服务器。

按任务提问，而不是按工具提问。 你无需知道哪家厂商销售反向链接数据，也无需持有其账户。只需搜索你想完成的任务，查看价格，然后调用。

Treg 最初为 Superdesign 团队构建，线上服务位于 treg.to——任何人都可以自行托管。

Agent 开展实际工作所需的工具，常常被锁在不值得为单次任务购买的订阅后面——Semrush 每月 139 美元、Moz 每月 99 美元、Crunchbase 每月 99 美元、Apollo 每席位 59 美元——或者藏在注册壁垒之后，甚至根本没有公开 API（仅限邀请、仅限合作伙伴、仅限应用审核）。treg 持有这些账户，并按每次调用的美分小数计费。

两类工具，一个 Token

• 目录（The catalog）——treg 可使用自己的密钥提供的外部端点，或通过无需供应商密钥的已验证公共路径提供的端点。使用自有密钥的调用从团队预付余额中扣费；匿名调用免费。无需拥有供应商账户。新完成验证的账户在创建符合条件的团队时，可一次性获得 1.00 美元免费额度。
• 你自己的工具（Your own tools）——任何团队成员注册的内容：付费 API 账户、OAuth 连接、供应商 CLI、SKILL.md。你自己的密钥始终优先于 treg 的密钥，而且这些调用永不计量收费。

后半部分使用的术语：

• tool（工具） = 注册表使用组织凭据代你调用的内容。分为两类：
  • endpoint（端点）——上游 base_url + 凭据 bindings（绑定）（每个绑定会向请求注入一个密钥；一次请求可携带多个绑定，例如 OAuth bearer 以及 developer-token 请求头）。
  • CLI——运行时注入凭据的供应商二进制程序（stripe、gh、vercel 等）。
• skill / bundle（技能 / 套件） = 一个配方（SKILL.md）+ 其密钥 + 其工具，统一注册。

唯一规则： 代理层转发，而不建模上游服务，并且在服务器端注入认证信息——因此它能够适应上游 API 变化，调用方也永远不持有密钥。

---

第 1 部分 · 使用注册表

访问 treg.to（托管于 Render）——仪表盘、登录以及下文所有 URL 均位于该站点。

流程与仪表盘的 **Getting started（快速入门）**指南一致：

# 1. 安装 CLI——同时将其指向注册表
curl -fsSL https://treg.to/install.sh | sh

# 2. 登录（默认 GitHub · --email 使用一次性验证码 · --token 适用于 Agent/CI）
treg login

# 3. 立即完成有用任务——无需密钥，也无需注册任何内容
treg catalog search "backlinks for a domain"     # 按工具“能做什么”查找工具
treg call tikhub.tiktok.user.profile --query uniqueId=tiktok
treg balance                                     # 精确查看刚才的花费

# （或者使用 `treg onboard` 进入引导式流程）

目录工具的输入参数可通过 treg catalog get <id> 查看。标记为 strict_query 的工具会拒绝未声明或重复的查询参数、不支持的值以及请求体。

你的 Token 会在每次调用中标识你的身份（X-Treg-Token 请求头），并且对所有工具通用。可使用 treg tool ls 发现团队共享的内容；使用 treg health 检查凭据健康状态。

或将其安装为 Claude Code 插件

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

安装时无需 Token，也无需配置。该技能会以 treg:treg 加载，首次运行时会引导你的 Agent 完成后续步骤——CLI、登录，然后是 treg mcp install——最终同时获得命令行 和 treg 工具。其他 Agent 可使用：npx skills add superdesigndev/treg -s treg（-s 参数很重要——没有它，你还会获得此仓库内部的开发技能）。参见 docs/CLAUDE-PLUGIN.md。MiniMax Code / MiniMax Agent 用户可通过 MiniMax Plugin Marketplace 使用同一技能（docs/MINIMAX-PLUGIN.md）。

Claude Connectors Directory 对接地址为 https://treg.to/mcp/v2/。它仅暴露精选目录端点，并将读取调用与写入调用分开，以便 Claude 获得准确的安全信号。现有的 /mcp/ 接口仍可用于目录端点、团队自有工具和导入的技能。有关边界和实现，请参见 MCP and OAuth architecture；有关发布门槛，请参见 submission runbook。

调用你没有密钥的工具

目录按端点能做什么分类：关键词与排名追踪、反向链接与权威度、AI 可见性、趋势与发现、发布到社交媒体、个人和公司数据补全、广告管理与创意、效果衡量。

treg catalog                                    # 所有平台，按活跃度排序
treg catalog search "find a work email"         # 按任务，而不是供应商名称搜索
treg catalog get hunter.people.email.find       # 参数、价格、示例响应
treg call hunter.people.email.find --query domain=reddit.com --query full_name="Alexis Ohanian"

一个已编目调用如何被服务——按以下凭据优先级顺序：

1. 你的团队已为该供应商注册自己的工具 → 使用该工具和该密钥；
2. 你的团队已保存该供应商的密钥 → 通过虚拟工具注入；
3. 两者皆无，但该端点具有已验证公共路径 → 无需供应商密钥，免费；
4. 否则 → 使用 treg 自己的密钥，从团队预付余额扣费。

匿名价格假设调用方不发送供应商凭据请求头。忠实转发会保留调用方的请求头，因此调用方提供的供应商密钥可使用该密钥自身的额度。你自己的凭据始终优先于 treg 的凭据，因此连接你已付费使用的密钥后，相应调用将不会从余额扣费，而不是产生重复付费。对于 treg 未公开价格的端点，系统会拒绝服务，而非免费提供——系统会提示你改为连接自己的密钥。若多个供应商能提供同一能力，treg catalog search 会并列展示其价格；选择权在你手中——treg 不会为你静默选择供应商，也不会在供应商之间自动故障转移。（当 treg 自己在某个供应商的账户额度耗尽时，可能通过 treg 自有中继账户提供_同一_端点，并会在响应中披露；团队可以选择退出。）可主动选择的例外是 treg.<capability> 路由端点：由 treg 为你选择供应商，并明确告知所选供应商。

treg balance          # 剩余额度、进行中的调用、近期支出
treg topup            # 充值，或设置自动充值

余额不足时，系统返回 HTTP 402，其中包含 balance_micro、estimated_cost_micro 和 topup_url，因此 Agent 无需阅读说明文字即可采取行动。

Enrich Arena 位于 /enrich-arena，独立于仪表盘之外。你可以比较各供应商的数据补全答案、成本和速度，一键投票选出最佳答案，或观看顺序瀑布流调用。浏览公开开放；提交需要登录，且计费尝试将使用团队额度。参见 Arena guide。

分享并使用自己的工具

无需思考的路径——将 treg 指向一个项目，它会判断哪些内容可以共享：

treg scan     # 只读预览：上传将注册的密钥、技能和 CLI
treg upload   # 注册它们（服务器端加密）；幂等，使用 --replace 更新

treg upload 会扫描 .env（将密钥与约 80 家已知供应商匹配）、每个技能子目录以及已安装的目录 CLI。有三类内容会进入注册表——以下说明如何分享和使用每一类内容：

分享——使用已保存密钥调用一个上游 URL，或从 .env 批量导入：

treg secret add STRIPE_KEY --value sk_live_123
treg add stripe --base-url https://api.stripe.com --secret STRIPE_KEY

treg upload env --select openai,stripe,resend     # 或直接从 .env 导入

使用——Agent 原生方式：构建真实的上游请求，并为其添加代理前缀。treg 根据主机解析工具、注入凭据，并忠实转发其余所有内容（在上游看到请求之前，会移除你的 X-Treg-Token）：

Real request:   GET https://api.intercom.io/conversations?per_page=5
Through treg:   GET https://treg.to/call/https://api.intercom.io/conversations?per_page=5
                    header:  X-Treg-Token: <your token>

或者使用 CLI 简写形式——并通过 treg calls 查看审计日志：

treg call intercom conversations --query per_page=5
treg call stripe v1/balance

分享——自动完成：treg upload 会检测已安装的目录 CLI（stripe、gh、vercel 等）并进行注册；仅包含配方的目录 CLI 技能（例如 stripe-cli）也会自动变为可运行状态。

使用——treg run 会在注入组织凭据的情况下执行供应商 CLI，因此你永远无需持有密钥或登录：

treg run stripe -- get /v1/balance
treg run gh -- pr list
treg run --server agentmail-cli inboxes list   # 在注册表服务器上运行：密钥永远不会到达你的设备

--local（默认）在你的机器上运行；--server 在注册表上运行，并将输出流式返回。对于整个会话，treg shell start 会打开一个子 shell，其中每个已注册 CLI 都会自动注入凭据——像平常一样直接使用 stripe、gh 等；执行 exit 即恢复原状。treg runs 是审计日志。

分享——一个技能代表完整能力（SKILL.md 配方 + 其密钥 + 其工具），统一注册，使整个团队运行相同技能，并在一个位置维护：

treg upload skills --dir ~/.claude/skills --all   # 一次注册一个文件夹中的全部技能

使用——将任何共享技能拉取到你的 Agent 中；其 API 调用会携带你的 Token 经由 treg 发出，因此密钥保留在服务器上，绝不会写入技能：

treg skill install seo-blog-writer      # 写入 ./.claude/skills/（--all 用于整个库）

手动注册——当启发式规则无法识别工具时

# 多凭据工具（例如 google-ads：OAuth bearer + developer-token 请求头）
treg tool add google-ads --base-url https://googleads.googleapis.com \
  --bind "secret=<oauth-id>,injector=oauth" \
  --bind "secret=<dev-id>,name=developer-token,format={secret}"

# 逐步注册一个技能
treg skill init --dir ./my-skill          # 起草 treg.json（猜测 base_url，查找密钥）
treg skill add  --dir ./my-skill          # 原子化注册配方 + 密钥 + 工具

# 通过浏览器完成 OAuth（生成首个 Token，treg 保存并自动刷新）
treg oauth connect gsc --client-secret client_secret.json \
  --scopes https://www.googleapis.com/auth/webmasters.readonly

每条命令的完整选项参见 USAGE.md。

使用 treg.to 时，CLI 会向 PostHog 发送匿名命令使用数据（不包含参数或凭据）。可通过 TREG_TELEMETRY=0 或 DO_NOT_TRACK=1 禁用。参见分析详情。

一个账户最多可拥有 10 个团队。作为成员加入其他团队不计入此上限。

所有内容都以 **org（组织）**为作用域：一个 Token = 一个 (user, org) 成员关系，每个密钥、工具和技能均属于当前活动组织。角色包括：owner / admin / member / viewer。

treg org create "Acme"                        # 创建团队，成为 owner
treg org invite teammate@acme.com             # 通过邮箱邀请（选择角色和工具访问权限）
treg org join <code> --email you@acme.com     # 接受邀请（新用户会被创建）
treg org ls | use <slug> | members            # 切换组织、查看成员列表
treg org access <member> --tools a,b          # 按成员设置工具访问权限（admin+）

• 反馈：treg feedback submit friction "The pagination example is unclear." 在不包含私人信息的前提下，分享问题或建议。参见反馈说明。

• 评价：treg review CALL_ID useful 在使用受邀目录调用的结果后进行评分；not_sure 也可以。请省略私密数据，然后继续任务。

• USAGE.md——完整的 treg CLI 参考文档。

• /llms.txt——Agent 入门文件：调用协议、发现、认证、CLI、技能。一次获取即可让 Agent 了解整个注册表。

• treg.to 的仪表盘——提供完整 CRUD、引导式教程（Help → Tutorial）以及可复制的 Agent 设置说明。

• API——CLI 所做的一切都是普通 HTTP；交互式 OpenAPI 文档位于 /docs。代理端点为 /call/{...}；所有端点均接受 X-Treg-Token 请求头。

---

第 2 部分 · 自托管与开发

一条命令即可启动（需要 tmux + uv；它会自行同步虚拟环境）：

scripts/dev-local.sh up        # 服务运行于 http://localhost:18790，采用对开发安全的设置

它会在 tmux 中以热重载方式运行服务器，使用独立的 sqlite 数据库（treg-dev.db）以及邮箱 OTP 开发模式（登录验证码直接显示在页面上——无需邮件发送服务）。日常操作：

scripts/dev-local.sh cli login   # 沙盒化 CLI：绝不会触及真实的 ~/.treg/config.json
scripts/dev-local.sh logs        # 服务器输出          · status / restart / down
scripts/dev-local.sh reset   

Treg (OpenRouter for Tools)

OpenRouter, but for agent tools instead of models. Point an agent at one base URL with one token and it can do the job: 3,000+ catalogued endpoints across 60+ providers — SEO and backlinks, social and trends, people and company enrichment, ads, scraping, image and video generation — priced per call, from a cent , with no provider signup. Plus your own team's keys, skills and CLIs, callable by every teammate's agent without the credential ever leaving the server.

Ask for the task, not the tool. You do not need to know which vendor sells backlink data, or to hold an account with them. Search for what you want to do, read the price, call it.

Built for the Superdesign team, live at treg.to — anyone can self-host.

The tools an agent needs for real work sit behind subscriptions nobody buys for a single run — Semrush $139/mo, Moz $99/mo, Crunchbase $99/mo, Apollo $59/seat — behind signup walls, or behind no public API at all (invite-only, partner-only, app-review-only). treg carries those accounts and bills fractions of a cent per call.

Two kinds of tool, one token

• The catalog — external endpoints treg can serve with its own key or through a verified public route that needs no provider key. Own-key calls use the team's prepaid balance; anonymous calls are free. No account with the provider is needed. New verified accounts receive $1.00 free once, when they create an eligible team.
• Your own tools — anything a teammate registered: a paid API account, an OAuth connection, a vendor CLI, a SKILL.md. Your own key always wins over treg's, and those calls are never metered.

The vocabulary for the second half:

• tool = something the registry calls for you with the org's credential. Two kinds:
  • endpoint — an upstream base_url + credential bindings (each binding injects one secret into the request; a request can carry several, e.g. an OAuth bearer and a developer-token header).
  • CLI — a vendor binary (stripe, gh, vercel, ...) run with the credential injected.
• skill / bundle = a recipe (SKILL.md) + its secrets + its tool(s), registered together.

The one rule: the proxy relays, never models the upstream, and injects auth server-side — so it survives upstream API changes and callers never hold keys.

---

Part 1 · Using the registry

Visit treg.to (hosted on Render) — the dashboard, sign-in, and every URL below live there.

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)

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.

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 with no token and no configuration. The skill loads as treg:treg and, on its first run, walks your agent through the rest — the CLI, sign-in, then treg mcp install — so you end up with the command line and treg's tools. Other agents: npx skills add superdesigndev/treg -s treg (the -s matters — without it you also get this repo's internal dev skills). See docs/CLAUDE-PLUGIN.md. MiniMax Code / MiniMax Agent users: the same skill ships via the MiniMax Plugin Marketplace (docs/MINIMAX-PLUGIN.md).

The Claude Connectors Directory surface is https://treg.to/mcp/v2/. It exposes only curated catalog endpoints and separates read calls from write calls so Claude receives accurate safety signals. The existing /mcp/ surface remains available for catalog endpoints, team-owned tools, and imported skills. See the MCP and OAuth architecture for the boundary and implementation, and the submission runbook for release gates.

Call a tool you don't have a key for

The catalog is grouped by what endpoints do : keyword and rank tracking, backlinks and authority, AI visibility, trending and discovery, publishing to socials, people and company enrichment, ads management and creative, measurement.

treg catalog                                    # every platform, busiest first
treg catalog search "find a work email"         # by the job, not the vendor
treg catalog get hunter.people.email.find       # params, PRICE, example response
treg call hunter.people.email.find --query domain=reddit.com --query full_name="Alexis Ohanian"

How a catalogued call is served — the credential ladder, in order:

1. your team registered its own tool for that provider → that tool, that key;
2. your team stored a secret for the provider → injected through a virtual tool;
3. neither, and the endpoint has a verified public route → no provider key , free;
4. otherwise → treg's own key , billed to the team's prepaid balance.

The anonymous price assumes the caller does not send a provider credential header. The faithful relay preserves caller headers, so a caller-supplied provider key can use that key's credits. Your own credential always beats treg's, so connecting a key you already pay for makes those calls free of the balance rather than duplicating them. An endpoint treg has no published price for is refused , not served free — you are told to connect your own key instead. Where several providers serve one capability, treg catalog search shows them side by side with prices; choosing is yours — treg does not silently pick or fail over between providers for you. (When treg's own account for a provider is out it may serve the same endpoint through a treg-owned relay account, 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.

treg balance          # credit left, calls in flight, recent spend
treg topup            # add funds, or set up automatic top-ups

Out of balance is an HTTP 402 carrying balance_micro, estimated_cost_micro and a topup_url, so an agent can act on it without reading prose.

Enrich Arena lives at /enrich-arena, outside the dashboard. Compare enrichment answers with each vendor’s cost and speed, vote for the best answer in one click, or watch a sequential waterfall. Browsing is public; submitting requires login, and billable attempts use your team's credits. See the Arena guide.

Share & use your own tools

The zero-thought path — point treg at a project and it figures out what's shareable:

treg scan     # read-only preview: the keys, skills & CLIs upload would register
treg upload   # register them (encrypted server-side); idempotent, --replace to update

treg upload scans the .env (matching keys against ~80 known providers), every skill subdirectory, and installed catalog CLIs. Three kinds of things go into the registry — here's how to share and use each:

Share — one upstream URL callable with a stored key, or bulk from a .env:

treg secret add STRIPE_KEY --value sk_live_123
treg add stripe --base-url https://api.stripe.com --secret STRIPE_KEY

treg upload env --select openai,stripe,resend     # or straight from the .env

Use — the agent-native way: build the real upstream request and prefix it with the proxy. treg resolves the tool by host, injects the credential, and relays everything else faithfully (your X-Treg-Token is stripped before the upstream sees it):

Real request:   GET https://api.intercom.io/conversations?per_page=5
Through treg:   GET https://treg.to/call/https://api.intercom.io/conversations?per_page=5
                    header:  X-Treg-Token: <your token>

Or the CLI shorthand — and treg calls for the audit log:

treg call intercom conversations --query per_page=5
treg call stripe v1/balance

Share — automatic: treg upload detects installed catalog CLIs (stripe, gh, vercel, …) and registers them; a recipe-only catalog CLI skill (e.g. stripe-cli) auto-becomes runnable too.

Use — treg run executes the vendor CLI with the org's credential injected , so you never hold the key or log in:

treg run stripe -- get /v1/balance
treg run gh -- pr list
treg run --server agentmail-cli inboxes list   # runs on the registry server: the key never reaches you

--local (default) runs on your machine; --server runs on the registry and streams output back. For a whole session, treg shell start opens a subshell where every registered CLI injects automatically — just use stripe, gh, … normally; exit reverts. treg runs is the audit log.

Share — a skill is a whole capability (SKILL.md recipe + its secrets + its tool(s)), registered together so the whole team runs the same skill, maintained in one place:

treg upload skills --dir ~/.claude/skills --all   # register a folder of skills in one pass

Use — pull any shared skill into your agent; its API calls go through treg with your token, so the key stays on the server, never in the skill:

treg skill install seo-blog-writer      # writes into ./.claude/skills/  (--all for the library)

Manual registration — when the heuristics can't figure a tool out

# multi-credential tool (e.g. google-ads: OAuth bearer + a developer-token header)
treg tool add google-ads --base-url https://googleads.googleapis.com \
  --bind "secret=<oauth-id>,injector=oauth" \
  --bind "secret=<dev-id>,name=developer-token,format={secret}"

# one skill, step by step
treg skill init --dir ./my-skill          # drafts treg.json (guesses base_url, finds secrets)
treg skill add  --dir ./my-skill          # registers recipe + secrets + tool, atomically

# OAuth via the browser (mints the first token, treg holds it and auto-refreshes)
treg oauth connect gsc --client-secret client_secret.json \
  --scopes https://www.googleapis.com/auth/webmasters.readonly

Full options for every command: USAGE.md.

The CLI sends anonymous command usage to PostHog when using treg.to (no arguments or credentials). Disable with TREG_TELEMETRY=0 or DO_NOT_TRACK=1. See analytics details.

An account can own up to 10 teams. Joining other teams as a member does not count toward this limit.

Everything is scoped to an org : a token = a (user, org) membership, and every secret, tool, and skill belongs to the active org. Roles: owner / admin / member / viewer.

treg org create "Acme"                        # make a team, become owner
treg org invite teammate@acme.com             # invite by email (pick role + tool access)
treg org join <code> --email you@acme.com     # accept an invite (creates you if new)
treg org ls | use <slug> | members            # switch orgs, see the roster
treg org access <member> --tools a,b          # per-member tool access (admin+)

• Feedback: treg feedback submit friction "The pagination example is unclear." Share problems or suggestions without private information. See feedback instructions.

• Review: treg review CALL_ID useful Rate an invited catalog call after using its result; not_sure is fine. Omit private data and continue the task.

• USAGE.md — the full treg CLI reference.

• /llms.txt — the agent-onboarding file: call protocol, discovery, auth, CLI, skills. One fetch teaches an agent the whole registry.

• The dashboard at treg.to — full CRUD, a guided tutorial (Help → Tutorial), and copyable setup instructions for your agents.

• The API — everything the CLI does is plain HTTP; interactive OpenAPI docs live at /docs. The proxy endpoint is /call/{...}; all endpoints take the X-Treg-Token header.

---

Part 2 · Self-hosting & development

One command (needs tmux + uv; it syncs the venv itself):

scripts/dev-local.sh up        # server on http://localhost:18790, dev-safe settings

That runs the server in tmux with hot-reload, its own sqlite DB (treg-dev.db), and email OTP dev mode (sign-in codes shown on the page — no mail sender needed). Day-to-day:

scripts/dev-local.sh cli login   # sandboxed CLI: never touches your real ~/.treg/config.json
scripts/dev-local.sh logs        # server output          · status / restart / down
scripts/dev-local.sh reset       # wipe the dev DB + CLI sandbox for a fresh start

Or run the server directly, without tmux:

uv sync                        # create the venv from uv.lock (pulls the server deps for dev)
uv run python -m treg upgrade  # prepare schema + run idempotent release tasks without serving
uv run python -m treg          # serve on 0.0.0.0:18790 (add --reload for dev)
uv run python -m treg keygen   # print a fresh Fernet key for TREG_SECRET_KEY

Installing to run a server (not from source): the base package is the CLI only. To run a registry, install the server extra — pip install "tools-registry[server]" — which adds FastAPI, the database drivers, and encryption. pip install tools-registry alone gives just the treg command for talking to an existing registry.

The official hosted service is available at treg.to. Its production topology and live settings are maintained in the private operator runbook.

Environment variables (prefix TREG_, read from .env):

Var	Default	Purpose
TREG_DATABASE_URL	sqlite+aiosqlite:///./treg.db	DB URL (SQLite for dev, Postgres in prod)
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.
TREG_SECRET_KEY	(empty)	Fernet key for secrets-at-rest; empty → an ephemeral key is minted (secrets won't survive a restart)
TREG_PUBLIC_URL	https://treg.to	treg's public base, used to build the OAuth callback URI
TREG_SESSION_SECRET	(empty)	signs the dashboard session cookie; falls back to TREG_SECRET_KEY. Set a real value in prod
TREG_GITHUB_CLIENT_ID / _SECRET	(empty)	GitHub OAuth sign-in (callback <public_url>/auth/github/callback); empty hides the button
TREG_GOOGLE_CLIENT_ID / _SECRET	(empty)	Google OAuth sign-in (redirect <public_url>/auth/google/callback); empty hides the button
TREG_INSTAGRAM_CLIENT_ID / _SECRET	(empty)	Instagram App ID and secret for direct Instagram Login (redirect <public_url>/oauth/callback)
TREG_META_CLIENT_ID / _SECRET	(empty)	Meta app credentials for Facebook Pages, Meta Ads, and optional Instagram page-tools
TREG_OAUTH_REVIEW_PENDING	instagram-login,page-messages	Comma-separated registry review keys whose capabilities must remain gated; hosted review state is maintained privately.
TREG_RESEND_API_KEY / TREG_EMAIL_FROM	(empty)	transactional email via Resend (OTP codes + invites); From must be a Resend-verified sender
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
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.
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.
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

No .env is needed for local dev — every setting has a working default (ephemeral key, sqlite).

⚠️ Back these up before moving or redeploying: the Fernet key (TREG_SECRET_KEY) and the database (Postgres in prod; treg.db for a local sqlite run). Lose the Fernet key and every stored secret becomes unrecoverable.

Request flow for/call: resolve tool (by URL host + longest base_url prefix, or by name) → decrypt its secret(s) → apply each binding's injector → stream to the upstream → fire-and-forget audit record. The infra relay streams bytes without business logic. The call application buffers responses needing settlement or ownership evidence up to 8 MiB; larger responses return a 502 without charging instead of a truncated success. Authorized free final downloads needing no body evidence stream in full, as do own-key and own-tool responses.

Module map (src/treg/):

Module	Role
proxy.py	relay() — the whole product in one function: a faithful streaming proxy
injectors.py	the auth-shape seam: env, cli_auth, secret_file, oauth place a secret into a header/query
oauth.py	token freshness (single-flight refresh) + the connect flow (consent URL, code exchange)
health.py	credential health: refresh oauth, probe tools, webhook the owner of anything broken
convert.py	scaffold a skill directory into a registerable bundle manifest
api.py	the API — the only brain; CLI + skill are thin clients over it
cli.py	the treg CLI
models.py	SQLModel tables: Org, User, Membership, Invite, Secret, Tool, Bundle, PendingOAuth, CallRecord
crypto.py config.py db.py audit.py	Fernet encryption + tokens · settings · async DB · deferred audit writer

The 4 auth shapes (per binding injector): env (plain string / API key) · secret_file (a JSON token file, pull a field) · oauth (a JSON OAuth token, auto-refreshed if refreshable) · cli_auth (material lifted from a CLI's keychain).

Faithful-relay contract: the proxy alters only three things, everything else is verbatim:

1. hop-by-hop transport headers (re-derived per hop),
2. treg's own control + edge-forwarding headers (x-treg-token, x-treg-org, ngrok-skip-browser-warning, x-forwarded-*, via, …) and treg's session cookie — all stripped, never leak upstream,
3. the injected credential(s).

OAuth, three ways to get the first token: manual upload (drop in a token.json) · auto-refresh (if the token carries refresh_token + client creds, treg keeps it fresh, you never re-upload) · hosted connect flow (treg oauth connect → browser consent → treg captures the token itself).

Health checks: give a tool an optional probe ({method, path, expect_status}); a periodic run (on demand or via cron) validates every credential, refreshes OAuth, and webhooks the owner of any that break.

Deep design lives in docs/context/ (per-subsystem fragments).

uv run --with pytest-xdist pytest -n auto -q   # daily local default (same shape as CI)
uv run --frozen python -m pytest -q            # serial: debugging one test, or order

Coverage: proxy walking-skeleton, all injector shapes, per-user auth + CRUD + audit, skill composer, URL-passthrough + faithful relay, OAuth refresh + connect flow, health checks, treg run/shell, upload/scan, orgs + invites, the dashboard API, CLI.

treg/
├── src/treg/            # the package (api, cli, proxy, injectors, oauth, health, convert, models, …)
│   └── web/             # dashboard, landing, tutorial, llms.txt, skill.md, install.sh
├── tests/               # pytest suite (CI + local default: pytest-xdist -n auto)
├── docs/
│   ├── context/         # design fragments (codemap system) + generated index
│   └── ONBOARDING.md    # first-time bootstrap
├── USAGE.md             # full treg CLI reference
└── pyproject.toml

Per-subsystem design docs are fragments in docs/context/, each citing its src/treg/* sources. Working in this repo with an AI agent? The /tools-registry-context skill loads the right fragment for what you're touching and keeps the docs in sync — run /tools-registry-context sync before pushing.

Roadmap: MCP support · finer permission tiers · at-rest key-management hardening · possible Loopni merge.

Apache 2.0 with additional terms (LICENSE): use it freely — including commercially, inside your own organization (self-hosting your own registry is encouraged). The restriction: don't redistribute the code to third parties as a competing hosted/managed registry service without written permission (jason@superdesign.dev). Using the hosted treg.to API inside your own product — with pass-through billing via X-Treg-Meta and usage/by-tag — is allowed without permission; that's calling our API, not redistributing our software.

Pinned customer read scopes

For a restricted customer agent, treg org agent-new bot --pin customer=cust_A enforces attribution and scopes call/run history, archived results and shared-provider async ownership to that pin. Foreign or unattributed ids return 404; an unpinned operator keeps the org-wide view and shared balance. BYOK account access and public media URLs retain their existing permissions. See the multi-tenancy contract for multiple pins, migration and replay behavior.