superdesigndev/treg

treg – a shared tool‑catalog and proxy for AI agents

What it is – treg (short for Tool Registry) is a hosted‑or‑self‑hosted service that lets an LLM‑based agent call any third‑party API or CLI without the agent having to know the vendor, store credentials, or manage billing. It works like OpenRouter for language models, but for tools: SEO services, people‑enrichment APIs, ad platforms, CLIs such as stripe, gh, vercel, etc.

Why it matters – Real‑world AI agents need dozens of paid SaaS APIs (Semrush, Crunchbase, Apollo, …). Those APIs are usually behind per‑seat subscriptions and require secret keys. treg centralises those keys, meters usage, and exposes a single token (X‑Treg‑Token) that any agent can use. The agent simply asks “find backlinks for example.com” and treg picks a catalogued endpoint, injects the appropriate secret server‑side, and forwards the request. This removes credential handling from the agent code and makes it cheap to prototype with many services.

Core concepts

Concept	Meaning
Catalog	A curated list of >3,000 endpoints from 60+ providers, each with a price per call. treg supplies its own credentials for many of them, billed against a prepaid team balance (free $1 credit on new accounts).
Team‑owned tools	Your own API keys, OAuth tokens, or vendor CLIs that you upload to treg. Your key always overrides treg’s own key, making those calls free of the prepaid balance.
Skill / bundle	A `SKILL.md` recipe together with the secrets and tools it needs. Skills can be shared across the team and installed into an agent (e.g., Claude, MiniMax).
Token	A per‑user, per‑org JWT (`X‑Treg‑Token`) that authenticates every call.
Proxy endpoint	`GET/POST https://treg.to/call/<upstream‑url>` – the actual streaming proxy that injects auth and forwards the request.

Main features

One‑token access – agents only need the treg token; no per‑provider credentials.
Pay‑per‑call pricing – each catalogued endpoint shows a price (as low as a cent). Teams get a prepaid balance and can top‑up via the CLI.
Self‑hostable – the server is a FastAPI app (pip install "tools-registry[server]"). Run locally with scripts/dev-local.sh or deploy to any cloud.
CLI – treg provides commands to login, browse the catalog, call tools, manage secrets, upload your own APIs/CLIs, and inspect usage.
Agent plugins – ready‑made Claude Code plugin and MiniMax plugin so an LLM can invoke treg without any manual setup.
Team & role management – orgs, members, roles (owner/admin/member/viewer) and per‑member tool access controls.
Audit & balance – every call is logged, balance is shown (treg balance), and out‑of‑balance responses return HTTP 402 with machine‑readable fields for agents to react.
Enrich Arena – a public UI to compare results from multiple providers for the same query and vote on the best answer.

Typical workflow for an AI agent

Discover – treg catalog search "backlinks for a domain" returns matching endpoints with price and example payload.
Call – treg call hunter.people.email.find --query domain=reddit.com (or via HTTP GET /call/...). treg injects the stored secret, forwards the request, streams the response back.
Handle balance – If the team’s prepaid balance is exhausted, the proxy returns 402; the agent can automatically top‑up or fall back to a self‑hosted key.
Share – Teams can treg upload their own .env keys, CLIs, or full skill bundles so every teammate (or agent) can reuse them.

Getting started (quick‑start)

# Install the CLI (points to the hosted registry by default)
curl -fsSL https://treg.to/install.sh | sh

# Authenticate (GitHub OAuth by default)
treg login

# Browse the catalog and make a test call
treg catalog search "backlinks for a domain"
treg call tikhub.tiktok.user.profile --query uniqueId=tiktok

treg balance   # see remaining prepaid credits

For self‑hosting:

# one‑liner (requires tmux + uv)
scripts/dev-local.sh up   # server on http://localhost:18790

# In another shell, use the sandboxed CLI against the local server
scripts/dev-local.sh cli login
scripts/dev-local.sh cli catalog search "email finder"

Who should use treg?

Product teams building AI assistants that need to enrich responses with real‑world data (SEO metrics, company info, ad spend, etc.).
LLM‑ops engineers who want a single, auditable gateway for all third‑party services and want to avoid embedding secrets in prompts or code.
Start‑ups that want cheap per‑call access to expensive SaaS APIs without buying a full subscription.
Researchers prototyping multi‑tool agents who need a reproducible, version‑controlled registry of endpoints and CLIs.

Installation & deployment notes

Component	How to install
CLI only (talk to an existing registry)	`pip install tools-registry`
Full server (self‑host)	`pip install "tools-registry[server]"` – brings in FastAPI, aiosqlite/Postgres drivers, and encryption.
Run locally	`scripts/dev-local.sh up` (tmux + hot‑reload) or `uv run python -m treg` after `uv sync`.
Production	Deploy the FastAPI app behind a TLS terminator; configure `TREG_DATABASE_URL`, `TREG_SECRET_KEY`, OAuth client IDs, and optional email (Resend) for OTPs.

Limitations & caveats

treg only proxies catalogued endpoints; if an endpoint has no price listed, the call is rejected and you must upload your own key.
The service does not perform any transformation of the upstream response – it is a faithful streaming proxy.
Large responses (>8 MiB) are blocked with a 502 to avoid excessive bandwidth charges.
Secrets are encrypted at rest with a Fernet key; losing TREG_SECRET_KEY renders stored credentials unrecoverable.

Links from the README

Dashboard / hosted service: https://treg.to
Claude plugin guide: docs/CLAUDE-PLUGIN.md
MiniMax plugin guide: docs/MINIMAX-PLUGIN.md
API docs: /docs (OpenAPI) on the running server
Full CLI reference: USAGE.md
Self‑host runbook (private): treg-internal repo (mentioned for production details)

Bottom line: treg is a practical infrastructure layer that lets LLM agents call a huge variety of SaaS tools with a single authentication token, handling billing, secret management, and audit logging for you. It is a genuine, production‑ready open‑source project aimed at the frontier of AI‑augmented workflows.