treg

npx add-mcp 'https://treg.to/mcp/v2/'

Treg (OpenRouter para ferramentas)

OpenRouter, mas para ferramentas de agentes em vez de modelos. Aponte um agente para uma única URL base com um único token e ele poderá fazer o trabalho: um catálogo selecionado com milhares de endpoints de muitos provedores — SEO e backlinks, redes sociais e tendências, enriquecimento de pessoas e empresas, anúncios, scraping, geração de imagens e vídeos — com preço por chamada, a partir de um centavo, sem precisar criar conta em provedores. Além disso, as chaves, habilidades e CLIs da sua própria equipe, acessíveis pelo agente de cada colega sem que as credenciais jamais saiam do servidor.

Peça a tarefa, não a ferramenta. Você não precisa saber qual fornecedor vende dados de backlinks nem ter uma conta com ele. Pesquise o que quer fazer, consulte o preço e chame a ferramenta.

Criado para a equipe Superdesign, disponível em treg.to — qualquer pessoa pode hospedar por conta própria.

Por que existe

As ferramentas de que um agente precisa para trabalhar de verdade ficam atrás de assinaturas que ninguém contrata para uma única execução — Semrush por $139/mês, Moz por $99/mês, Crunchbase por $99/mês, Apollo por $59/assento —, atrás de barreiras de cadastro ou sem nenhuma API pública (acesso somente por convite, para parceiros ou após análise do aplicativo). O treg mantém essas contas e cobra frações de centavo por chamada.

Dois tipos de ferramenta, um token

• O catálogo — endpoints externos que o treg pode disponibilizar com sua própria chave ou por uma rota pública verificada que não exige chave do provedor. Chamadas com chave própria usam o saldo pré-pago da equipe; chamadas anônimas são gratuitas. Não é preciso ter conta com o provedor. Novas contas verificadas recebem $1.00 grátis uma vez, ao criar uma equipe elegível.
• Suas próprias ferramentas — qualquer coisa registrada por um colega: uma conta de API paga, uma conexão OAuth, uma CLI de fornecedor, um SKILL.md. Sua própria chave sempre tem prioridade sobre a do treg, e essas chamadas nunca são contabilizadas.

O vocabulário da segunda parte:

• ferramenta = algo que o registro chama por você usando a credencial da organização. Há dois tipos:
  • endpoint — um base_url upstream + vínculos de credenciais (cada vínculo injeta um segredo na solicitação; uma solicitação pode incluir vários, por exemplo, um bearer OAuth e um cabeçalho developer-token).
  • CLI — um binário de fornecedor (stripe, gh, vercel, ...) executado com a credencial injetada.
• skill / bundle = uma receita (SKILL.md) + seus segredos + sua(s) ferramenta(s), registrados em conjunto.

A única regra: o proxy retransmite, nunca modela o upstream e injeta a autenticação no servidor — assim, continua funcionando mesmo quando a API upstream muda, e quem faz as chamadas nunca fica com as chaves.

---

Parte 1 · Usar o registro

Acesse treg.to (hospedado no Render) — o painel, o login e todas as URLs abaixo ficam lá.

Início rápido

O mesmo fluxo do guia Primeiros passos do painel:

# 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)

O Fish Audio oferece fala com S2.1 Pro, descoberta de vozes públicas e clonagem de vozes privadas. A fala é enviada como saída binária, então redirecione-a para um arquivo. O _id de uma voz descoberta ou o ID de uma voz da equipe é o reference_id de TTS; as vozes criadas na conta Fish do treg são recursos permanentes da equipe:

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

Com sua própria chave Fish, as solicitações continuam sendo uma retransmissão upstream irrestrita e sem contabilização, e o Fish mantém o controle da conta.

As entradas das ferramentas do catálogo são descritas por treg catalog get <id>. Ferramentas marcadas como strict_query rejeitam parâmetros de consulta não declarados ou repetidos, valores sem suporte e corpos de solicitação.

Seu token identifica você em cada chamada (cabeçalho X-Treg-Token) e é o mesmo para todas as ferramentas. Descubra o que sua equipe compartilhou: treg tool ls · verifique a integridade das credenciais: treg health.

