Bridge Service

WebSocket tunneling service for connecting cloud-deployed Cosmos to on-premises systems behind VPNs and firewalls

bridge

bridgetunnelwebsocketon-premisesvpnproxy

Updated 2026-11-03

Verified 2026-11-03

Repository: cosmos-bridge Language: Go Port: 8109 (server) Registry: in-memory, rebuilt by client reconnects

Overview

The Bridge is a generic HTTP tunnel that enables cloud-deployed Cosmos services to communicate with on-premises systems behind VPNs and firewalls. It consists of two components:

Server (cmd/server) — Deployed on Kubernetes. Accepts WebSocket connections from bridge clients and provides a proxy API for other Cosmos services to route requests through active bridges.
Client (cmd/client) — Standalone binary run on the user's VPN-connected machine. Connects to the server via WebSocket, receives HTTP request descriptors, executes them against local/on-prem endpoints, and returns responses.

Architecture

Bridge tunnel flow

Source

Loading diagram...

The client binary runs on a VPN-connected machine and establishes a persistent WebSocket connection to the bridge server.
When a Cosmos service needs to reach an on-prem system, it POSTs to /api/v1/proxy with the target URL and request details.
The bridge server forwards the request descriptor over the WebSocket to the client.
The client executes the HTTP request locally (where it has network access to the on-prem system) and streams the response back.
If the server restarts, active clients reconnect and repopulate the in-memory registry.

Authentication

Bridge tokens: Cosmos JWTs are validated through User Service JWKS. The CLI can accept a token explicitly or obtain one through browser OAuth2.
JWT validation: Server validates tokens against the User Service JWKS endpoint (/.well-known/jwks.json).
Client auth: Client connects to the WebSocket endpoint with ?token=<bridge-token>.
OAuth client mode: If no token is provided, the CLI can use browser-based Cosmos OAuth2 based on GET /api/v1/auth/config.

API Endpoints

Endpoint	Method	Description
`/health`	GET	Liveness probe
`/ready`	GET	Readiness probe
`/api/v1/proxy`	POST	Proxy HTTP request through a bridge
`/api/v1/bridges`	GET	List active bridges
`/api/v1/bridges/status`	GET	Check if user has active bridge
`/api/v1/bridges/{id}`	DELETE	Disconnect a bridge
`/api/v1/auth/config`	GET	Public OAuth2 configuration for bridge CLI
`/api/v1/releases/{os}/{arch}`	GET	Download client binary
`/api/v1/releases`	GET	List available binaries
`/ws?token=<jwt>`	WebSocket	Bridge client connection

Configuration

Env Variable	Default	Description
`PORT`	`8000`	Server port
`LOG_LEVEL`	`info`	Server log level
`JWKS_URLS`	`http://user-web:8000/.well-known/jwks.json`	Comma-separated JWKS endpoints for JWT validation
`USER_SERVICE_URL`	`http://user-web:8000`	User Service URL. When unset, the server uses the `USER_SERVICE_URLS` entry for `DEFAULT_ENVIRONMENT`.
`USER_SERVICE_URLS`	—	Per-environment User Service URLs: `develop=http://...,uat=http://...`
`DEFAULT_ENVIRONMENT`	`uat`	Environment used to pick defaults from the per-environment maps
`DEFAULT_ORG_ID`	—	Default organization ID. When unset, the server uses the `DEFAULT_ORG_IDS` entry for `DEFAULT_ENVIRONMENT`.
`DEFAULT_ORG_IDS`	—	Per-environment default organization IDs: `develop=<org-id>,uat=<org-id>`
`PROXY_TIMEOUT`	`30`	Proxy request timeout in seconds
`HEARTBEAT_INTERVAL`	`30`	WebSocket heartbeat interval
`MAX_REQUEST_BODY_SIZE`	`10485760`	Max proxied request body size
`BINARIES_DIR`	`/binaries`	Directory containing client binaries
`CORS_ALLOWED_ORIGINS`	`*`	CORS allowed origins
`OAUTH2_AUTH_URL`	—	Default Cosmos OAuth2 base URL for CLI login
`OAUTH2_CLIENT_ID`	—	Default OAuth2 client ID for CLI login
`OAUTH2_ENVS`	—	Per-environment OAuth2 config: `env=url\|client_id\|bridge_url` (bridge URL optional), comma-separated

Client Binary Distribution

Client binaries are cross-compiled for multiple OS/architecture combinations and served directly by the bridge server. Users download the appropriate binary for their platform from the Jumpstart UI or via the API:

Use GET /api/v1/releases to list binaries and GET /api/v1/releases/{os}/{arch} to download the matching client. Older /api/v1/download paths redirect to the releases endpoints.

Supported platforms: darwin/arm64, darwin/amd64, linux/amd64, linux/arm64, windows/amd64.

Client Usage

bash

# macOS (first time — remove quarantine)
chmod +x cosmos-bridge-darwin-arm64
xattr -d com.apple.quarantine cosmos-bridge-darwin-arm64

# Connect to bridge server
./cosmos-bridge-darwin-arm64 --token <bridge-token>

# With custom options
./cosmos-bridge-darwin-arm64 \
  --token <token> \
  --server wss://cosmos.example.com/bridge \
  --insecure \          # Skip TLS for target requests (e.g., self-signed SAP certs)
  --ca-cert /path/to/ca.pem \
  --verbose

Connection Registry

The bridge server keeps active client connections in memory. It stores client ID, user identity, connection time, heartbeat status, and routing metadata for /api/v1/proxy. There is no Redis dependency for bridge connection state; clients reconnect automatically after a server restart.