Pass-through Adapter

The pass-through adapter is a transparent proxy for AI systems that already expose an OpenAI-compatible endpoint locally. It serves both POST /v1/chat/completions (Chat Completions) and POST /v1/responses (Responses API), forwarding each request to the matching path on your target and returning the response unchanged.

warning

The Responses API path requires spectral-bridge 0.2.0 or later.

Installation

Example

pip install spectral-bridge-adapter-pass-through
# or, with the CLI in a single step:
pip install "spectral-bridge[pass-through]"

Usage

Via the CLI

The simplest way to use the pass-through adapter is through the spectral-bridge CLI. The start command spawns it as a subprocess while connecting the relay client:

Example

spectral-bridge start \
  --adapter  pass-through \
  --target   <local-target-url>

The relay URL defaults to Spectral's relay. If you want to connect to another platform, pass its relay server URL with --relay-url wss://relay.example.com/connect.

Via Docker

The pass-through adapter also ships as a container image that bundles the relay client and the adapter. It runs spectral-bridge start internally, so it is the CLI setup with nothing to install. Container images are available from spectral-bridge 0.3.0 onward.

Example

docker run -d --restart always --read-only --cap-drop ALL \
  -e SPECTRAL_BRIDGE_API_KEY=<your-api-key> \
  -e TARGET_URL=<local-target-url> \
  ghcr.io/principled-intelligence/spectral-bridge:latest

There are no ports to publish: every connection the container makes is outbound (to the relay) or to your target. The flags run it detached and restart it on failure (-d --restart always) with a hardened, read-only filesystem and no Linux capabilities (--read-only --cap-drop ALL).

Configuration is passed through environment variables:

Variable	Description
SPECTRAL_BRIDGE_API_KEY	Relay API key.
TARGET_URL	Local OpenAI-compatible endpoint to proxy.
RELAY_URL	[Optional] Relay server WebSocket URL override (wss://...). Defaults to the Spectral relay.

Standalone

Alternatively, you can run the adapter as a standalone process:

Example

TARGET_URL=<local-target-url> \
  uvicorn \
  spectral_bridge_passthrough.app:app \
  --host 127.0.0.1 \
  --port 8000

Behavior

There is no protocol flag: the adapter serves both endpoints, and the relay client decides which to call per request (it forwards to the path carried in each request frame). A target that implements only one of the two endpoints works fine, since only the endpoint you select is ever called.

The adapter strips hop-by-hop and connection headers (Host, Content-Length, Connection, Transfer-Encoding, etc.) before forwarding. All other headers from the relay client are passed through to the target unchanged.