Ou instale como plugin do Claude Code

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

Instala a skill do treg e as ferramentas do treg sem token nem configuração. Execute /mcp, escolha treg e faça login; as ferramentas aparecerão em seguida. Para outros agentes: npx skills add superdesigndev/treg -s treg (ou consulte Workflow skills para ver as demais). Consulte docs/CLAUDE-PLUGIN.md. Para usuários do MiniMax Code / MiniMax Agent: a mesma skill está disponível no MiniMax Plugin Marketplace (docs/MINIMAX-PLUGIN.md).

Workflow skills

Receitas prontas que seu agente executa de ponta a ponta, com todas as chamadas passando pelo treg:

Skill	O que seu agente pode fazer
treg	Encontrar e chamar qualquer ferramenta do catálogo, além das suas próprias ferramentas
web-access	Quando as ferramentas web do próprio agente não forem suficientes, consultar a web em tempo real sem scrapers locais: primeiro, pesquisa e leitura de páginas gratuitas; depois, o trabalho de plataforma adequado para redes sociais, lojas, avaliações, mapas e artigos acadêmicos, com o treg recorrendo ao próximo fornecedor quando um deles falhar
lead-signals	Encontrar compradores em fase de decisão a partir de sinais públicos (reclamações, mudanças de emprego, contratações, financiamento, adoção de ferramentas) e monitorar um tópico, concorrente ou lista de contas em busca deles (treg.to/leads-signals)
recruit	Transformar uma vaga do LinkedIn em uma lista de candidatos ordenada: critérios extraídos da vaga, busca de pessoas, filtros com justificativas, uma frase sobre por que cada pessoa se encaixa, evidências citadas (publicações, GitHub, palestras, tempo de experiência, mudança de emprego) dentro de um limite de gastos por candidato e, em seguida, e-mail pessoal e telefone verificados, com um arquivo da execução contendo contagens, evidências e o histórico de fornecedores por candidato
make-ugc	Criar vídeos UGC com IA: ganchos em alta, apresentador, clipes de pessoas falando para a câmera e legendas (treg.to/ugc)
jev-memory	Dar memória ao Claude Code: um mod do Claude Code em que Jev avalia cada prompt após a resposta e mantém suas preferências duradouras, instalado pronto para uso ou criado a partir de um único prompt (o mod)

install.sh instala apenas treg e menciona as outras em uma linha; seu agente as oferece após o login e a primeira chamada. Indique as que você quer com sh -s -- --skills lead-signals,recruit (ou --skills all; as opções de adesão jev-memory e rea-growth nunca fazem parte desse conjunto). No Claude Code, cada uma também é um plugin próprio no marketplace do treg: /plugin install recruit@treg, ou escolha-as em /plugin. Para adicioná-las a um agente existente (skills.sh CLI):

npx skills add superdesigndev/treg                        # every public skill
npx skills add superdesigndev/treg --skill lead-signals   # just one
treg skill bootstrap --skills all                         # the installer's set, with the treg CLI you already have

As workflow skills são executadas no treg, então configure-o primeiro (com o Início rápido acima ou apontando seu agente para treg.to/llms.txt).

Conector do Claude.ai

A interface do Claude Connectors Directory é https://treg.to/mcp/v2/. Ela expõe apenas endpoints selecionados do catálogo, sem geração de imagens, vídeos ou áudio, e separa chamadas de leitura das chamadas de gravação para que o Claude receba sinais de segurança precisos. A interface existente /mcp/ continua disponível para endpoints do catálogo, ferramentas da equipe e skills importadas. Consulte a arquitetura de MCP e OAuth para entender os limites e a implementação, e o guia de lançamento para conhecer os critérios de liberação.

Chame uma ferramenta para a qual você não tem chave

O catálogo é organizado pelo que os endpoints fazem: acompanhamento de palavras-chave e posições, backlinks e autoridade, visibilidade em IA, tendências e descoberta, publicação em redes sociais, enriquecimento de pessoas e empresas, gerenciamento de anúncios e criativos, mensuração.

