treg

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

Treg (OpenRouter cho công cụ của tác tử)

OpenRouter, nhưng dành cho công cụ của tác tử thay vì mô hình. Trỏ tác tử đến một URL cơ sở duy nhất với một token là đủ để tác tử hoàn thành công việc: danh mục được tuyển chọn gồm hàng nghìn endpoint từ nhiều nhà cung cấp — SEO và backlink, mạng xã hội và xu hướng, bổ sung dữ liệu về cá nhân và công ty, quảng cáo, thu thập dữ liệu, tạo hình ảnh và video — tính phí theo mỗi lần gọi, từ một xu, không cần đăng ký với nhà cung cấp. Ngoài ra còn có khóa, kỹ năng và CLI của chính nhóm bạn, để tác tử của mọi thành viên trong nhóm đều có thể gọi mà thông tin xác thực không bao giờ rời khỏi máy chủ.

Yêu cầu công việc, không phải công cụ. Bạn không cần biết nhà cung cấp nào bán dữ liệu backlink, cũng không cần có tài khoản với họ. Tìm kiếm việc bạn muốn làm, xem giá rồi gọi công cụ.

Được xây dựng cho nhóm Superdesign, hiện hoạt động tại treg.to — bất kỳ ai cũng có thể tự lưu trữ.

Vì sao có treg

Các công cụ mà tác tử cần để làm việc thực tế thường nằm sau những gói đăng ký không ai mua chỉ để chạy một lần — Semrush $139/tháng, Moz $99/tháng, Crunchbase $99/tháng, Apollo $59/chỗ ngồi — sau các trang yêu cầu đăng ký, hoặc sau những API công khai không tồn tại (chỉ dành cho người được mời, đối tác hoặc được duyệt ứng dụng). treg duy trì các tài khoản đó và tính phí theo phần nhỏ của một xu cho mỗi lần gọi.

Hai loại công cụ, một token

• Danh mục — các endpoint bên ngoài mà treg có thể cung cấp bằng khóa riêng hoặc qua một tuyến công khai đã xác minh, không cần khóa nhà cung cấp. Các lần gọi bằng khóa riêng dùng số dư trả trước của nhóm; các lần gọi ẩn danh miễn phí. Không cần tài khoản với nhà cung cấp. Tài khoản mới được xác minh sẽ nhận $1.00 miễn phí một lần khi tạo nhóm đủ điều kiện.
• Công cụ của bạn — bất cứ thứ gì thành viên trong nhóm đăng ký: tài khoản API trả phí, kết nối OAuth, CLI của nhà cung cấp, SKILL.md. Khóa của bạn luôn được ưu tiên hơn khóa của treg, và các lần gọi đó không bao giờ bị tính phí.

Thuật ngữ dùng cho phần thứ hai:

• tool = thứ mà registry gọi thay bạn bằng thông tin xác thực của tổ chức. Có hai loại:
  • endpoint — một base_url upstream + các binding thông tin xác thực (mỗi binding chèn một bí mật vào yêu cầu; một yêu cầu có thể mang nhiều bí mật, ví dụ như bearer OAuth và một header developer-token).
  • CLI — một tệp nhị phân của nhà cung cấp (stripe, gh, vercel, ...) được chạy với thông tin xác thực đã chèn.
• skill / bundle = một công thức (SKILL.md) + các bí mật của nó + (các) công cụ của nó, được đăng ký cùng nhau.

Quy tắc duy nhất: proxy chuyển tiếp, không mô phỏng upstream và chèn xác thực ở phía máy chủ — nhờ vậy proxy vẫn hoạt động khi API upstream thay đổi, còn bên gọi không bao giờ phải giữ khóa.

---

Phần 1 · Sử dụng registry

Truy cập treg.to (được lưu trữ trên Render) — trang tổng quan, đăng nhập và mọi URL bên dưới đều nằm tại đó.

Bắt đầu nhanh

Quy trình giống với hướng dẫn Bắt đầu trên trang tổng quan:

# 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 cung cấp giọng nói S2.1 Pro, khả năng khám phá giọng nói công khai và nhân bản giọng nói riêng tư. Đầu ra giọng nói là dữ liệu nhị phân trên stdout, vì vậy hãy chuyển hướng nó vào một tệp. _id của giọng nói đã tìm thấy hoặc ID giọng nói của nhóm là reference_id cho TTS; giọng nói được tạo trên tài khoản Fish của treg là tài nguyên lâu dài của nhóm:

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

