Trentina

Trentina

Trentina sits between your AI agents and everything they touch: MCP servers, the web, Matrix, LLM providers and alerts. It stops prompt injection at every ingress, shrinks what reaches the context window, and enforces a policy the agent cannot talk its way past. It is named after the 1377 trentino of Ragusa, where ships anchored offshore for thirty days before anyone came ashore: commerce keeps flowing, and nothing dangerous gets in.

Why Trentina

1. Security. Untrusted content crosses three independent layers at every ingress: L1 deterministic checks, L2 a local classifier, L3 a quarantined LLM with no tools. Guarded execution judges what goes out against a rule you write in English. What is and is not defended is in Coverage. Defense Pipeline · Benchmark · OWASP mapping

2. Token savings. Hidden tools, short names, compacted schemas, compressed descriptions and minified responses: 52% fewer response bytes on production traffic. Compression · Tool Filtering

3. Determinism. Parameter guards, response guards and allowlists are evaluated by the gateway, so an agent that ignores its instructions is stopped before the backend sees the call. Parameter Guards · Response Guards

4. Authentication. Trentina is the OAuth authorization server for web clients such as claude.ai: dynamic client registration, a provisioned client, external issuers or a static bearer, chosen per profile. Authentication

5. Architectural flexibility. A personal assistant, a coding agent and a swarm each get their own profile, with their own backends, defense mode and credentials. Profiles · Operator

Quick Start

# The container image is the distribution: the L2 model, the parsers and
# their process isolation ship in it. There is no PyPI package.
podman run -d -p 127.0.0.1:8019:8019 \
    -v ./profiles.yaml:/config/profiles.yaml:ro,Z \
    -e TRENTINA_GATEWAY_ENABLED=true \
    -e TRENTINA_PROFILES_PATH=/config/profiles.yaml \
    -e TRENTINA_PROFILE_MYAGENT_TOKEN=your-token \
    -e OPENROUTER_API_KEY=your-key -e TRENTINA_MODEL_PROVIDER=openrouter \
    quay.io/crunchtools/trentina \
    --transport streamable-http --host 0.0.0.0 --port 8019

L3 needs a key for one LLM provider. Any of Gemini, OpenRouter, OpenAI, Anthropic or Ollama works. A minimal profiles.yaml:

profiles:
  myagent:
    auth:
      bearer_token_env: TRENTINA_PROFILE_MYAGENT_TOKEN
    backends:
      web:
        url: "internal://web"         # Trentina's own content tools
        tools_allow: ["*"]
      gmail:
        url: "http://gws-personal:8000/mcp"
        tools_allow:                  # it may read and draft; you send
          - search_gmail_messages
          - get_gmail_message_content
          - draft_gmail_message
    defense:
      enforcement: block

Then point Claude Code at it:

{
  "mcpServers": {
    "trentina": {
      "type": "streamable-http",
      "url": "http://localhost:8019/gateway/myagent/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Documentation

Document	Description
MCP Gateway	One endpoint per profile: routing, tool names, circuit breakers
Per-Agent Profiles	Profile schema, modes, minifying, roles, multi-agent setup
Operator Profile	The agent that installs and runs the gateway
Configuration	Every environment variable
Authentication	Static bearer, OAuth proxy with DCR or a provisioned client, delegated issuers
Backend OAuth	Each profile signs in to OAuth-only backends with its own grant
Defense Pipeline	L1/L2/L3, modes, coverage and known gaps
Benchmark	Detection rates per layer and per L3 provider
Corpora	Every attack and benign set the defense is measured on
Prompt Packs	The judge's prompts tuned per model
Content Tools	fetch, read, dir, content, search, with an egress guard and file confinement
Blocklist	A refused source stays refused
Tool Filtering	Allowlists, denylists, glob patterns
Tool Pinning	A new or changed tool is held until approved
Tool Discovery	Find/call or per-session loading for clients without tool search
Description Compression	Description compression and schema compaction
Token Routing	Response minifying (implemented); delegation (proposed)
Guarded Execution	A judge reads calls to listed tools against a policy in plain English
Parameter Guards	Per-tool argument validation
Response Guards	Per-tool result validation
Audit Log	Call recording, stats, monitoring
LLM Key Proxying	Provider keys kept inside the gateway
Matrix Bridge	E2EE termination and two-way judging
Channel Bridges	More than one upstream per agent (RCS, ...) and the bridge wire contract
Matrix Reverse Proxy	Matrix for agents on an isolated network
Client Egress	A CONNECT tunnel to listed hosts for the agent's own client
Git Transport	Clone, fetch and push to listed repositories and branches
HTTP(S) Egress	An agent's outbound request judged and re-originated to a named destination
Deployment Hardening	Container flags, secrets, egress, the startup check
Cockpit Plugin	Live defense pipeline dashboard
Internal: Gateway Design	Original design document, for contributors

Development

uv sync --all-extras
uv run ruff check src tests
uv run mypy src
uv run pytest -v

The container image is built by CI, never locally; see CLAUDE.md. The demo is recorded by demo.yml; its fixtures are in docs/demo/.

License

AGPL-3.0-or-later