The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Trentina listing page.
Trentina is a secure MCP gateway that quarantines everything between your AI agents and the outside world — web content, MCP tool responses, LLM API keys, network access, and agent-to-agent communication. Named after the 1377 quarantine system from Ragusa, where incoming ships had to anchor offshore for thirty days before anyone was allowed into the city. Same idea: keep the commerce flowing without letting something dangerous through.
Single chokepoint between your agents and all their MCP backends. One endpoint, one bearer token, one audit log — instead of each agent connecting directly to dozens of MCP servers. Backend tools are namespaced automatically (slack__slack_search_messages, github__list_issues_tool) so there are no collisions.
Each consumer — Claude Code, Hermes, OpenClaw, or any MCP client — gets its own profile with independent tool access, defense settings, and authentication. Your human-supervised agent can have full tool access while your autonomous agent gets a locked-down subset, all through the same gateway.
Control which tools each agent can even see. Tools not in the allowlist are stripped from tools/list responses before they reach the consumer — they never enter the agent's context window. Supports exact names and glob patterns (delete*, *_gmail_*). Reduces both context cost and attack surface.
Per-tool argument validation at the gateway level. Restrict what values an agent can pass, not just which tools it can call. Example: "this agent can send email, but only to user@example.com." The call is rejected before it reaches the backend — no tokens spent, no side effects. Deterministic enforcement that doesn't depend on LLM behavior.
Every piece of untrusted content passes through three independent detection layers. Layer 1 strips structural attacks (hidden HTML, invisible Unicode, encoded payloads, exfiltration URLs). Layer 2 runs a Prompt Guard 2 86M classifier to catch instruction overrides. Layer 3 hands sanitized content to a quarantined LLM (Gemini Flash Lite) for semantic analysis — no tools, no memory, minimal blast radius. Each layer catches what the others miss.
MCP servers ship verbose tool descriptions that waste context tokens. Trentina uses an LLM to compress every tool description as it passes through the gateway, caching results in SQLite so the model is only called once per unique description. Real-world results: 154 tools compressed from 62K to 17K characters (72% reduction), saving ~11K tokens per session. The compressed descriptions are fully functional — agents use them without issue.
Every tool call through the gateway is recorded in SQLite with profile, backend, tool name, success/failure, duration, and error message. The quarantine_stats tool exposes this data for monitoring — tool call counts, error rates, per-backend breakdowns. Data-driven evidence for tightening allowlists and identifying problems.
When Trentina detects prompt injection in a source, it records the source in a SQLite blocklist. Future requests for that source trigger an immediate warning — the system remembers what it's seen before. Blocklist entries include the source URL or content hash, detection timestamp, and risk level.
Trentina's original capability: safe web fetching, file reading, and web search with prompt injection defense. safe_fetch fails on injection. quarantine_fetch warns but proceeds, extracting content through the Q-Agent. quarantine_search chains Gemini grounding with the full defense pipeline. quarantine_scan does pre-flight detection without returning content.
Proxy LLM API calls (Gemini, OpenAI, Anthropic) through the gateway so API keys never leave the trusted boundary. Agents send model requests to Trentina, which forwards them with the real credentials. Adding a new provider is a YAML entry, not code. Streaming and non-streaming responses are forwarded transparently.
Proxy Matrix Client-Server API traffic through the gateway so agents on the internal network can communicate via Matrix without direct internet access. Agents point MATRIX_HOMESERVER at Trentina instead of matrix.org. Long-poll /sync timeouts are tuned automatically.
Live web dashboard for the defense pipeline, built as a Cockpit plugin with PatternFly 6. Shows layer status, blocklist entries, and pipeline events in real time through the same web console sysadmins already use to manage RHEL systems. Vanilla JavaScript, no React, no build step.
| Document | Description |
|---|---|
| MCP Gateway | Architecture, routing, namespacing |
| Per-Agent Profiles | Authentication, profile schema, multi-agent setup |
| Tool Filtering | Allowlists, denylists, glob patterns |
| Parameter Guards | Per-tool argument validation |
| Defense Pipeline | L1/L2/L3 layers, coverage matrix |
| Description Compression | LLM-powered context reduction |
| Audit Log | Call recording, stats, monitoring |
| Blocklist | Cumulative detection memory |
| Quarantine Tools | Web fetch, read, search, scan |
| LLM Key Proxying | API key isolation via reverse proxy |
| Matrix Reverse Proxy | Agent communication via Matrix |
| Cockpit Plugin | Live defense pipeline dashboard |
| Internal: Gateway Design | Original design document for contributors |
AGPL-3.0-or-later