Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff

Public Access

By default, Trinity is only accessible on the local network or via VPN. Enabling public access exposes specific paths through a Cloudflare Tunnel so that external webhooks, public chat links and MCP clients work without opening firewall ports or requiring a static IP.

TLS Is Terminated Outside Trinity

Trinity serves plain HTTP; no compose file carries an HTTPS listener or a certificate step. Before an instance answers on a public address, choose one posture:

PostureWhat it gives youWhen to use it
Cloudflare Tunnel (this page)HTTPS at a real hostname, no inbound ports open at allThe default for a public instance. Nothing to renew.
Private network (Tailscale / WireGuard / VPC)Encrypted transport; the instance is not on the public internetTeams and webhook sources that can all reach the VPN. Inbound integrations (Telegram, WhatsApp, VoIP, webhook triggers) do not work without a public hostname.
Reverse proxy you run (Caddy / nginx + Let's Encrypt)HTTPS at your own domainYou already operate a proxy. Have it send X-Forwarded-Proto: https on every request — Trinity reads that header to show https:// webhook and MCP URLs (see Webhook URLs).

Plain HTTP on a public IP with none of the above is the one combination to avoid. An instance prepared by start.sh --provision (the DigitalOcean 1-Click or installer script, an AWS or Vultr install) ships its own Caddy with a short-lived certificate for the instance's IP, and on the DigitalOcean and AWS paths the Secure this instance step of the first-run setup presents the tunnel below as the second hardening stage, after a domain — see Single Server → DigitalOcean 1-Click.

What Public Access Enables

FeatureRequires public access
Slack: the one-time OAuth install callback, and event delivery in webhook mode (the default Socket Mode connects outward and needs none)Yes
Telegram bot webhooksYes
WhatsApp (Twilio) webhooksYes
Public chat links (/chat/*)Yes
Nevermined paid chat (/api/paid/*/chat)Yes
Web UI access for team members off-VPNYes
MCP access for Claude Code clients off-VPN (/mcp)Yes — and External MCP access turned on (Settings → MCP Keys)

Every path and transport on the MCP port is behind that switch — /mcp in any spelling, the legacy /sse + /messagestransport, and anything else the server answers — so while it is off an off-server client is refused whatever URL it tries; only the health probe answers.

If all your users and webhook sources can reach the server directly (e.g., via Tailscale), you do not need the Cloudflare Tunnel.

Cloudflare Tunnel Setup

1. Create a tunnel

2

Navigate to Networks → Tunnels → Create a tunnel.

3

Select Cloudflared as the connector type.

4

Give the tunnel a name (e.g., trinity).

5

Copy the tunnel token — it starts with eyJ....

2. Configure public hostnames

In the Cloudflare dashboard, add a public hostname for your tunnel under the Public Hostnames tab. The cloudflared container runs on the Trinity networks, so it reaches the platform containers by name. On production and hosted installs it also sits on the ingress network at a reserved address, and its backend and trinity-backend names are pinned there (compose extra_hosts), so both rule shapes below reach the backend from that address — which is how the backend knows a request came through the tunnel and reads the visitor's address from it (see Visitor addresses).

Simplest: one catch-all rule — route the whole hostname to the frontend, http://trinity-frontend:8080. The production frontend's nginx already proxies /api/, /a2a/, /mcp, /ws and /health to the right upstream, so a single rule serves the web UI, every webhook, and MCP. (The frontend container listens on 8080 inside the network; FRONTEND_PORT only changes the host-side mapping.)

Narrower: path-split rules — if you want to publish only the webhook surface rather than the whole UI. Anchor the A2A rules. An unanchored /a2a/* also matches /api/agents/{name}/a2a/call — Trinity's outboundA2A caller, an authenticated internal endpoint that has no business on a public hostname — so use the two anchored rules below rather than a prefix.

Path prefixRoutes toPurpose
/api/public/*http://trinity-backend:8000Public API, OAuth callbacks
/api/telegram/webhook/*http://trinity-backend:8000Telegram bot webhooks
/api/whatsapp/*http://trinity-backend:8000WhatsApp/Twilio webhooks
/api/paid/*http://trinity-backend:8000Nevermined paid chat
^/a2a/[^/]+$http://trinity-backend:8000A2A inbound JSON-RPC door (paid or authenticated)
^/a2a/[^/]+/\.well-known/agent-card\.json$http://trinity-backend:8000A2A discovery card
/api/webhooks/*http://trinity-backend:8000Schedule webhook triggers
/api/voip/*http://trinity-backend:8000VoIP media streams (WebSocket)
/mcphttp://trinity-frontend:8080MCP server, proxied by the frontend
/chat/*http://trinity-frontend:8080Public chat UI
/assets/*http://trinity-frontend:8080Static assets

These rules publish the webhook surface and not the web interface. To publish the interface as well, add a / catch-all routing to http://trinity-frontend:8080. To keep it private, leave that out and reach it over a private network — Hardening → Step 2c.

Add the matching rule whenever you connect a new channel. A path you have not published stops delivering, with no error on this end.

3. Add the DNS record

In your domain's Cloudflare DNS settings, add a CNAME:

public.your-domain.com  →  <tunnel-id>.cfargotunnel.com

Cloudflare creates this automatically when you use Public Hostnames in Zero Trust.

Required Environment Variables

Both variables are forwarded by docker-compose.prod.yml and docker-compose.hosted.yml (the dev compose does not forward TUNNEL_TOKEN — a tunnel is a server-install feature):

VariableExample valueNotes
TUNNEL_TOKENeyJhIjoiY...The token from the Cloudflare Zero Trust dashboard. Required for the cloudflared container to authenticate.
PUBLIC_CHAT_URLhttps://public.your-domain.comThe externally reachable base URL. Used to construct webhook URLs and public chat links. Must match the public hostname you configured in Cloudflare. Also settable after login as the Public URL under Settings → General.

Set both in .env:

TUNNEL_TOKEN=your-tunnel-token-here
PUBLIC_CHAT_URL=https://public.your-domain.com

Also set FRONTEND_URL if it differs from PUBLIC_CHAT_URL:

FRONTEND_URL=https://trinity.your-domain.com

Visitor Addresses Behind the Tunnel and Other Proxies

Per-client sign-in limits and audit-log addresses use the visitor's address. The backend learns it from a proxy only when that proxy is trusted; nothing else (an agent, a direct caller to port 8000, the Docker bridge gateway) can choose the address it is recorded under.

  • •Cloudflare Tunnel, either rule shape. A direct-to-backend rule (http://trinity-backend:8000) reaches the backend from the tunnel's reserved address; a catch-all rule (http://trinity-frontend:8080) goes through nginx, which appends the tunnel's address to X-Forwarded-For. In both cases the backend takes the visitor from Cloudflare's single CF-Connecting-IP header. No configuration is needed.
  • •When identity is missing. A request that arrives through a trusted proxy without any client identity is still served, but it is attributed to the proxy itself: all such requests share one rate-limit bucket and the audit log shows the proxy's address. Identity that is present but malformed (an empty or duplicated CF-Connecting-IP, an X-Forwarded-For entry that is not an IP address) is refused with 400, or a WebSocket close code 1008. The backend logs a warning, at most once a minute, while requests arrive without identity.
  • •Your own reverse proxy or load balancer in front of port 80: list its address or range in TRUSTED_PROXIES in .env (comma-separated, e.g. TRUSTED_PROXIES=192.0.2.10,198.51.100.0/28), and make sure it overwrites or appends X-Forwarded-For rather than passing a client's value through. Only the right-hand entries your trusted proxies appended are read. Wildcards, 0.0.0.0/0, loopback and Trinity's own Docker networks are refused when the backend starts, with the offending entry named. A proxy on the same host should not be listed; it uses the loopback PROXY-protocol listener (CADDY_PROXY_PORT, see Single-Server Deployment).
  • •Development and bare containers. The development compose (Vite on port 80) trusts no proxy: every request is attributed to its connecting address. A bare docker run of the backend image trusts none either until you configure it.

Starting with the Tunnel

The cloudflared service is defined under the tunnel Compose profile. Setting TUNNEL_TOKEN alone starts nothing.

Hosted installs: ./scripts/deploy/start.sh --hosted reads TUNNEL_TOKEN from .env, adds --profile tunnel itself, and appends COMPOSE_PROFILES=tunnel to .env — so every later bare docker compose -f docker-compose.hosted.yml stop / logs also acts on the tunnel container. Without that persisted profile, stop would leave the tunnel running and the instance publicly reachable after you had been told the stack was down.

Source-built installs: pass the profile explicitly:

# Start everything including the tunnel
docker compose -f docker-compose.prod.yml --profile tunnel up -d

# Start only the tunnel (if other services are already running)
docker compose -f docker-compose.prod.yml --profile tunnel up -d cloudflared

# Or make the profile stick for every later command
echo 'COMPOSE_PROFILES=tunnel' >> .env

Verify the tunnel is connected:

docker ps | grep cloudflared          # a missing container is silent — check it exists
docker logs trinity-cloudflared
# Look for: "Registered tunnel connection" or "Connection established"

Stopping the Tunnel

docker compose -f docker-compose.prod.yml stop cloudflared     # or -f docker-compose.hosted.yml

This stops the tunnel container without affecting the rest of the platform.

Webhook URLs After Enabling Public Access

Once PUBLIC_CHAT_URL is set and the tunnel is connected, Trinity constructs webhook URLs automatically. These appear in the UI when you configure each integration:

IntegrationURL pattern
Telegram{PUBLIC_CHAT_URL}/api/telegram/webhook/{secret}
WhatsApp (Twilio){PUBLIC_CHAT_URL}/api/whatsapp/webhook/{secret}
Schedule webhookshttps://<the host you opened Trinity on>/api/webhooks/{token} — see below

Copy the URL shown in the UI into the respective third-party dashboard (Telegram BotFather, Twilio console, etc.).

Schedule webhook URLs and the auto-detected MCP URL follow the proxy, not PUBLIC_CHAT_URL. Their host is the one you opened Trinity on, and their scheme comes from the X-Forwarded-Proto header the proxy in front of Trinity sends: a proxy that sends https (a Cloudflare Tunnel, or your own proxy configured as above) gets https://<host>/api/webhooks/{token} and https://<host>/mcp. A proxy that sends no such header, or Trinity opened directly on its own port, gets http://URLs. The scheme is only ever upgraded by that header, never downgraded. So open Trinity through its public address before you copy a schedule's webhook URL.

MCP clients off-VPN connect to {PUBLIC_CHAT_URL}/mcp with an MCP API key (Settings → MCP Keys). The MCP server treats everything arriving through the tunnel or the frontend as outside, so this works only while External MCP access is on — an admin turns it on on the same page; a fresh install starts with it off and refuses such clients with 403 external_mcp_access_off. Agents are never affected. The tunnel cannot bypass the switch: a rule aimed straight at the MCP server container still arrives as an outside caller. The URL the UI shows to users is auto-detected the same way — <origin>/mcp through a proxy that sends X-Forwarded-Proto, the raw :8080 port otherwise; Settings → MCP Keys → MCP Server URL overrides it. See MCP Server — External MCP Access.

Security Notes

  • •The Cloudflare Tunnel does not require opening any inbound firewall ports — the cloudflared container initiates an outbound connection to Cloudflare's edge.
  • •TUNNEL_TOKEN is a long-lived credential. Store it only in .env (gitignored). Do not commit it.
  • •Path prefixes not listed in your ingress rules return 404 at Cloudflare's edge before reaching your server.
  • •Rate limits apply to the public endpoints — schedule webhooks, for example, accept 10 triggers per token per 60 s (WEBHOOK_RATE_LIMIT) and 60 requests per IP per 60 s before authentication (WEBHOOK_IP_RATE_LIMIT).
  • •Forwarded client addresses are believed only from the bundled nginx, the bundled cloudflared and the proxies you list in TRUSTED_PROXIES — see Visitor addresses.
  • •MCP over the tunnel is protected by the MCP API key on every request. Leave MCP_INLINE_AUTH_ENABLED at its default (false) unless you intend keyless email-code sign-in over MCP, and then only over TLS.