<p align="center">
  <img src="https://raw.githubusercontent.com/crunchtools/trentina/main/docs/images/trentina-logo.png" alt="trentina: a medieval merchant ship anchored offshore while an inspector in a rowboat checks each crate of code before it reaches the harbor gate" width="320">
</p>

# Trentina

<!-- mcp-name: io.github.crunchtools/trentina -->

Trentina is an MCP gateway that sits between your AI agents and everything they
touch: MCP servers, the web, Matrix, LLM providers and monitoring alerts. Every
agent gets one endpoint and its own profile. Behind that endpoint Trentina
stops prompt injection at every ingress and shrinks what reaches the context
window. It also enforces policy the agent cannot talk its way past and handles
OAuth for web clients like claude.ai and gemini.google.com. The same gateway
can serve a personal assistant, a coding agent and a swarm, wired however you
like. It is named after the 1377 *trentino* of Ragusa, where ships anchored
offshore for thirty days before anyone came ashore. The idea is the same:
commerce keeps flowing, and nothing dangerous gets in.

<p align="center">
  <img src="https://raw.githubusercontent.com/crunchtools/trentina/main/docs/demo/trentina.gif" alt="Demo: a request crosses Trentina's auth, policy, defense and minify stages; then, in a terminal, a 131-tool list is served as 6 tools, a recipe page with an injection in its comments is refused and then answered through redact, and a send to an outside address is refused while a draft goes through" width="800">
</p>

## Why Trentina