treg catalog                                    # every platform, busiest first
treg catalog search "find a work email"         # by the job, not the vendor
treg catalog search --new                       # tools added in the last 30 days, newest first
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"

Como uma chamada do catálogo é atendida — a hierarquia de credenciais, em ordem:

1. sua equipe registrou uma ferramenta própria para esse provedor → essa ferramenta, essa chave;
2. sua equipe armazenou um segredo para o provedor → injetado por meio de uma ferramenta virtual;
3. nenhum dos dois, e o endpoint tem uma rota pública verificada → sem chave do provedor, grátis;
4. caso contrário → chave própria do treg, cobrada do saldo pré-pago da equipe.

O preço para chamadas anônimas pressupõe que quem chama não envie um cabeçalho de credencial do provedor. A retransmissão fiel preserva os cabeçalhos enviados por quem chama, então uma chave de provedor fornecida por ele pode usar os créditos dessa chave. Sua própria credencial sempre tem prioridade sobre a do treg; portanto, conectar uma chave pela qual você já paga torna essas chamadas gratuitas em relação ao saldo, em vez de cobrar duas vezes. Um endpoint para o qual o treg não publicou um preço é recusado, não disponibilizado gratuitamente — você será informado de que deve conectar sua própria chave. Quando vários provedores oferecem a mesma capacidade, treg catalog search os mostra lado a lado com os preços; a escolha é sua — o treg não escolhe nem alterna silenciosamente entre provedores por você. (Quando a própria conta do treg em um provedor estiver sem saldo, ele poderá disponibilizar o mesmo endpoint por meio de uma conta de retransmissão do treg, informada na resposta; uma equipe pode desativar essa opção.) A exceção que você pode escolher: endpoints roteados treg.<capability>, nos quais o treg escolhe o provedor por você e informa qual foi. Para tarefas comuns (raspar uma página, pesquisar na web, obter resultados do Google, encontrar um e-mail), comece pelo endpoint roteado, como treg.web.extract ou treg.web.search, em vez de escolher um provedor cujo nome você conhece. Em treg.people.email.find e treg.people.phone.find, X-Treg-Route-Verify: true também verifica o endereço ou número encontrado na mesma chamada, com cobrança própria, e informa o resultado da verificação.

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

Saldo insuficiente gera um HTTP 402 error: insufficient_balance contendo balance_micro, estimated_cost_micro e um topup_url, para que um agente possa agir sem precisar interpretar texto explicativo.

Enrich Arena fica em /enrich-arena, fora do painel. Compare respostas de enriquecimento com o custo e a velocidade de cada fornecedor, vote na melhor resposta com um clique ou acompanhe uma cascata sequencial. Provedores assíncronos compatíveis com a capacidade também participam; o Arena gerencia o envio e a consulta de resultados internamente. A navegação é pública; para enviar solicitações, é preciso fazer login, e as tentativas cobradas usam os créditos da sua equipe. Consulte o guia do Arena.

Web Arena compara provedores de Web Search, Web Fetch e Sitemap em /web-arena. As chamadas de Batalha selecionam provedores para a mesma entrada; a Cascata tenta cada um em ordem. O placar ao vivo combina taxas de sucesso e tempos de resposta de chamadas diretas aos provedores com resultados de qualidade verificados do Web Arena em uma janela móvel de 30 dias. As páginas ficam disponíveis quando o recurso está ativado. Consulte o guia do Web Arena.

Compartilhe e use suas próprias ferramentas

O caminho que exige menos esforço — aponte o treg para um projeto e ele identifica o que pode ser compartilhado:

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 examina o .env (comparando chaves com cerca de 80 provedores conhecidos), cada subdiretório de skills e as CLIs de catálogo instaladas. Três tipos de itens podem ser adicionados ao registro — veja como compartilhar e usar cada um:

1. Endpoints (APIs HTTP)

Compartilhar — uma URL upstream que pode ser chamada com uma chave armazenada, ou em lote a partir de um .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

Usar — a forma nativa para agentes: crie a solicitação upstream real e acrescente o proxy no início. O treg identifica a ferramenta pelo host, injeta a credencial e retransmite fielmente todo o restante (seu X-Treg-Token é removido antes que a solicitação chegue ao upstream):

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>

