th3ist: Free OpenAI-compatible gateway for t3.chat

th3ist is a zero-dependency, standalone Go proxy gateway that exposes an OpenAI-compatible HTTP interface (/v1/chat/completions and /v1/models) backed by the t3.chat API.

Features

• Standard OpenAI interface: Serves /v1/chat/completions and /v1/models (with /chat/completions and /models aliases).
• Dual-engine architecture (Browser Bridge enabled by default):
  • Browser bridge (-auto-capture, default: true): Routes upstream requests directly through a private, stealth offscreen Chromium session over CDP with automatic virtual X server (Xvfb) isolation. This ensures a 100% genuine Chrome TLS handshake (JA3/JA4), completely bypassing Vercel Security Checkpoints and WAF blocks out of the box.
  • Direct HTTP client (-direct / -no-bridge): Fallback mode for high-throughput environments where valid Vercel clearance cookies and tokens are supplied directly.
• Real-time per-token streaming: Streams tokens in real time over CDP via Runtime.addBinding and ReadableStreamDefaultReader, passing token chunks immediately through stateful thinking and tool call filters without buffering.
• Automated hardware fingerprint rotation & 429 auto-recovery: Dynamically discovers FingerprintJS entropy modules (or generates high-entropy synthetic fallbacks) and auto-rotates visitor identities upon encountering HTTP 429 / rate limits, retrying immediately (up to 4 attempts) without dropping client connections.
• Private & anti-fingerprinting stealth:
  • 100% isolated session: Launches in --incognito mode with a temporary ephemeral user profile and --disable-extensions, completely segregated from any existing Chromium/Chrome windows, history, extensions, or sessions.
  • Auto-managed virtual display (-xvfb, default: true): Spawns an isolated Xvfb display to completely isolate Chromium from tiling window managers (i3, bspwm, sway, dwm).
  • Zero port collisions: Binds to a dynamically allocated ephemeral loopback port for CDP commands.
  • Stealth & anti-detection:
    • Disables Blink automation features (--disable-blink-features=AutomationControlled).
    • Masks navigator.webdriver to undefined via Page.addScriptToEvaluateOnNewDocument.
    • Normalizes window.chrome, navigator.languages, and navigator.plugins.
    • Sets desktop viewport (--window-size=1920,1080) and custom User-Agent.
    • Strips telemetry, domain reliability, crash reporting, and sync.
• Dynamic token ingestion API: Provides GET /v1/token and POST /v1/token to inspect or hot-reload single-use hCaptcha tokens and cookies on the fly without restarting the server.
• Fast fail & clear error propagation: Non-transient errors (such as captcha_failed or invalid_params) return immediately (<300ms) without wasting time in exponential backoff retry loops.
• Reasoning content separation: Parses <think>...</think> tags and upstream reasoning chunks into reasoning_content deltas / message fields.
• Function / tool calling translation: Injects tool schemas into system instructions, maps multi-turn tool calling history, and parses model tool invocations into standard OpenAI tool_calls.
• Zero external dependencies: Implemented using pure Go standard library.

Installation

go install code.luxferre.top/luxferre/th3ist@latest

Building from source

make build

Binary will be produced at bin/th3ist.

Running

# Run with default settings (Browser Bridge and isolated Xvfb active)
./bin/th3ist

# Run on a custom port with static defaults
./bin/th3ist -port 9000 -default-model gemini-3.5-flash-lite

# Run in direct HTTP client mode (bypasses browser bridge)
./bin/th3ist -direct

CLI flags

