`th3ist` is a high-performance, zero-dependency Go gateway proxy that provides a standard OpenAI-compatible API (`/v1/chat/completions` and `/v1/models`) backed by the `t3.chat` web backend.
The service is designed to solve two core security constraints enforced by `t3.chat` and its hosting infrastructure (Vercel Edge):
1.**Vercel security checkpoint (TLS fingerprinting)**: Vercel Edge validates incoming TLS Client Hello handshakes (JA3/JA4). Direct HTTP requests originating from non-browser runtimes (Go `net/http`, curl, Python `requests`) trigger an HTML security checkpoint (`HTTP 429` / `HTTP 403`).
2.**hCaptcha Enterprise protection**: The `t3.chat` backend requires a valid, unconsumed single-use hCaptcha token on every guest request.
`th3ist` solves both challenges using an isolated, in-process **Browser Bridge Engine** that coordinates with a private Chromium instance via Chrome DevTools Protocol (CDP).
The `BrowserBridge` manages an active, isolated Chromium instance over standard Chrome DevTools Protocol (CDP) WebSocket framing implemented directly in pure Go standard library.
#### Lifecycle & startup
- **Dynamic port allocation**: Uses `getFreePort()` to bind to an available local TCP port on `127.0.0.1`, preventing port conflicts with other tools or existing Chrome debug sessions.
- **Isolated user data directory**: Generates a dedicated temporary directory (`/tmp/th3ist_bridge_*`) on startup via `os.MkdirTemp`.
- **Automatic cleanup**: On shutdown or bridge termination, `bb.cleanup()` kills the browser process and deletes the temporary directory via `os.RemoveAll`.
#### Launch arguments & offscreen rendering
```go
args:=[]string{
"--window-position=-3000,-3000",
"--window-size=1280,800",
"--remote-debugging-port="+port,
"--user-data-dir="+tmpDir,
"--disable-gpu",
"--no-sandbox",
"--no-first-run",
"--no-default-browser-check",
"--disable-extensions",
"--disable-default-apps",
"https://t3.chat",
}
```
- **Offscreen positioning (`-3000, -3000`)**: Keeps the browser window completely off the visible desktop area without taking focus, stealing cursor input, or disrupting user workflow.
- Tiling window managers (i3, bspwm, sway, dwm) can capture offscreen windows on the main display. `th3ist` provides `-xvfb` to automatically launch and attach to a virtual X server (`Xvfb :<free_display> -screen 0 1280x800x24`), ensuring 100% isolation from the desktop environment.
- Users can also supply a custom `-display :99` (for existing `Xvfb`, `Xephyr`, or `Xnest` sessions).
- Sets window class `--class=th3ist_hidden` and `--app=https://t3.chat` for easy floating/scratchpad filtering.
- **Headless detection evasion**: Running in an active display context (real or virtual Xvfb) prevents hCaptcha Enterprise's client heuristics from detecting headless browser environments, ensuring automated invisible token generation succeeds.
- **Strict headless fallback (`-headless`)**: When the `-headless` flag is passed or when `DISPLAY` is unset (e.g. Docker or server environments), it automatically uses `--headless=new`.
#### Why Chromium stays active for upstream requests (TLS fingerprinting vs. captcha)
An important architectural nuance is that Chromium is required for **both** token generation and request dispatch:
1.**Single-use token lifecycle**: `t3.chat` backend invalidates the hCaptcha token upon every single completion. Each new chat prompt or message requires a freshly generated token.
2.**Vercel Edge JA3/JA4 TLS checkpoint**: Even when provided with a 100% valid token and session cookies, any direct HTTP request initiated outside of Chromium (e.g., via Go `net/http`, Node.js `fetch()`, curl) is intercepted by Vercel Edge with `HTTP 429: Vercel Security Checkpoint` because non-browser TLS handshakes do not match Chromium's TLS Client Hello signature.
3.**Zero-overhead persistence**: Rather than launching and killing a browser process on every single prompt (which adds 3-5s cold-start latency), `th3ist` maintains a single, lightweight offscreen Chromium instance. Incoming completion requests execute `fetch()` and mint tokens concurrently inside the existing page context with sub-300ms latency.
- In non-streaming mode: `<tool_call>...</tool_call>` XML and raw JSON blocks are extracted via `DetectToolCalls()`, populating `choice.Message.ToolCalls` with `ID: "call_..."`, `Type: "function"`, `Function: { Name: "...", Arguments: "..." }`, while cleaning tool call tags out of `Content`.
- In streaming mode: `StreamToolCallFilter` intercepts `<tool_call>` blocks in real-time, preventing them from leaking into `delta.content`, and emits standard OpenAI `delta.tool_calls` chunks followed by `finish_reason: "tool_calls"`.
1.`StreamThinkingFilter`: Stateful filter intercepting `<think>...</think>` tags and routing to `reasoning_content`.
2.`StreamToolCallFilter`: Stateful filter intercepting `<tool_call>...</tool_call>` tags, preventing raw XML leaks in `content` and emitting OpenAI `delta.tool_calls`.
3. Flushes `data: [DONE]` on stream termination.
---
### 3.5. Token ingestion API
To allow external token management or custom API keys:
- **Inspect active credentials**:
```http
GET /v1/token
```
Returns masked session cookies, active deployment ID, and token status.
- **Push fresh token / credentials**:
```http
POST /v1/token
Content-Type: application/json
{
"hcaptchaToken": "<new-token>",
"cookie": "<optional-new-cookie>",
"deploymentId": "dpl_...",
"clientContext": "..."
}
```
- **Per-request header overrides**:
- `X-Hcaptcha-Token`: Override token for a single completion request.
- **Client errors (`400`, `401`, `403`)**: Non-transient errors (such as `captcha_failed` or `invalid_params`) bypass retry loops and return immediately in `<300ms` with original error bodies and HTTP status codes.
- **Server errors (`5xx`)**: Direct HTTP fallback requests utilize `DoWithFibonacciRetry` with bounded Fibonacci delays (1s, 1s, 2s, 3s, 5s) before failing.
Empirical testing confirmed that rate limiting on `t3.chat` is **tracked strictly per FingerprintJS visitor ID (`t3-anon-visitor`)**, rather than by IP address:
#### 1. How visitor identities are minted (`/api/identity`)
- `t3.chat` loads `assets/fp.esm-*.js` to collect 42 hardware entropy components: canvas 2D render geometry, AudioContext base latency, WebGL parameters, CPU hardware concurrency, and screen dimensions.
- The browser submits `{ fingerprint: { visitorId, confidence, components, version } }` to `/api/identity`.
- The server evaluates the component entropy and signs an HMAC cookie:
- **Audio entropy**: Adds subtle jitter to `AudioContext` frequency responses.
- **Hardware concurrency & resolution**: Mutates CPU core counts (4, 6, 8, 12, 16) and screen resolutions.
- Submits the modified components to `/api/identity`, which returns:
```json
{
"visitorId": "visitor_<fresh_hash>",
"requiresSignIn": false,
"confidence": 1
}
```
- **Zero-downtime auto-recovery**: If `ExecuteFetch()` receives an `HTTP 429 ratelimit_hit`, it automatically invokes `RotateIdentity()`, mints a fresh hCaptcha token, and retries the completion request transparently.
#### 3. Bypassing guest limits via BYOK (bring your own key)
`th3ist` also supports passing custom provider API keys directly in standard OpenAI format:
`th3ist` automatically detects the provider (`sk-ant-` -> Anthropic, `sk-or-` -> OpenRouter, `AIza` -> Google, `sk-` -> OpenAI) and attaches the key to the upstream `T3ChatPayload`, completely bypassing anonymous guest quotas and captcha requirements.
---
## 4. Source file index
| File | Purpose |
|------|---------|
| [`th3ist.go`](file:///home/lux/ditch/th3ist/th3ist.go) | Main server, BrowserBridge implementation, CDP protocol handler, stream parsers, tool calling converter, and HTTP handlers. |
| [`th3ist_test.go`](file:///home/lux/ditch/th3ist/th3ist_test.go) | Unit test suite covering message transforms, thinking tag filters, tool calling detection, mock upstream completions, and live bridge tests. |
| [`Makefile`](file:///home/lux/ditch/th3ist/Makefile) | Build, test, run, and cleanup targets. |
| [`README.md`](file:///home/lux/ditch/th3ist/README.md) | User documentation, quickstart guide, CLI flags, and API examples. |