Ou use a forma abreviada da CLI — e treg calls para o registro de auditoria:

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

2. CLIs

Compartilhar — automático: treg upload detecta CLIs de catálogo instaladas (stripe, gh, vercel, …) e as registra; uma skill de CLI do catálogo que contenha apenas uma receita (por exemplo, stripe-cli) também passa a ser executável automaticamente.

Usar — treg run executa a CLI do fornecedor com a credencial da organização injetada, para que você nunca precise guardar a chave nem fazer login:

treg run stripe -- get /v1/balance
treg run gh -- pr list

--local (padrão) é executado na sua máquina. A execução de CLI no servidor (--server) está desativada globalmente. treg runs é o registro de auditoria.

3. Skills

Compartilhar — uma skill é uma capacidade completa (receita SKILL.md + seus segredos + sua(s) ferramenta(s)), registrada em conjunto para que toda a equipe use a mesma skill, mantida em um só lugar:

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

Usar — importe qualquer skill compartilhada para seu agente; as chamadas de API passam pelo treg com seu token, para que a chave permaneça no servidor, nunca na skill:

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

Registro manual — quando as heurísticas não conseguem identificar uma ferramenta

# 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

Veja as opções completas de cada comando: USAGE.md.

A CLI e seu instalador enviam dados de uso anônimos ao PostHog quando usam treg.to (sem argumentos nem credenciais). Desative com TREG_TELEMETRY=0 ou DO_NOT_TRACK=1. Consulte detalhes de análise.

Equipes

Uma conta pode ter até 10 equipes. Participar de outras equipes como membro não conta para esse limite.

Tudo tem escopo de uma org: um token = uma associação (user, org), e cada segredo, ferramenta e skill pertence à org ativa. Funções: 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>                          # accept an invite (sign in as the invited email first)
treg org ls | use <slug> | members            # switch orgs, see the roster
treg org access <member> --tools a,b          # per-member tool access (admin+)

Os proprietários de equipes podem ativar o SSO empresarial na guia Team → SSO do painel. O WorkOS conecta o provedor de identidade da empresa; os proprietários podem convidar o administrador de TI para concluir a configuração. Os funcionários podem inserir seu e-mail corporativo em qualquer diálogo de login ou usar o link direto de login da equipe. treg mantém as funções da equipe e as chaves de API. O plano Directory Sync remove o acesso à equipe de um funcionário desativado. Consulte configuração do SSO empresarial.

Aprofunde-se

• Feedback: treg feedback submit friction "The pagination example is unclear." Compartilhe problemas ou sugestões sem informações privadas. Consulte instruções de feedback.

• Avaliação: treg review CALL_ID useful Avalie uma chamada do catálogo convidada após usar o resultado; not_sure está ótimo. Não inclua dados privados e continue a tarefa.

• USAGE.md — a referência completa da CLI treg.

• /llms.txt: o ponto de entrada do agente, no formato llms.txt : o que é treg, configuração para cada tipo de agente, o ciclo de busca-leitura-chamada e as regras, com links para /skill.md, o guia operacional, para todo o restante.

• O painel em treg.to — CRUD completo, um tutorial guiado (Help → Tutorial) e instruções de configuração copiáveis para seus agentes.

• A API — tudo o que a CLI faz é HTTP simples; a documentação interativa do OpenAPI está em /docs. O endpoint de proxy é /call/{...}; todos os endpoints exigem o cabeçalho X-Treg-Token.

---

Parte 2 · Auto-hospedagem e desenvolvimento

Execute localmente

Um comando (requer tmux + uv; ele sincroniza o venv automaticamente):

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

Isso executa o servidor no tmux com recarga automática, seu próprio banco de dados sqlite (treg-dev.db) e modo de desenvolvimento com OTP por e-mail (códigos de login exibidos na página — não é necessário um remetente de e-mail). No dia a dia:

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

Ou execute o servidor diretamente, sem tmux:

bash scripts/build-dashboard.sh # Node 22.12+ and npm; build the Dashboard
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