Flag	Description	Default
-auto-capture	Enable private browser bridge (bypasses Vercel TLS & mints fresh tokens)	true
-direct / -no-bridge	Disable browser bridge and run in direct HTTP mode	false
-xvfb / -Xvfb	Automatically spawn and manage an isolated virtual X server (Xvfb) for complete isolation from tiling window managers	true
-no-xvfb	Disable automatic virtual X server (uses active $DISPLAY)	false
-display	Custom X11 DISPLAY to attach Chromium to (e.g. :99 for an existing Xvfb / Xephyr / Xnest session)	(auto / $DISPLAY)
-headless	Force strict headless mode --headless=new (defaults to offscreen window when display is present)	false
-browser-bin	Custom path to Chromium/Google Chrome binary	(auto-detected)
-port	Port to listen on	8080
-endpoint	Upstream T3 chat endpoint	https://t3.chat/api/chat
-default-model	Default model identifier	gemini-3.5-flash-lite
-cookie	Cookie string to pass upstream	""
-hcaptcha-token	hCaptcha token to pass upstream	""
-deployment-id	x-deployment-id header value	""
-client-context	x-client-context header value	""
-user-agent / -ua	User-Agent string sent upstream	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36

Tiled window managers & virtual display isolation

On tiling window managers (e.g., i3, bspwm, sway, dwm, awesome, hyprland, xmonad), th3ist defaults to managing an isolated virtual X server (-xvfb) so that no Chromium windows appear on your desktop workspace:

1. Option A: Auto-managed Xvfb (Default): Install xorg-server-xvfb (or Xfbdev):

   • Void Linux: sudo xbps-install -S xorg-server-xvfb
   • Debian / Ubuntu: sudo apt install xvfb
   • Arch Linux: sudo pacman -S xorg-server-xvfb

   th3ist will automatically allocate an isolated virtual display (e.g. :99), launch Xvfb, attach Chromium to it, and cleanly terminate Xvfb on exit.

2. Option B: Manual virtual X server (Xvfb, Xephyr, or Xnest):

   # Start virtual framebuffer in background
   Xvfb :99 -screen 0 1280x800x24 -ac &
   
   # Run th3ist attached to display :99
   ./bin/th3ist -display :99 -port 9000
   

3. Option C: Tiling window manager rules (--class=th3ist_hidden): Chromium is launched with --class=th3ist_hidden and --app=https://t3.chat. You can add a floating/hidden rule to your window manager config:

   • i3/sway: for_window [class="th3ist_hidden"] floating enable, move scratchpad
   • bspwm: bspc rule -a th3ist_hidden state=floating hidden=on

Token ingestion API

t3.chat protects /api/chat with single-use hCaptcha tokens. You can inspect or hot-reload tokens live:

• Inspect current credentials:

  curl http://localhost:8080/v1/token
  

• Push fresh hCaptcha token:

  curl -X POST http://localhost:8080/v1/token \
    -H "Content-Type: application/json" \
    -d '{
      "hcaptchaToken": "<new-unconsumed-hcaptcha-token>",
      "cookie": "<optional-new-cookie-string>"
    }'
  

Per-request header overrides

You can also override credentials per request:

• X-Hcaptcha-Token: supply a fresh hCaptcha token for a single request.
• X-Cookie / Cookie / Authorization: Bearer <cookie-string>: override upstream cookies.
• X-Deployment-Id: override x-deployment-id.
• X-Client-Context: override x-client-context.
• X-User-Agent: override upstream User-Agent.

Usage examples

1. List models

curl http://localhost:8080/v1/models

2. Chat completion (non-streaming)

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash-lite",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

3. Chat completion (streaming)

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash-lite",
    "messages": [
      {"role": "user", "content": "Tell me a short joke."}
    ],
    "stream": true
  }'

4. Tool / function calling

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash-lite",
    "messages": [
      {"role": "user", "content": "What is the weather in Tokyo?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

5. Using with official OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
  base_url="http://localhost:8080/v1",
  api_key="not-needed"
)

response = client.chat.completions.create(
  model="gemini-3.5-flash-lite",
  messages=[
    {"role": "user", "content": "Write a quick hello world in Go"}
  ],
  stream=True
)

for chunk in response:
  if chunk.choices[0].delta.content:
    print(chunk.choices[0].delta.content, end="", flush=True)
print()

Credits

Created by Luxferre in 2026, released into the public domain with no warranties.