Với khóa Fish của riêng bạn, các yêu cầu vẫn được chuyển tiếp upstream không giới hạn và không tính phí, còn Fish quản lý ranh giới tài khoản.

Đầu vào của công cụ trong danh mục được mô tả bằng treg catalog get <id>. Các công cụ được đánh dấu strict_query sẽ từ chối tham số truy vấn chưa khai báo hoặc bị lặp, giá trị không được hỗ trợ và nội dung yêu cầu.

Token của bạn xác định danh tính của bạn trong mọi lần gọi (header X-Treg-Token) và dùng chung cho tất cả công cụ. Khám phá nội dung nhóm đã chia sẻ: treg tool ls · kiểm tra tình trạng thông tin xác thực: treg health.

Hoặc cài đặt dưới dạng plugin Claude Code

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

Cài đặt kỹ năng treg và các công cụ của treg mà không cần token hay cấu hình. Chạy /mcp, chọn treg rồi đăng nhập; các công cụ sẽ xuất hiện sau đó. Với các tác tử khác: npx skills add superdesigndev/treg -s treg (hoặc xem Kỹ năng quy trình làm việc để biết các lựa chọn còn lại). Xem docs/CLAUDE-PLUGIN.md. Người dùng MiniMax Code / MiniMax Agent: kỹ năng tương tự cũng có trên MiniMax Plugin Marketplace (docs/MINIMAX-PLUGIN.md).

Kỹ năng quy trình làm việc

Các công thức có sẵn để tác tử chạy từ đầu đến cuối, mọi lần gọi đều qua treg:

Kỹ năng	Tác tử của bạn có thể làm gì
treg	Tìm và gọi bất kỳ công cụ nào trong danh mục, cùng với công cụ của riêng bạn
web-access	Khi các công cụ web của tác tử không đáp ứng đủ nhu cầu, đọc web trực tiếp mà không cần trình thu thập dữ liệu cục bộ: trước tiên dùng tìm kiếm và đọc trang miễn phí, sau đó chọn tác vụ phù hợp cho mạng xã hội, cửa hàng, đánh giá, bản đồ và bài báo; treg sẽ chuyển sang nhà cung cấp tiếp theo nếu một nhà cung cấp gặp lỗi
lead-signals	Tìm người mua đang có nhu cầu từ các tín hiệu công khai (khiếu nại, thay đổi công việc, tuyển dụng, gọi vốn, sử dụng công cụ) và theo dõi chủ đề, đối thủ cạnh tranh hoặc danh sách tài khoản để tìm họ (treg.to/leads-signals)
recruit	Biến tin tuyển dụng trên LinkedIn thành danh sách rút gọn được xếp hạng: tiêu chí lấy từ tin tuyển dụng, tìm kiếm người, bộ lọc kèm lý do, một dòng giải thích mức độ phù hợp của từng người, bằng chứng có trích dẫn (bài đăng, GitHub, bài nói chuyện, thâm niên, thay đổi công việc) trong giới hạn chi phí cho mỗi ứng viên, sau đó là email cá nhân và số điện thoại đã xác minh, cùng tệp kết quả ghi số lượng, bằng chứng và lịch sử nhà cung cấp cho từng ứng viên
make-ugc	Tạo video UGC bằng AI: câu mở đầu thịnh hành, người dẫn, clip nói trực diện trước máy quay, phụ đề (treg.to/ugc)
jev-memory	Thêm bộ nhớ cho Claude Code: một bản sửa đổi Claude Code trong đó Jev đánh giá từng lời nhắc sau mỗi lượt và lưu lại các tùy chọn lâu dài của bạn; có thể cài sẵn hoặc tạo từ một lời nhắc (bản sửa đổi)