Instalação para executar um servidor (não a partir do código-fonte): o pacote base contém somente a CLI. Para executar um registro, instale o extra do servidor — pip install "tools-registry[server]" — que adiciona FastAPI, os drivers de banco de dados e criptografia. pip install tools-registry sozinho fornece apenas o comando treg para se comunicar com um registro existente.

O serviço oficial hospedado está disponível em treg.to. A topologia de produção e as configurações ativas são mantidas no manual privado do operador.

Configuração

Variáveis de ambiente (prefixo TREG_, lidas de .env):

Var	Padrão	Finalidade
TREG_DATABASE_URL	sqlite+aiosqlite:///./treg.db	URL do banco de dados (SQLite para desenvolvimento, Postgres em produção)
TREG_READ_DATABASE_URL	(vazio)	Fonte de dados opcional de leitura SQLite / PostgreSQL; vazia, reutiliza a principal. Requer adesão explícita dos chamadores; as consultas existentes não são alteradas. Consulte configuração da fonte de dados de leitura.
TREG_SECRET_KEY	(vazio)	Chave Fernet para segredos em repouso; vazia → uma chave efêmera é gerada (os segredos não sobreviverão a uma reinicialização)
TREG_PUBLIC_URL	https://treg.to	URL pública base do treg, usada para criar o URI de retorno de chamada OAuth
TREG_SESSION_SECRET	(vazio)	assina o cookie de sessão do painel; usa TREG_SECRET_KEY como alternativa. Defina um valor real em produção
TREG_GITHUB_CLIENT_ID / _SECRET	(vazio)	Login OAuth do GitHub (retorno de chamada <public_url>/auth/github/callback); vazio oculta o botão
TREG_GOOGLE_CLIENT_ID / _SECRET	(vazio)	Login OAuth do Google (redirecionamento <public_url>/auth/google/callback); vazio oculta o botão
TREG_WORKOS_API_KEY / _CLIENT_ID / _WEBHOOK_SECRET	(vazio)	SSO empresarial do WorkOS; configure o retorno de chamada e o webhook de diretório assinado conforme descrito em configuração do SSO empresarial
TREG_ENTERPRISE_SSO_BUNDLE_ONLY	true	Mostrar apenas o plano SSO + Directory Sync por padrão; defina como false para oferecer os dois planos mensais.
TREG_ENTERPRISE_SSO_BUNDLE_PRICE_ID / TREG_ENTERPRISE_SSO_ONLY_PRICE_ID	(vazio)	IDs de preços mensais reutilizáveis do Stripe na mesma conta que TREG_STRIPE_SECRET_KEY; um preço não definido ou inutilizável oculta seu plano. O preço do Stripe fornece o valor exibido e a cobrança do Checkout.
TREG_ENTERPRISE_SSO_BUNDLE_MIN_PRICE_USD / TREG_ENTERPRISE_SSO_ONLY_MIN_PRICE_USD	0	Mínimo opcional em dólares inteiros para cada preço mensal do Stripe; preços inferiores são ocultados e rejeitados no Checkout.
TREG_INSTAGRAM_CLIENT_ID / _SECRET	(vazio)	ID e segredo do app do Instagram para Login direto do Instagram (redirecionamento <public_url>/oauth/callback)
TREG_META_CLIENT_ID / _SECRET	(vazio)	Credenciais do app Meta para Facebook Pages, Meta Ads e Instagram opcional page-tools
TREG_OAUTH_REVIEW_PENDING	instagram-login,page-messages	Chaves de avaliação do registro, separadas por vírgulas, cujas capacidades devem permanecer restritas; o estado de avaliação hospedado é mantido em privado.
TREG_RESEND_API_KEY / TREG_EMAIL_FROM	(vazio)	e-mail transacional via Resend (códigos OTP + convites); o remetente deve ser verificado pelo Resend
TREG_BLOCKED_EMAIL_DOMAINS	(vazio)	domínios de e-mail separados por vírgulas que são recusados em todas as etapas de cadastro/login e na criação de equipes (inclui subdomínios, sem distinção entre maiúsculas e minúsculas). Vazio não bloqueia nada — nenhum domínio é incluído no código
TREG_CLIENT_IP_HEADER	(vazio)	um cabeçalho que somente sua borda pode definir, usado como endereço do cliente para cada limite por IP (cf-connecting-ip atrás do Cloudflare)
TREG_TRUSTED_PROXY_HOPS	1	sem esse cabeçalho: a entrada X-Forwarded-For a esta quantidade de saltos a partir da DIREITA (a que seu proxy mais próximo adicionou); 0 quando os clientes se conectam diretamente. A primeira entrada é definida pelo cliente e nunca é confiável
TREG_REQUIRED_EXTENSIONS	(vazio)	extensões de política separadas por vírgulas (pontos de entrada treg.extensions) que devem estar instaladas; caso contrário, a inicialização falha. treg.to executa uma extensão privada de política contra abuso dessa forma; ela só pode restringir (extensões de política)
TREG_TURNSTILE_SITE_KEY / _SECRET	(vazio)	Cloudflare Turnstile em todos os formulários de login por e-mail e no primeiro login de um novo endereço via GitHub/Google; qualquer um vazio = desativado. A chave do site é fornecida em /captcha.js, o segredo só chega ao siteverify
TREG_TURNSTILE_MODE	observe	observe registra cada resultado e não altera nada; enforce recusa um código para um token ausente ou inválido, não concede crédito de cadastro quando o Cloudflare não responde e só concede crédito de cadastro a um novo usuário do GitHub/Google após uma verificação aprovada
TREG_TURNSTILE_SOCIAL	true	false ignora a verificação no primeiro login de um novo endereço via GitHub/Google, que então recebe crédito de cadastro como se não houvesse widget; a etapa de e-mail não é alterada
TREG_TURNSTILE_HOSTNAMES	(vazio)	hosts separados por vírgulas nos quais um token deve ser resolvido; vazio = o host TREG_PUBLIC_URL (e seus aliases conhecidos)
TREG_ADMIN_TOKEN	(vazio)	bearer super-admin entre locatários; autoriza todos os endpoints /admin/*. Vazio desativa o caminho de ambiente (somente usuários is_superadmin acessam /admin). Mantenha-o longo e secreto.
TREG_EMAIL_DEV_MODE	false	quando verdadeiro, /auth/email/start retorna o OTP na resposta (não é necessário um remetente de e-mail) — somente desenvolvimento/local, nunca em produção.
TREG_KV_URL	(vazio)	armazenamento compartilhado de chave-valor (protocolo Redis) para contadores que todos os workers precisam compartilhar; atualmente, o limite de convites para avaliação por equipe. Vazio = alternativa em processo, adequada para um único worker

Nenhum .env é necessário para desenvolvimento local — todas as configurações têm um padrão funcional (chave efêmera, sqlite).

⚠️ Faça backup antes de mover ou reimplantar: a chave Fernet (TREG_SECRET_KEY) e o banco de dados (Postgres em produção; treg.db para uma execução local com sqlite). Se perder a chave Fernet, todos os segredos armazenados ficarão irrecuperáveis.

Arquitetura

Fluxo de solicitação para /call: resolver a ferramenta (pelo host da URL + o prefixo base_url mais longo, ou pelo nome) → descriptografar seus segredos → aplicar o injetor de cada vínculo → transmitir ao upstream → disparar registro de auditoria sem aguardar. O relay de infraestrutura transmite bytes sem lógica de negócio. A aplicação de chamada armazena em buffer as respostas que exigem liquidação ou evidência de propriedade, até 8 MiB; respostas maiores retornam um 502 sem cobrança, em vez de um sucesso truncado. Endpoints que incluem mídia (imagens do Gemini) declaram spooled_response: a resposta tarifada é lida em um arquivo temporário, liquidada com base no uso informado e retransmitida por inteiro. Downloads finais gratuitos autorizados que não exigem evidência do corpo são transmitidos integralmente, assim como respostas com chave própria e ferramenta própria.

Mapa de módulos (src/treg/):

Módulo	Função
proxy.py	relay() — o produto inteiro em uma função: um proxy de streaming fiel
injectors.py	a interface de autenticação: env, cli_auth, secret_file, oauth inserem um segredo em um cabeçalho/parâmetro de consulta
oauth.py	atualização de tokens (atualização single-flight) + fluxo de conexão (URL de consentimento, troca de código)
health.py	integridade das credenciais: atualizar OAuth, sondar ferramentas, enviar webhook ao responsável por qualquer problema
convert.py	criar um diretório de skill em um manifesto de pacote registrável
api.py	a API — o único cérebro; CLI + skill são clientes leves sobre ela
cli.py	a CLI treg
models.py	tabelas SQLModel: Org, User, Membership, Invite, Secret, Tool, Bundle, PendingOAuth, CallRecord
crypto.py config.py db.py audit.py	criptografia Fernet + tokens · configurações · banco de dados assíncrono · gravador de auditoria adiado

Os 4 formatos de autenticação (por binding injector): env (string simples / chave de API) · secret_file (um arquivo de token JSON, extrai um campo) · oauth (um token OAuth JSON, atualizado automaticamente se puder ser atualizado) · cli_auth (material extraído do chaveiro de uma CLI).

Contrato de retransmissão fiel: o proxy altera apenas três coisas; todo o resto é transmitido sem alterações:

1. cabeçalhos de transporte hop-by-hop (recalculados a cada salto),
2. os cabeçalhos de controle e encaminhamento de borda do próprio treg (x-treg-token, x-treg-org, ngrok-skip-browser-warning, x-forwarded-*, via, …) e o cookie de sessão do treg — todos removidos, nunca vazam para o upstream,
3. as credenciais injetadas.

OAuth, três formas de obter o primeiro token: envio manual (adicione um token.json) · atualização automática (se o token contiver refresh_token + credenciais do cliente, o treg o mantém atualizado, sem que você precise enviá-lo novamente) · fluxo de conexão hospedado (treg oauth connect → consentimento no navegador → o treg captura o token).

Verificações de integridade: atribua uma sondagem opcional a uma ferramenta ({method, path, expect_status}); uma execução periódica (sob demanda ou via cron) valida cada credencial, atualiza o OAuth e envia um webhook ao responsável por qualquer credencial que apresente problemas.

O design detalhado está em docs/context/ (fragmentos por subsistema).

Testes

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

Cobertura: estrutura básica do proxy, todos os formatos de injetor, autenticação por usuário + CRUD + auditoria, compositor de skills, encaminhamento de URL + retransmissão fiel, atualização OAuth + fluxo de conexão, verificações de integridade, treg run/shell, envio/varredura, organizações + convites, API do painel, CLI.

Contribuições e documentação

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
├── USAGE.md             # full treg CLI reference
└── pyproject.toml

Os documentos de design por subsistema são fragmentos em docs/context/, cada um citando suas fontes src/treg/*. Trabalhando neste repositório com um agente de IA? A skill /tools-registry-context carrega o fragmento adequado ao que você está alterando e mantém a documentação sincronizada — execute /tools-registry-context sync antes de enviar as alterações.

Roteiro: suporte a MCP · níveis de permissão mais granulares · reforço do gerenciamento de chaves em repouso · possível fusão com Loopni.

Licença

Apache 2.0 com termos adicionais (LICENSE): use livremente — inclusive comercialmente, dentro da sua própria organização (recomendamos hospedar seu próprio registro). A restrição: não redistribua o código a terceiros como um serviço concorrente de registro hospedado/gerenciado sem autorização por escrito (jason@superdesign.dev). É permitido usar a API hospedada treg.to no seu próprio produto — com cobrança repassada via X-Treg-Meta e usage/by-tag — sem autorização; isso é chamar nossa API, não redistribuir nosso software.

Escopos de leitura fixados para clientes

Para um agente de cliente restrito, treg org agent-new bot --pin customer=cust_A impõe a atribuição e limita o histórico de chamadas/execuções, os resultados arquivados e a propriedade assíncrona de provedores compartilhados a esse pin. IDs externos ou sem atribuição retornam 404; um operador sem pin mantém a visualização de toda a organização e o saldo compartilhado. O acesso a contas BYOK e as URLs públicas de mídia mantêm as permissões existentes. Consulte o contrato de multilocação para vários pins, migração e comportamento de reprodução.