Bridge
connic bridges provide secure access to private services from connectors, LLM providers, MCP servers, custom tools, and middleware, without inbound firewall rules.
On this page
What is the connic bridge?
The connic bridge is a lightweight agent that runs inside a private network and creates a secure outbound tunnel to connic cloud. Anything in a project (connectors, custom LLM providers, MCP servers, custom tools, and middleware) can then reach services that are not publicly accessible, as if they were running next to them.
Because the bridge only makes outbound connections, no inbound firewall rules need to be opened and private services remain unexposed to the internet.
When is a bridge needed?
A bridge is needed when the target service is:
- Inside a private AWS VPC, GCP VPC, or Azure VNet
- Running on-premises behind a corporate firewall
- Accessible only via private DNS or private IPs
- Behind an IP allowlist that cannot include connic's IPs
Publicly reachable services (e.g. managed Kafka on Confluent Cloud or AWS SQS via a public endpoint) do not need a bridge.
Connection Flow
Private Network
Private Services
Kafka, PostgreSQL, SQS, ...
connic bridge
Runs in a VPC
TLS encrypted
connic cloud
connic tunnel endpoint
relay.connic.co
Connectors, LLM Providers,
Tools & Middlewares, MCP Servers
All reach private services via the bridge
1. Deploy the connic bridge as a Docker container inside the private network.
2. The bridge makes an outbound WSS connection to relay.connic.co (no inbound ports needed).
3. connic sends connections for the selected bridge to the bridge running in the private network.
4. If ALLOWED_HOSTS is configured, the bridge validates the target against that list. Without it, any target reachable from the bridge's network is allowed. The bridge then opens a local TCP connection and proxies the traffic.
5. The WSS connection encrypts traffic between the bridge and the connic tunnel endpoint.
Setup Instructions
Create a Bridge
Go to Project Settings > Bridge and click Add Bridge. Give it a name (e.g. "Production VPC") and copy the token that is displayed. It will only be shown once. Create any number of bridges, each with its own token, to reach different networks or environments.
Run the connic bridge
Deploy the bridge inside the private network. It needs to reach both the private services and the internet.
Docker:
terminaldocker run -d --name connic-bridge --restart unless-stopped \ -e BRIDGE_TOKEN=cbr_your_token_here \ -e ALLOWED_HOSTS=kafka:9092,postgres:5432 \ connicorg/bridge:latestpip:
terminalpip install connic-bridge connic-bridge \ --token cbr_your_token_here \ --allow kafka:9092 \ --allow postgres:5432Docker Compose:
docker-compose.yamlservices: connic-bridge: image: connicorg/bridge:latest restart: always environment: BRIDGE_TOKEN: cbr_your_token_here ALLOWED_HOSTS: kafka:9092,postgres:5432,my-db:5432 LOG_LEVEL: INFO
Once the bridge is online, connectors, LLM providers, custom code, MCP servers, and channels can route through it. Configure each connection independently.
A bridge can't be deleted while a connector, Connection, notification channel, or user credential uses it. The deletion fails, with 409 in the API, and names what still uses the bridge; remove the bridge from those first.
Keep the pip agent running
The agent reconnects by itself after network interruptions. It exits when connic rejects its token or when the project has no active deployment, so run it under a service manager that starts it again. The Docker examples above restart the container for the same reason. The pip package needs Python 3.11 or later.
macOS (launchd):
python3 -m venv ~/.connic-bridge
~/.connic-bridge/bin/pip install connic-bridgeSave the agent definition with your user name in both paths. KeepAlive starts the agent again whenever it exits, at most once every 30 seconds.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>co.connic.bridge</string>
<key>ProgramArguments</key>
<array>
<string>/Users/you/.connic-bridge/bin/connic-bridge</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>BRIDGE_TOKEN</key>
<string>cbr_your_token_here</string>
<key>ALLOWED_HOSTS</key>
<string>localhost:8080</string>
</dict>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>ThrottleInterval</key>
<integer>30</integer>
<key>StandardErrorPath</key>
<string>/Users/you/Library/Logs/connic-bridge.log</string>
</dict>
</plist>chmod 600 ~/Library/LaunchAgents/co.connic.bridge.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/co.connic.bridge.plist
# Restart after an upgrade
launchctl kickstart -k gui/$(id -u)/co.connic.bridgeA LaunchAgent runs while you are logged in. To run the bridge without a login session, install the same file in /Library/LaunchDaemons and add a UserName key.
Linux (systemd):
Save the settings and the unit, then install and start the agent. Restart=always starts it again after every exit.
BRIDGE_TOKEN=cbr_your_token_here
ALLOWED_HOSTS=localhost:8080[Unit]
Description=connic bridge
Wants=network-online.target
After=network-online.target
[Service]
EnvironmentFile=/etc/connic-bridge.env
ExecStart=/opt/connic-bridge/bin/connic-bridge
Restart=always
RestartSec=30
DynamicUser=yes
[Install]
WantedBy=multi-user.targetsudo python3 -m venv /opt/connic-bridge
sudo /opt/connic-bridge/bin/pip install connic-bridge
sudo chmod 600 /etc/connic-bridge.env
sudo systemctl daemon-reload
sudo systemctl enable --now connic-bridge
journalctl -u connic-bridge -fWhere bridges are used
Connectors
Kafka, RabbitMQ, MQTT, SQS, PostgreSQL, email, and S3 connectors use the bridge of their Connection. Choose it in the Bridge dropdown of the Connection's Network Access section, when you create or edit the Connection from the connector form or under Project Settings → Connections. Every connector that uses the Connection routes through that bridge; to use a different bridge per environment, use a different Connection in each. An outbound HTTP webhook has the Bridge dropdown in its own Network Access section. Leave it set to None to connect directly without a bridge.
The following connector types support bridge access:
- Apache Kafka (inbound and outbound, on the Connection)
- RabbitMQ (inbound and outbound, on the Connection)
- MQTT (inbound and outbound, on the Connection)
- AWS SQS (inbound and outbound, on the Connection)
- PostgreSQL (inbound via LISTEN/NOTIFY, on the Connection)
- Email / IMAP / SMTP (inbound and outbound, on the Connection)
- AWS S3 (file downloads from a custom endpoint, on the Connection)
- HTTP Webhook (outbound callbacks, on the connector)
LLM Providers
For private LLM endpoints (vLLM, Ollama, a LiteLLM proxy, or any OpenAI-compatible server), open Project Settings > LLM Provider, expand the custom provider, and pick a bridge in the Route via Bridge dropdown. Every LLM request from an agent that uses this provider is tunnelled through the bridge.
Tools & Middlewares
Project code (custom tools, middleware, tool hooks, and custom guardrails) can reach private services through a bridge hostname:
<target>.cnc-bridge-<bridge_id>
where target is the hostname of the service inside the private network (e.g. postgres-primary, kafka, billing) and bridge_id is copied from Project Settings > Bridge. Each bridge card has a copyable "Custom-tool host" field.
connic routes connections that use this hostname pattern through the named bridge. Standard Python clients such as psycopg, aiokafka, httpx (sync and async), requests, aiohttp, and redis-py can use the pattern directly:
import psycopg
from aiokafka import AIOKafkaProducer
import httpx
BRIDGE_ID = "abc123" # copy from Project Settings > Bridge
async def lookup_order(order_id: str) -> dict:
# Postgres in a private VPC
with psycopg.connect(
host=f"postgres-primary.cnc-bridge-{BRIDGE_ID}",
port=5432, dbname="orders", user="reader", password="...",
) as conn:
row = conn.execute(
"SELECT data FROM orders WHERE id = %s", (order_id,)
).fetchone()
# Private Kafka topic
producer = AIOKafkaProducer(
bootstrap_servers=f"kafka.cnc-bridge-{BRIDGE_ID}:9092"
)
await producer.start()
await producer.send("order-lookups", order_id.encode())
await producer.stop()
# Private HTTP service
async with httpx.AsyncClient(timeout=30) as client:
r = await client.get(f"http://billing.cnc-bridge-{BRIDGE_ID}/v1/orders/{order_id}")
return {"row": row, "billing": r.json()}A small helper is also available as an explicit alternative to string concatenation:
from connic import bridge_host
host = bridge_host("abc123", "postgres-primary")
# -> "postgres-primary.cnc-bridge-abc123"Services on the bridge machine
A service that only listens on the bridge machine itself, for example on 127.0.0.1:8080, is reached with the target localhost. The bridge opens that connection on its own machine.
import httpx
BRIDGE_ID = "abc123"
async def get_order(order_id: str) -> dict:
# httpx gives up after 5 seconds by default; allow for the slowest call.
async with httpx.AsyncClient(timeout=120) as client:
response = await client.get(
f"http://localhost.cnc-bridge-{BRIDGE_ID}:8080/v1/orders/{order_id}"
)
response.raise_for_status()
return response.json()ALLOWED_HOSTSentries match the exact host and port of the bridge hostname.localhost.cnc-bridge-abc123:8080needslocalhost:8080;127.0.0.1:8080does not match it.- Inside Docker,
localhostis the bridge container. Docker on a Mac runs containers in a virtual machine, so a containerized bridge cannot reach services on the Mac's localhost. Run the pip agent on the Mac instead. - Responses and uploads stream with backpressure in both directions, so large files pass through even when one side reads slowly. This needs connic-bridge 0.1.7 or later.
Automatic routes for discovered endpoints
Some protocols connect to an initial service and receive a different hostname or IP for the next connection. Redis Sentinel, Kafka metadata, and database failover clients commonly work this way. When the magic suffix cannot be added to that returned destination, configure automatic routes under Project Settings > Bridge, or with the authenticated GET/PUT /v1/projects/{project_id}/bridges/{bridge_id}/routes API. API keys need bridges.update for both operations.
{
"routes": [
{
"match_type": "exact",
"target": "redis-sentinel.internal",
"port": 26379
},
{
"match_type": "regex",
"target": "^redis-[a-z0-9-]+\\.internal$",
"port": 6379
}
]
}- Each bridge can have up to 32 routes, with 256 automatic routes total across a project. Every route matches a hostname or IP and one required TCP port.
exactmatches one hostname or IP.regexaccepts a safe, anchored^...$subset with at most one quantified character class, such as[a-z0-9-]+. Groups, lookarounds, backreferences, alternation, braces, unescaped dots, and broad.*patterns are rejected.- Explicit
.cnc-bridge-<bridge_id>hostnames take priority, followed by exact routes and then regex routes. Matches across different bridges fail closed. - Bridge list and detail responses include
route_count. Read route definitions from the dedicated routes endpoint.
Redis Sentinel example
Route the Sentinel service on port 26379 and the possible master hostnames on port 6379, then use the ordinary hostnames in redis-py:
from redis.sentinel import Sentinel
sentinel = Sentinel(
[("redis-sentinel.internal", 26379)],
socket_timeout=1,
)
redis = sentinel.master_for("orders-primary", socket_timeout=1)
# The master hostname returned by Sentinel is routed automatically.
value = redis.get("health")Routing and authorization are separate. If ALLOWED_HOSTS is configured, it must list the Sentinel and every possible master exactly, for example ALLOWED_HOSTS=redis-sentinel.internal:26379,redis-1.internal:6379,redis-2.internal:6379. If Sentinel announces IP addresses, use exact IP routes or a narrowly scoped IP regex instead of the hostname pattern above.
- If the bridge agent has
ALLOWED_HOSTSconfigured, the target host:port must be in that list. Unset or empty allows every target reachable from the bridge's network. - Automatic routes preserve the original hostname for TLS verification. When using an explicit magic hostname, configure SNI /
server_hostnameas the real target if the client verifies certificates. - Automatic routing supports standard synchronous sockets, asyncio, and anyio TCP connections, which covers httpx, requests, and aiohttp. Connections opened later from background threads require the explicit bridge hostname.
- Clients with their own DNS resolver bypass both bridge hostnames and automatic routes. For aiohttp with
aiodnsinstalled, passaiohttp.TCPConnector(resolver=aiohttp.ThreadedResolver()).
MCP Servers
Private MCP servers running inside a VPC, on-prem, or behind a corporate firewall can be reached by setting the bridge field on the server entry in the agent YAML. connic tunnels the Streamable HTTP connection through the bridge and negotiates MCP 2026-07-28 or a supported earlier revision with the server.
mcp_servers:
- name: internal-mcp
url: http://mcp.internal:8080/mcp
bridge: ${INTERNAL_BRIDGE_ID}If the bridge agent has ALLOWED_HOSTS configured, it must include the MCP server's host:port. See Private MCP Servers via Bridge for details.
Channels
Webhook and OpenTelemetry channels have a Bridge field in Project Settings > Notifications. With a bridge selected, drains, notifications, and approval requests reach an endpoint inside your network, such as an OpenTelemetry collector. If the bridge agent has ALLOWED_HOSTS configured, it must include the endpoint's host:port.
Configuration Reference
| Variable | Required | Description |
|---|---|---|
BRIDGE_TOKEN | Yes | Bridge authentication token from the connic dashboard |
ALLOWED_HOSTS | No | Optional comma-separated host:port allowlist. Entries match the exact host:port that connic requests, so localhost:8080 and 127.0.0.1:8080 are different entries. Unset or empty allows every network-reachable target. |
RELAY_URL | No | connic tunnel endpoint (default: wss://relay.connic.co) |
LOG_LEVEL | No | DEBUG, INFO, WARNING, or ERROR (default: INFO) |
Security
- Outbound-only - the bridge never accepts inbound connections. No ports need to be opened.
- Optional allowed hosts - configure exact host:port values to restrict what the bridge can reach. Unset or empty allows every target available from its network.
- Token authentication - each bridge has its own token tied to a single connic project. Tokens can be rotated at any time, and multiple bridges can run in different networks for the same project.
- TLS encryption - communication between the bridge and the connic tunnel endpoint uses WSS (WebSocket over TLS).
Troubleshooting
docker ps) and has outbound internet access. Verify the token is correct and has not been regenerated.ALLOWED_HOSTS environment variable (or --allow flag) of the bridge container and restart it. Entries match exactly, so localhost:8080 does not allow 127.0.0.1:8080.ALLOWED_HOSTS and the bridge logs. Clients of other protocols see the connection close instead.docker exec connic-bridge nc -zv kafka 9092).