install.sh chỉ cài đặt treg và liệt kê các kỹ năng khác trong một dòng; tác tử sẽ đề xuất chúng sau khi đăng nhập và thực hiện lần gọi đầu tiên. Chỉ định những kỹ năng bạn muốn bằng sh -s -- --skills lead-signals,recruit (hoặc --skills all; các kỹ năng chọn tham gia jev-memory và rea-growth không bao giờ nằm trong nhóm đó). Trong Claude Code, mỗi kỹ năng cũng là một plugin riêng trong marketplace của treg: /plugin install recruit@treg, hoặc chọn chúng từ /plugin. Để thêm chúng vào một tác tử hiện có (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

Các kỹ năng quy trình làm việc chạy trên treg, vì vậy hãy thiết lập treg trước (theo phần Bắt đầu nhanh ở trên, hoặc trỏ tác tử đến treg.to/llms.txt).

Kết nối Claude.ai

Giao diện Claude Connectors Directory là https://treg.to/mcp/v2/. Giao diện này chỉ cung cấp các endpoint được tuyển chọn trong danh mục, không bao gồm tạo hình ảnh, video hoặc âm thanh, đồng thời tách riêng các lần gọi đọc và ghi để Claude nhận được tín hiệu an toàn chính xác. Giao diện /mcp/ hiện có vẫn dùng được cho các endpoint trong danh mục, công cụ do nhóm sở hữu và kỹ năng đã nhập. Xem Kiến trúc MCP và OAuth để biết ranh giới và cách triển khai, và sổ tay quy trình gửi để biết các điều kiện phát hành.

Gọi công cụ mà bạn không có khóa

Danh mục được nhóm theo chức năng của endpoint: theo dõi từ khóa và thứ hạng, backlink và độ uy tín, khả năng hiển thị trên AI, xu hướng và khám phá, đăng lên mạng xã hội, bổ sung dữ liệu về cá nhân và công ty, quản lý quảng cáo và nội dung sáng tạo, đo lường.

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"

Cách xử lý một lần gọi trong danh mục — thứ tự ưu tiên thông tin xác thực:

1. nhóm của bạn đã đăng ký công cụ riêng cho nhà cung cấp đó → dùng công cụ đó, khóa đó;
2. nhóm của bạn đã lưu bí mật cho nhà cung cấp → chèn bí mật qua công cụ ảo;
3. không có cả hai, nhưng endpoint có tuyến công khai đã xác minh → không cần khóa nhà cung cấp, miễn phí;
4. nếu không → dùng khóa riêng của treg, tính phí vào số dư trả trước của nhóm.

Giá ẩn danh giả định bên gọi không gửi header thông tin xác thực của nhà cung cấp. Cơ chế chuyển tiếp nguyên trạng giữ lại các header do bên gọi cung cấp, vì vậy khóa nhà cung cấp do bên gọi gửi có thể dùng số dư của khóa đó. Thông tin xác thực của bạn luôn được ưu tiên hơn của treg, vì vậy kết nối khóa mà bạn đã trả phí sẽ giúp các lần gọi đó không dùng số dư, thay vì tính phí trùng lặp. Nếu treg không có giá công bố cho một endpoint thì endpoint đó sẽ bị từ chối, chứ không được cung cấp miễn phí — bạn sẽ được yêu cầu kết nối khóa riêng. Khi nhiều nhà cung cấp cung cấp cùng một chức năng, treg catalog search hiển thị giá của họ cạnh nhau; bạn tự chọn — treg không âm thầm chọn nhà cung cấp hoặc tự chuyển sang nhà cung cấp khác thay bạn. (Khi tài khoản riêng của treg với một nhà cung cấp hết hạn mức, treg có thể cung cấp cùng endpoint đó qua tài khoản chuyển tiếp do treg sở hữu; việc này sẽ được thông báo trong phản hồi và nhóm có thể chọn không tham gia.) Ngoại lệ mà bạn có thể chọn tham gia: các endpoint định tuyến treg.<capability>, nơi treg chọn nhà cung cấp thay bạn và nêu rõ tên nhà cung cấp. Với các tác vụ phổ biến (thu thập dữ liệu trang, tìm kiếm web, kết quả Google, tìm email), hãy bắt đầu bằng endpoint định tuyến, chẳng hạn treg.web.extract hoặc treg.web.search, thay vì chọn một nhà cung cấp mà bạn nhớ tên. Trên treg.people.email.find và treg.people.phone.find, X-Treg-Route-Verify: true cũng xác minh địa chỉ hoặc số điện thoại tìm được trong cùng lần gọi, tính phí riêng và cho biết kết quả xác minh.

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

Hết số dư sẽ trả về HTTP 402 error: insufficient_balance chứa balance_micro, estimated_cost_micro và một topup_url, để tác tử có thể xử lý mà không cần đọc văn bản mô tả.

Enrich Arena có tại /enrich-arena, bên ngoài trang tổng quan. So sánh kết quả bổ sung dữ liệu theo chi phí và tốc độ của từng nhà cung cấp, bình chọn kết quả tốt nhất chỉ bằng một cú nhấp, hoặc theo dõi quy trình thác nước tuần tự. Các nhà cung cấp bất đồng bộ tương thích về chức năng cũng tham gia; Arena tự xử lý việc gửi yêu cầu và thăm dò trạng thái. Mọi người đều có thể xem; cần đăng nhập để gửi yêu cầu, và các lần thử có tính phí sẽ dùng tín dụng của nhóm. Xem hướng dẫn Arena.

Web Arena so sánh các nhà cung cấp Web Search, Web Fetch và Sitemap tại /web-arena. Chế độ Battle gọi các nhà cung cấp được chọn với cùng đầu vào; chế độ Waterfall thử lần lượt theo thứ tự. Bảng xếp hạng trực tiếp kết hợp tỷ lệ thành công và thời gian phản hồi từ các lần gọi trực tiếp đến nhà cung cấp với kết quả chất lượng đã kiểm tra của Web Arena trong khoảng thời gian 30 ngày gần nhất. Các trang sẽ mở khi tính năng được bật. Xem hướng dẫn Web Arena.

Chia sẻ và sử dụng công cụ của riêng bạn

Cách đơn giản nhất — trỏ treg đến một dự án để treg tự xác định những gì có thể chia sẻ:

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 quét .env (đối chiếu khóa với khoảng 80 nhà cung cấp đã biết), mọi thư mục con chứa kỹ năng và các CLI trong danh mục đã cài đặt. Có ba loại nội dung được đưa vào registry — dưới đây là cách chia sẻ và sử dụng từng loại:

1. Endpoint (API HTTP)

Chia sẻ — một URL upstream có thể gọi bằng khóa đã lưu, hoặc nhập hàng loạt từ một .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

Sử dụng — cách dành riêng cho tác tử: tạo yêu cầu upstream thực rồi thêm tiền tố proxy vào đó. treg xác định công cụ theo host, chèn thông tin xác thực và chuyển tiếp nguyên trạng mọi thứ khác (X-Treg-Token của bạn sẽ bị loại bỏ trước khi upstream nhận được yêu cầu):

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>

Hoặc dùng lệnh tắt CLI — và treg calls để xem nhật ký kiểm tra:

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

2. CLI

Chia sẻ — tự động: treg upload phát hiện các CLI trong danh mục đã cài đặt (stripe, gh, vercel, …) và đăng ký chúng; kỹ năng CLI trong danh mục chỉ chứa công thức (ví dụ: stripe-cli) cũng tự động trở thành công cụ có thể chạy.

Sử dụng — treg run thực thi CLI của nhà cung cấp với thông tin xác thực của tổ chức được chèn vào, vì vậy bạn không bao giờ phải giữ khóa hoặc đăng nhập:

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

--local (mặc định) chạy trên máy của bạn. Tính năng thực thi CLI phía máy chủ (--server) bị tắt trên toàn hệ thống. treg runs là nhật ký kiểm tra.

3. Kỹ năng

Chia sẻ — kỹ năng là một năng lực hoàn chỉnh (công thức SKILL.md + các bí mật của nó + (các) công cụ của nó), được đăng ký cùng nhau để cả nhóm dùng chung một kỹ năng và duy trì kỹ năng đó tại một nơi:

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

Sử dụng — đưa bất kỳ kỹ năng nào đã chia sẻ vào tác tử của bạn; các lệnh gọi API của kỹ năng sẽ đi qua treg bằng token của bạn, vì vậy khóa luôn ở trên máy chủ, không bao giờ nằm trong kỹ năng:

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

Đăng ký thủ công — khi các quy tắc suy đoán không xác định được công cụ

# 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

Xem đầy đủ tùy chọn cho từng lệnh: USAGE.md.

CLI và trình cài đặt gửi dữ liệu sử dụng ẩn danh đến PostHog khi dùng treg.to (không có đối số hoặc thông tin xác thực). Tắt tính năng này bằng TREG_TELEMETRY=0 hoặc DO_NOT_TRACK=1. Xem chi tiết phân tích.

Nhóm

Một tài khoản có thể sở hữu tối đa 10 nhóm. Việc tham gia các nhóm khác với tư cách thành viên không tính vào giới hạn này.

Mọi thứ đều thuộc phạm vi của một org: một token = một tư cách thành viên (user, org), và mọi secret, tool, và skill đều thuộc về org đang hoạt động. Vai trò: 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+)

