Io.Github.Crunchtools/Airlock

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 — or at a trusted boundary you declare — 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 to the trust boundary, which can be federated with other instances: L1 deterministic checks, L2 a local classifier, L3 a quarantined LLM with no tools. Semantic request guards judge 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. Literal request guards, literal response guards and allowlists are evaluated by the gateway, so an agent that ignores its instructions is stopped before the backend sees the call. Literal Request Guards · Literal 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 — and an operator agent configures all of it through tools, with no shell; the five grants only a person should agree to, it proposes and you approve. Profiles · Operator · Approvals

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)
Semantic Request Guards	A judge reads calls to listed tools against a policy in plain English
Semantic Response Guards	A judge reads listed tools' responses against a policy before delivery
Literal Request Guards	Per-tool argument validation
Literal 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
Stability tiers	Which features may change shape in a minor release, and how you are told
Approvals	The six grants an operator proposes and a person agrees to
Federation	Share a profile with a second gateway: its tools mounted over a trusted link, scanned once
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
Proxies	Every perimeter route as config under proxies:, the forward type, and route plugins
Plugins	Write, test, install and name your own transform plugins
Cockpit Plugin	Live defense pipeline dashboard
Internal: Gateway Design	Original design document, for contributors

Development

pre-commit install          # wires the commit and push checks

CONTRIBUTING.md is the page for a person: the three commands, what each costs, and what an exit code means. The host needs only git, podman, pre-commit and gh — every check runs from python-sdlc, the same image CI runs. The demo is recorded by demo.yml; its fixtures are in docs/demo/.

License

AGPL-3.0-or-later