1. **Security.** Untrusted content gets the same three independent layers at
   every ingress: tool responses, tool descriptions, web pages, Matrix
   messages, LLM completions and alerts. L1 is deterministic checks, L2 is a
   local classifier and L3 is a quarantined LLM with no tools. L2's model is
   a setting: Horizon-Labs' prompt-injection-guard-small by default, Prompt
   Guard 2 86M one variable away. On our attacks planted inside long
   documents the default catches 21 of 39 where Prompt Guard 2 catches 4,
   2.4x faster on CPU. L3 reads everything L2 lets through.
   Around the layers sit an egress guard, file confinement and a startup
   containment check. What is and is not defended, by kind of content, is in
   [Coverage](docs/defense-pipeline.md#coverage), with every known gap.
   [Defense Pipeline](docs/defense-pipeline.md) · [Benchmark](docs/benchmark.md)

2. **Token savings.** Agents pay for every tool name, schema and response byte
   they read. Trentina hides tools a profile doesn't need, serves short names,
   compacts schemas and compresses descriptions: 154 tool descriptions went
   from 62K to 17K characters. It also minifies responses. On production
   traffic, agents received **52% fewer response bytes** than backends sent,
   across 4,164 calls. [Compression](docs/compression.md) ·
   [Tool Filtering](docs/tool-filtering.md)

3. **Determinism.** Asking a model nicely is not a control. Parameter guards,
   response guards and allowlists are evaluated by the gateway, so an agent
   that ignores its instructions, or assumes it has permission, is stopped
   before the backend sees the call. Trentina can't know when your email is
   ready to send. It can let the agent draft and keep the send for you.
   Production, last 30 days: 61 calls stopped by parameter guards, 11
   responses withheld by response guards. [Parameter Guards](docs/parameter-guards.md) ·
   [Response Guards](docs/response-guards.md)

4. **Authentication.** Web clients need OAuth, and most MCP servers don't
   speak it. Trentina is the authorization server: dynamic client
   registration for claude.ai and Claude Code, a provisioned client for
   gemini.google.com, verified external issuers, or a static bearer, chosen
   per profile. Each token is bound to the profile it was issued for, and LLM
   API keys stay inside the gateway. [Authentication](docs/authentication.md) ·
   [LLM Key Proxying](docs/llm-proxying.md)

5. **Architectural flexibility.** One gateway, many shapes. A personal
   assistant on Matrix, a coding agent in Claude Code and a swarm of locked-down
   autonomous agents each get their own profile, with their own backends,
   defense mode and credentials. An operator agent runs the gateway itself.
   The production deployment serves 8 profiles over 30 backends.
   [Profiles](docs/profiles.md) · [Operator](docs/operator.md)

## Capabilities

### Security

1. **[Three-Layer Defense Pipeline](docs/defense-pipeline.md).** Every payload
   runs L1 ∥ L2, then L3 briefed with both. The profile's mode decides delivery,
   never detection: `block` refuses, `flag` delivers the exact bytes with a
   verdict, `redact` returns an answer L3 extracted and a second pass verified.
2. **[Prompt Packs](docs/l3-prompt-tuning.md).** The L3 judge's prompts,
   tuned and measured for one exact model. On held-out benign content the
   generic prompts flag 19% on Gemini 2.5 Flash Lite and 47% on Gemini 3.8
   Flash; the shipped packs bring that to 2% and 0%, and catch every
   planted-instruction case the generic prompts catch. Packs ship for four
   judges, each through a held-out gate, and an operator can tune their own
   for any model.
3. **[Content Tools](docs/quarantine-tools.md).** `fetch`, `read`, `dir`,
   `content` and `search`, built-in tools that bring outside content in
   through the pipeline. Fetches go through an egress guard that refuses
   private addresses and checks every redirect. Reads are confined to
   configured roots.
4. **[Cumulative Detection Memory](docs/blocklist.md).** A refused source stays
   refused for that profile until its entry expires, whatever a probabilistic
   layer thinks on the next run.
5. **[Matrix Bridge](docs/matrix-bridge.md).** Terminates end-to-end
   encryption in a separate process so every message, in both directions,
   crosses the pipeline.
6. **[Deployment Hardening](docs/deployment-hardening.md).** Container flags,
   secrets from files, network isolation, and a startup check that warns or
   refuses on containment gaps.

### Token savings

6. **[Tool Filtering](docs/tool-filtering.md).** Allowlists and denylists,
   exact or glob. A tool a profile can't use never enters its context window.
7. **[Tool Description Compression](docs/compression.md).** Tool and parameter
   descriptions are compressed once by the operator's model and cached. Schemas
   are compacted, and tools are served under short names.
8. **[Minified Responses](docs/profiles.md#minifying-and-exact-text).** HTML
   becomes Markdown, logs and JSON arrays are grouped by
   [petit](https://github.com/crunchtools/petit), quoted mail threads collapse.
   Minifying fails open: if it breaks, the agent gets the original.

### Determinism

9. **[Parameter Guards](docs/parameter-guards.md).** Per-tool allow/deny
   patterns on argument values: "this agent may send mail, but only to
   `user@example.com`." Refused before the backend is called.
10. **[Response Guards](docs/response-guards.md).** The same constraint on what
    a backend returns, for semantic tools where nothing in the arguments is
    matchable.
11. **[Gateway Audit Log](docs/audit-log.md).** Every call, with profile,
    backend, tool, outcome, bytes in and out, and duration. It tells you
    which guards fired and which allowlisted tools no agent ever uses.

### Authentication

12. **[Authentication](docs/authentication.md).** Static bearer, OAuth proxy
    with DCR, OAuth proxy with a provisioned client, or a delegated external
    issuer, each set per profile. The tokens Trentina issues are bound to
    their profile.
13. **[LLM Key Proxying](docs/llm-proxying.md).** Agents call models through
    the gateway, which adds the real key. Request bodies are allowlisted and
    re-serialized, so a provider can't become a side door out of a
    `--network=none` container.

### Architectural flexibility

14. **[MCP Gateway](docs/gateway.md).** One endpoint per profile in front of
    any number of streamable-HTTP MCP backends, with circuit breakers, hot
    reload and argument normalization.
15. **[Per-Agent Profiles](docs/profiles.md).** Each consumer gets its own
    backends, tools, defense mode, pre-processors and authentication.
16. **[Operator Profile](docs/operator.md).** Trentina is built to be run by an
    agent. The operator seat installs, reloads and administers the gateway, and
    is the identity its own model calls bill to.
17. **[Matrix Reverse Proxy](docs/network-isolation.md).** Agents on an
    isolated network reach Matrix through the gateway rather than the internet.
18. **[Cockpit Plugin](docs/cockpit-plugin.md).** A live dashboard of layers,
    blocklist and pipeline events in the Cockpit console.

## Quick Start

```bash
# 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`:

```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:

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

## Documentation

| Document | Description |
|----------|-------------|
| [MCP Gateway](docs/gateway.md) | Endpoint, routing, tool names, argument normalization |
| [Per-Agent Profiles](docs/profiles.md) | Profile schema, modes, minifying, roles, multi-agent setup |
| [Operator Profile](docs/operator.md) | The operator agent's seat and the gateway's service identity |
| [Configuration](docs/configuration.md) | Every environment variable |
| [Authentication](docs/authentication.md) | Static bearer, OAuth proxy with DCR or a provisioned client, delegated issuers |
| [Defense Pipeline](docs/defense-pipeline.md) | L1/L2/L3, modes, coverage and known gaps |
| [Benchmark](docs/benchmark.md) | Detection rates per layer and per L3 provider |
| [Prompt Packs](docs/l3-prompt-tuning.md) | The judge's prompts tuned per model: shipped packs, the gate, tuning your own |
| [Content Tools](docs/quarantine-tools.md) | fetch, read, dir, content, search |
| [Blocklist](docs/blocklist.md) | Cumulative detection memory |
| [Tool Filtering](docs/tool-filtering.md) | Allowlists, denylists, glob patterns |
| [Description Compression](docs/compression.md) | Description compression and schema compaction |
| [Token Routing](docs/token-routing.md) | Response reduction (implemented); delegation (proposed) |
| [Parameter Guards](docs/parameter-guards.md) | Per-tool argument validation |
| [Response Guards](docs/response-guards.md) | Per-tool result validation |
| [Audit Log](docs/audit-log.md) | Call recording, stats, monitoring |
| [LLM Key Proxying](docs/llm-proxying.md) | Provider keys kept inside the gateway |
| [Matrix Bridge](docs/matrix-bridge.md) | E2EE termination and two-way judging |
| [Matrix Reverse Proxy](docs/network-isolation.md) | Matrix for agents on an isolated network |
| [Deployment Hardening](docs/deployment-hardening.md) | Container flags, secrets, egress, the startup check |
| [Cockpit Plugin](docs/cockpit-plugin.md) | Live defense pipeline dashboard |
| [Internal: Gateway Design](docs/internal/gateway-design.md) | Original design document, for contributors |

## Development

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

The demo above is recorded against the published image by
[`demo.yml`](.github/workflows/demo.yml) (`docs/demo/render.sh`); see
[`docs/demo/`](docs/demo/) for the fixtures it runs.

The container image is built by the GHA pipeline
([`container.yml`](.github/workflows/container.yml)), never locally. The model-export
stage needs a gated HuggingFace credential that only CI holds, and building outside
the pipeline causes drift. Push the branch and let the pipeline verify the image.

## License

AGPL-3.0-or-later