Chủ sở hữu nhóm có thể bật SSO doanh nghiệp từ thẻ Team → SSO trên bảng điều khiển. WorkOS kết nối với nhà cung cấp danh tính của công ty; chủ sở hữu có thể mời quản trị viên CNTT hoàn tất thiết lập. Nhân viên có thể nhập email công việc vào bất kỳ hộp thoại đăng nhập nào hoặc dùng liên kết đăng nhập trực tiếp của nhóm. treg giữ nguyên các vai trò nhóm và API key. Gói Directory Sync xóa quyền truy cập nhóm của nhân viên đã bị vô hiệu hóa. Xem thiết lập SSO doanh nghiệp.

Tìm hiểu sâu hơn

• Phản hồi: treg feedback submit friction "The pagination example is unclear." Chia sẻ vấn đề hoặc đề xuất mà không kèm thông tin riêng tư. Xem hướng dẫn phản hồi.

• Đánh giá: treg review CALL_ID useful Đánh giá một lệnh gọi catalog được mời sau khi dùng kết quả; not_sure là được. Không đưa dữ liệu riêng tư vào và tiếp tục tác vụ.

• USAGE.md — tài liệu tham khảo đầy đủ về CLI treg.

• /llms.txt: điểm vào dành cho agent, theo định dạng llms.txt gồm: treg là gì, cách thiết lập cho từng loại agent, vòng lặp tìm kiếm-đọc-gọi và các quy tắc, cùng liên kết đến /skill.md, hướng dẫn vận hành, cho mọi nội dung khác.

