# treg

> Integrate the

## Metadata

- Author: [@superdesigndev](https://github.com/superdesigndev)
- Repo: <https://github.com/superdesigndev/treg.git>
- GitHub: [superdesigndev/treg](https://github.com/superdesigndev/treg)
- Stars: 530
- Language: Python
- License: [NOASSERTION](https://spdx.org/licenses/NOASSERTION.html)
- Homepage: <https://treg.to>
- Topics: `agents`, `api-keys`, `cli`, `credentials`, `developer-tools`, `dsh-plugin`, `mcp`, `proxy`, `python`, `registry`, `secrets`
- Forks: 47
- Open Issues: 12
- Last push: 2026-08-20T12:45:29.000Z
- Added: 2026-08-17T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:superdesigndev/treg
```

## Wiki

## One-Line Description
treg is the "OpenRouter for Tools" — a DSH plugin that brings the external tools marketplace (~2600 API endpoints across 40 providers) to your DSH agent; the agent uses a single token to call, and the original API key always stays on the treg server side, never sent to the caller.

## Core Capabilities
- Exposes 5 MCP tools in DSH agent: `catalog_search` / `catalog_get` / `call` / `balance` / `my_tools`, covering the complete flow from "find tool by task → check price → call → check balance"
- Gives agents access to ~2600 catalog endpoints: SEO & backlinks, keywords & rankings, AI visibility, social profiles & trends, people/company enrichment, ad library & campaign management, web scraping, etc.
- Server-side credential injection: caller only needs `X-Treg-Token`, original API key is injected by treg at the gateway, requests are forwarded as-is to upstream
- Team's own key takes priority: if someone in the team has already registered a provider's key, calls use that key, not consuming treg balance or incurring charges
- Graceful degradation without token: MCP connector auto-disables, SKILL still loads and guides user to get token, profile won't crash due to missing token
- Supports HTTP URL-passthrough: building "real upstream URL prefix `/call/`" lets treg automatically identify tools and forward them (native agent calling method)

## Technical Implementation
- **Language**: TypeScript (dsh/ directory, ESM no build step) + Python 3.12-3.13 (treg registry server, optional)
- **Key Dependencies**: `@deepseek-ai/cordis` (ctx.skills.registerProvider), `@deepseek-ai/dsh-mcp-client` (MCP connector line), `node:fs/promises` (reading bundled SKILL.md)
- **Architecture Pattern**: Cordis dual-row injection — `treg-skill` row always on and registers SKILL provider; `treg-mcp` row uses `!!js` expression to disable when `TREG_TOKEN` is empty, avoiding "connector without token registering 5 always-401 tools"
- **Entry File**: dsh/index.js (apply() registers skill provider, export name='treg-skill', inject=['skills'])

## Use Cases
When DSH agent needs to query external real-time data — such as competitor SEO backlinks, keyword search volume, TikTok/Instagram profiles, person email, opponent ad creative — the agent can pay-per-call with a single token, eliminating the need to separately register accounts, apply for keys, and manage multiple secrets for each data source.

This is suitable for developers who have DSH set up but want to extend their agent's "action capability" to external SaaS data APIs; not suitable for scenarios involving only local conversation without external data queries.

## Prerequisites & Compatibility
| Dependency | Min Version | Notes |
|---|---|---|
| DSH Host | Not declared | Injects cordis via `dsh.bundle.patch`, host needs to support cordis plugin protocol |
| Node.js | Not declared | dsh/index.js is pure ESM, no build step; specific lower bound depends on DSH host |
| Python (self-hosted treg server) | >=3.12,<3.14 | Only needed when self-hosting registry; no restriction when using hosted version https://treg.to |
| Platform | Cross-platform | "Operating System :: OS Independent" declared in pyproject.toml |
| Native Modules | None | dsh/ directory only uses node:fs/promises, node:url, cordis API |

## Installation
```bash
dsh plugin --profile web add github:superdesigndev/treg
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `TREG_TOKEN` | Environment Variable | treg account token; copy after logging in at https://treg.to. Set and restart dsh to enable MCP connector | Not set (empty) |
| When `TREG_TOKEN` is missing | Behavior | MCP row auto-disables, 5 mcp__treg__* tools won't appear; SKILL.md still loads and guides user to get token | — |

## FAQ
**Q: What happens without TREG_TOKEN?**

A: MCP connector row (treg-mcp) auto-disables, 5 `mcp__treg__*` tools won't appear in the agent; but SKILL.md still loads and guides user to register at treg.to to get token, profile won't crash due to missing token.

**Q: Where do I get TREG_TOKEN?**

A: Copy from account page after logging in at https://treg.to via GitHub / Google / email OTP; new teams get $1.00 free credit.

**Q: Do I need to register separate accounts and apply for keys for each third-party API?**

A: No. treg uses its own key to call upstream and deducts from team prepaid balance per call; keys already registered by other team members take priority and are not metered.

**Q: Will the caller get the third-party API key?**

A: No. treg proxy is "faithful forwarding": only modifies hop-by-hop headers, its own control headers, and injected credentials, all other bytes forwarded as-is; `X-Treg-Token` is stripped before reaching upstream.

**Q: What to do with HTTP 402?**

A: Indicates insufficient team prepaid balance. Caller should check `mcp__treg__balance` / `treg balance` and prompt user to top up at https://reg.to, or have the team register their own key for that provider.

**Q: Why does a duplicate SKILL.md appear under ~/.agents/skills/treg/?**

A: treg's `install.sh` runs `treg skill bootstrap` to write SKILL.md to `~/.agents/skills/treg/`, duplicating the version bundled with this bundle, but content is identical and harmless.

**Q: How to completely uninstall from dsh?**

A: Just remove the `treg-dsh` bundle from your dsh profile's plugin list; no need to clean up environment variables (`TREG_TOKEN` belongs to treg service itself, not dsh).

**Q: If a third-party API upgrades, does treg need to change?**

A: No. treg proxy doesn't parse upstream body or cache models, forwards requests and responses as-is, so upstream API changes are transparent to treg.

## Difficulty Level
Advanced — DSH host needs to support cordis patch protocol, user must first register at treg.to and copy token, then export to dsh's environment variables and restart; SKILL.md documentation is lengthy (~260 lines), agent needs guidance to read through on first call.

## Known Issues & Limitations
- MCP connector unavailable when `TREG_TOKEN` is missing; user must manually set and restart dsh to enable (`dsh/cordis.patch.yml:26-28`)
- `treg install.sh` installs SKILL.md redundantly to `~/.agents/skills/treg/`, coexisting with the bundled version in this bundle, identical content, harmless but redundant (`dsh/skills/treg/SKILL.md:39-41`)
- When self-hosting treg registry: `treg run --server` doesn't yet provide filesystem/network-level isolation, currently only rlimits + command whitelist (`SECURITY.md:36-41`)
- When self-hosting: CLI-login handshake state saved in server process, multi-instance deployment requires sticky session (`SECURITY.md:42-44`)
- Catalog endpoints without public quotes are refused, need to register own key for that provider; treg won't automatically select provider or failover (`README.md:103-108`)

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [treg](https://deepseek-plugin.org/plugins/superdesigndev/treg)
Wiki generated by AI (model: `MiniMax-M2.5`)