• Bảng điều khiển tại treg.to — đầy đủ thao tác CRUD, hướng dẫn từng bước (Help → Tutorial) và hướng dẫn thiết lập có thể sao chép cho các agent.

• API — mọi thao tác CLI đều dùng HTTP thuần; tài liệu OpenAPI tương tác có tại /docs. Endpoint proxy là /call/{...}; mọi endpoint đều yêu cầu header X-Treg-Token.

---

Phần 2 · Tự lưu trữ & phát triển

Chạy cục bộ

Một lệnh (cần tmux + uv; tự đồng bộ venv):

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

Lệnh này chạy máy chủ trong tmux với hot-reload, DB sqlite riêng (treg-dev.db) và chế độ phát triển email OTP (mã đăng nhập hiển thị trên trang — không cần dịch vụ gửi thư). Các thao tác hằng ngày:

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

Hoặc chạy máy chủ trực tiếp, không dùng 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

Cài đặt để chạy máy chủ (không phải từ mã nguồn): gói cơ sở chỉ có CLI. Để chạy một registry, hãy cài phần bổ sung máy chủ — pip install "tools-registry[server]" — bao gồm FastAPI, trình điều khiển cơ sở dữ liệu và mã hóa. Chỉ cài pip install tools-registry thì chỉ có lệnh treg để giao tiếp với một registry hiện có.

Dịch vụ lưu trữ chính thức có tại treg.to. Cấu trúc liên kết môi trường production và các cài đặt đang hoạt động được duy trì trong sổ tay vận hành riêng tư.

Cấu hình

Biến môi trường (tiền tố TREG_, đọc từ .env):

Var	Default	Purpose
TREG_DATABASE_URL	sqlite+aiosqlite:///./treg.db	URL DB (SQLite cho dev, Postgres trong prod)
TREG_READ_DATABASE_URL	(empty)	Nguồn dữ liệu đọc SQLite / PostgreSQL tùy chọn; để trống sẽ dùng lại nguồn chính. Yêu cầu bên gọi chủ động chọn; các truy vấn hiện có không thay đổi. Xem thiết lập nguồn dữ liệu đọc.
TREG_SECRET_KEY	(empty)	Khóa Fernet cho secret được mã hóa khi lưu; để trống → tạo khóa tạm thời (secret sẽ không tồn tại sau khi khởi động lại)
TREG_PUBLIC_URL	https://treg.to	URL cơ sở công khai của treg, dùng để tạo URI callback OAuth
TREG_SESSION_SECRET	(empty)	ký cookie phiên của bảng điều khiển; nếu không có thì dùng TREG_SECRET_KEY. Đặt giá trị thực trong prod
TREG_GITHUB_CLIENT_ID / _SECRET	(empty)	Đăng nhập OAuth bằng GitHub (callback <public_url>/auth/github/callback); để trống sẽ ẩn nút
TREG_GOOGLE_CLIENT_ID / _SECRET	(empty)	Đăng nhập OAuth bằng Google (redirect <public_url>/auth/google/callback); để trống sẽ ẩn nút
TREG_WORKOS_API_KEY / _CLIENT_ID / _WEBHOOK_SECRET	(empty)	SSO doanh nghiệp WorkOS; cấu hình callback và webhook thư mục có chữ ký như mô tả trong thiết lập SSO doanh nghiệp
TREG_ENTERPRISE_SSO_BUNDLE_ONLY	true	Mặc định chỉ hiển thị gói SSO + Directory Sync; đặt thành false để cung cấp cả hai gói theo tháng.
TREG_ENTERPRISE_SSO_BUNDLE_PRICE_ID / TREG_ENTERPRISE_SSO_ONLY_PRICE_ID	(empty)	ID Stripe Price theo tháng có thể tái sử dụng trong cùng tài khoản với TREG_STRIPE_SECRET_KEY; Price chưa được đặt hoặc không dùng được sẽ ẩn gói tương ứng. Price của Stripe cung cấp số tiền hiển thị và khoản phí Checkout.
TREG_ENTERPRISE_SSO_BUNDLE_MIN_PRICE_USD / TREG_ENTERPRISE_SSO_ONLY_MIN_PRICE_USD	0	Mức giá tối thiểu tùy chọn, tính theo đô la nguyên, cho từng Stripe Price theo tháng; giá thấp hơn sẽ bị ẩn và từ chối tại Checkout.
TREG_INSTAGRAM_CLIENT_ID / _SECRET	(empty)	ID và secret của Instagram App để đăng nhập Instagram trực tiếp (redirect <public_url>/oauth/callback)
TREG_META_CLIENT_ID / _SECRET	(empty)	Thông tin xác thực ứng dụng Meta cho Facebook Pages, Meta Ads và page-tools Instagram tùy chọn
TREG_OAUTH_REVIEW_PENDING	instagram-login,page-messages	Các khóa đánh giá registry, phân tách bằng dấu phẩy, có các khả năng phải tiếp tục bị giới hạn; trạng thái đánh giá trên dịch vụ lưu trữ được quản lý riêng tư.
TREG_RESEND_API_KEY / TREG_EMAIL_FROM	(empty)	Email giao dịch qua Resend (mã OTP + lời mời); địa chỉ From phải là người gửi đã xác minh trên Resend
TREG_BLOCKED_EMAIL_DOMAINS	(empty)	Các miền email bị từ chối tại mọi cổng đăng ký/đăng nhập và khi tạo nhóm, phân tách bằng dấu phẩy (bao gồm miền con, không phân biệt chữ hoa chữ thường). Để trống nghĩa là không chặn gì — mã nguồn không có danh sách mặc định
TREG_CLIENT_IP_HEADER	(empty)	Một header mà chỉ edge của bạn có thể đặt, dùng làm địa chỉ client cho mọi giới hạn theo IP (cf-connecting-ip phía sau Cloudflare)
TREG_TRUSTED_PROXY_HOPS	1	nếu không có header đó: mục X-Forwarded-For cách bên PHẢI số hop này (mục mà proxy gần nhất của bạn đã thêm vào); 0 khi client kết nối trực tiếp. Mục đầu tiên do client ghi và không bao giờ được tin cậy
TREG_REQUIRED_EXTENSIONS	(empty)	Các phần mở rộng chính sách phân tách bằng dấu phẩy (treg.extensions entry point) phải được cài đặt, nếu không quá trình khởi động sẽ thất bại. treg.to dùng một phần mở rộng chính sách chống lạm dụng riêng tư theo cách này; phần mở rộng chỉ có thể áp đặt thêm hạn chế (phần mở rộng chính sách)
TREG_TURNSTILE_SITE_KEY / _SECRET	(empty)	Cloudflare Turnstile trên mọi biểu mẫu đăng nhập email và lần đăng nhập GitHub/Google đầu tiên bằng địa chỉ mới; để trống một trong hai = tắt. Site key được cung cấp trong /captcha.js, secret chỉ được gửi đến siteverify
TREG_TURNSTILE_MODE	observe	observe ghi nhật ký từng kết quả và không thay đổi gì; enforce từ chối gửi mã cho token bị thiếu hoặc không hợp lệ, không cấp quyền đăng ký khi Cloudflare không phản hồi, và chỉ cấp quyền đăng ký cho người dùng GitHub/Google mới khi kiểm tra thành công
TREG_TURNSTILE_SOCIAL	true	false bỏ qua bước kiểm tra trong lần đăng nhập GitHub/Google đầu tiên bằng địa chỉ mới; khi đó người dùng được cấp quyền đăng ký như khi không có widget; cổng email không thay đổi
TREG_TURNSTILE_HOSTNAMES	(empty)	Các host phân tách bằng dấu phẩy mà token phải được giải trên đó; để trống = host TREG_PUBLIC_URL (và các bí danh đã biết của host đó)
TREG_ADMIN_TOKEN	(empty)	Bearer super-admin xuyên tenant; cấp quyền cho mọi endpoint /admin/*. Để trống sẽ tắt đường dẫn env (chỉ người dùng is_superadmin mới truy cập được /admin). Giữ khóa dài và bí mật.
TREG_EMAIL_DEV_MODE	false	khi là true, /auth/email/start trả OTP trong phản hồi (không cần dịch vụ gửi thư) — chỉ dùng cho dev/local, tuyệt đối không dùng trong prod.
TREG_KV_URL	(empty)	Kho key-value dùng chung (giao thức Redis) cho các bộ đếm mà mọi worker phải thống nhất, hiện là ngân sách lời mời đánh giá theo nhóm. Để trống = dùng phương án dự phòng trong tiến trình, phù hợp với một worker

Không cần .env cho dev cục bộ — mọi cài đặt đều có giá trị mặc định hoạt động (khóa tạm thời, sqlite).

⚠️ Hãy sao lưu các mục này trước khi di chuyển hoặc triển khai lại: khóa Fernet (TREG_SECRET_KEY) và cơ sở dữ liệu (Postgres trong prod; treg.db cho lần chạy sqlite cục bộ). Nếu mất khóa Fernet, mọi secret đã lưu sẽ không thể khôi phục.

Kiến trúc

Luồng yêu cầu cho /call: phân giải tool (theo host URL + tiền tố base_url dài nhất, hoặc theo tên) → giải mã secret của nó → áp dụng injector của từng binding → truyền luồng đến upstream → ghi bản ghi kiểm toán theo kiểu fire-and-forget. Relay hạ tầng truyền luồng byte mà không xử lý logic nghiệp vụ. Ứng dụng xử lý lệnh gọi đệm các phản hồi cần quyết toán hoặc bằng chứng quyền sở hữu, tối đa 8 MiB; phản hồi lớn hơn trả về 502 mà không tính phí thay vì trả về thành công bị cắt cụt. Các endpoint nhúng media (ảnh Gemini) khai báo spooled_response: thay vào đó, câu trả lời tính phí được đọc vào tệp tạm, quyết toán dựa trên mức sử dụng được báo cáo rồi chuyển tiếp nguyên vẹn. Các lượt tải xuống cuối cùng miễn phí đã được cấp quyền, không cần bằng chứng từ nội dung, được truyền đầy đủ; phản hồi dùng khóa riêng và tool riêng cũng vậy.

Sơ đồ module (src/treg/):

Mô-đun	Vai trò
proxy.py	relay() — toàn bộ sản phẩm trong một hàm: proxy truyền luồng trung thực
injectors.py	điểm nối về hình dạng xác thực: env, cli_auth, secret_file, oauth đặt bí mật vào header/query
oauth.py	độ mới của token (làm mới đơn luồng) + luồng kết nối (URL đồng ý, trao đổi mã)
health.py	tình trạng thông tin xác thực: làm mới oauth, thăm dò công cụ, gửi webhook cho chủ sở hữu khi có sự cố
convert.py	tạo khung thư mục kỹ năng thành gói kê khai có thể đăng ký
api.py	API — bộ não duy nhất; CLI + kỹ năng là các ứng dụng khách mỏng chạy trên đó
cli.py	CLI treg
models.py	các bảng SQLModel: Org, User, Membership, Invite, Secret, Tool, Bundle, PendingOAuth, CallRecord
crypto.py config.py db.py audit.py	mã hóa Fernet + token · cài đặt · DB bất đồng bộ · trình ghi kiểm toán trì hoãn

4 hình dạng xác thực (theo binding injector): env (chuỗi thuần / khóa API) · secret_file (tệp token JSON, lấy một trường) · oauth (token OAuth JSON, tự động làm mới nếu có thể làm mới) · cli_auth (thông tin được lấy từ keychain của CLI).

Cam kết chuyển tiếp trung thực: proxy chỉ thay đổi ba thứ, mọi thứ khác được giữ nguyên:

1. header truyền tải hop-by-hop (được tạo lại cho mỗi hop),
2. các header điều khiển + chuyển tiếp biên của chính treg (x-treg-token, x-treg-org, ngrok-skip-browser-warning, x-forwarded-*, via, …) và cookie phiên của treg — tất cả đều bị loại bỏ, không bao giờ rò rỉ lên upstream,
3. (các) thông tin xác thực được chèn vào.

OAuth, ba cách lấy token đầu tiên: tải lên thủ công (thả vào một token.json) · tự động làm mới (nếu token có refresh_token + thông tin xác thực ứng dụng, treg sẽ giữ token luôn mới, bạn không bao giờ phải tải lên lại) · luồng kết nối được lưu trữ (treg oauth connect → đồng ý trên trình duyệt → treg tự thu thập token).

Kiểm tra tình trạng: cung cấp cho công cụ một probe tùy chọn ({method, path, expect_status}); một lần chạy định kỳ (theo yêu cầu hoặc qua cron) sẽ xác thực mọi thông tin xác thực, làm mới OAuth và gửi webhook cho chủ sở hữu khi có thông tin nào bị lỗi.

Thiết kế chi tiết nằm trong docs/context/ (các phần theo từng hệ thống con).

Kiểm thử

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

Phạm vi bao phủ: bộ khung proxy tối thiểu, mọi hình dạng injector, xác thực theo người dùng + CRUD + kiểm toán, bộ soạn kỹ năng, chuyển tiếp URL + chuyển tiếp trung thực, làm mới OAuth + luồng kết nối, kiểm tra tình trạng, treg run/shell, tải lên/quét, tổ chức + lời mời, API bảng điều khiển, CLI.

Đóng góp & tài liệu

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

Tài liệu thiết kế theo từng hệ thống con là các phần rời trong docs/context/, mỗi phần trích dẫn các nguồn src/treg/* tương ứng. Đang làm việc trong repo này với một tác nhân AI? Kỹ năng /tools-registry-context sẽ tải phần phù hợp với nội dung bạn đang chỉnh sửa và giữ tài liệu đồng bộ — chạy /tools-registry-context sync trước khi đẩy thay đổi.

Lộ trình: hỗ trợ MCP · các cấp quyền chi tiết hơn · tăng cường quản lý khóa khi lưu trữ · khả năng hợp nhất Loopni.

Giấy phép

Apache 2.0 với các điều khoản bổ sung (LICENSE): tự do sử dụng — kể cả cho mục đích thương mại, trong tổ chức của riêng bạn (khuyến khích tự lưu trữ registry của riêng mình). Hạn chế: không được phân phối lại mã cho bên thứ ba dưới dạng dịch vụ registry lưu trữ/quản lý cạnh tranh nếu không có sự cho phép bằng văn bản (jason@superdesign.dev). Được phép sử dụng API treg.to được lưu trữ trong sản phẩm của riêng bạn — với tính phí chuyển tiếp qua X-Treg-Meta và usage/by-tag — mà không cần xin phép; đó là gọi API của chúng tôi, không phải phân phối lại phần mềm của chúng tôi.

Phạm vi đọc của khách hàng được ghim

Đối với tác nhân khách hàng bị giới hạn, treg org agent-new bot --pin customer=cust_A thực thi việc ghi nhận nguồn và giới hạn lịch sử gọi/chạy, kết quả đã lưu trữ và quyền sở hữu bất đồng bộ của nhà cung cấp dùng chung theo ghim đó. ID thuộc phạm vi khác hoặc không có thông tin ghi nhận nguồn sẽ trả về 404; toán tử không ghim vẫn giữ chế độ xem toàn tổ chức và số dư dùng chung. Quyền truy cập tài khoản BYOK và URL phương tiện công khai vẫn giữ nguyên quyền hiện có. Xem cam kết đa thuê bao để biết về nhiều ghim, hành vi di chuyển và phát lại.