venice-bridge

venice-bridge is a free, open-source local bridge for macOS that lets OpenCode, Claude Code, Codex CLI and other OpenAI- or Anthropic-compatible coding agents use a venice.ai web subscription, with working tool calls.

It is two small local processes. The bridge (venice_bridge.py, about 2,400 lines, plus tolerant_parser.py) runs an HTTP server on 127.0.0.1:18891 that speaks OpenAI Chat Completions, and forwards each request to the backend of the venice.ai web app, authenticated with your own browser login. The optional adapter (venice_adapters.py, standard library only) runs on 127.0.0.1:18892 and translates the Anthropic Messages and OpenAI Responses APIs to Chat Completions, so Claude Code and Codex CLI work too. It does not use the paid Venice API and needs no API key.

Disclaimer: unofficial, read before use
  • Unofficial. Not affiliated with, endorsed by, or supported by Venice.ai.
  • Undocumented endpoints. It talks to the web app's own backend, which can change or break at any time.
  • Terms-of-service risk. It automates your own logged-in web session; that may be against Venice's terms of service. You use it at your own risk.
  • Your own account only. Do not share cookies or accounts. The cookie is a live credential for your Venice account: never commit it, never share it.

OpenAI and Anthropic APIs

Bridge: POST /v1/chat/completions, GET /v1/models, GET /health, POST /reload. Adapter: POST /v1/messages and POST /v1/responses.

Working tool calls

Venice's web routes hide client tools from the model, so the bridge emulates them in text and returns real OpenAI tool_calls.

Web subscription, no API key

Uses the __client cookie of clerk.venice.ai. Tested on a paid Venice web plan (Pro). Limited by requests per day, not tokens.

Local models too

ollama/<model>, lmstudio/<id> or your own backend: passed straight through, no Venice login, no quota.

Honest limits

macOS only so far. No images. With tools, short replies are sent only when complete. Open models sometimes need a retry.

Model quality

Venice's fast models are weak at long agentic chains. In a small test of 5 one-tool runs per model through Claude Code, none of the three fast models produced a clean correct final answer every time, and one invented a cited weather report (one machine, one account). Good for cheap exploratory runs, not for high-stakes work.

What's new

Full history: CHANGELOG.md · Releases · PyPI

v0.2.6 2026-11-21

  • Double-encoded Bash.command regex fallback: unwraps {"command": "..."} even when unescaped inner shell double quotes break JSON parsing.
  • Control-character restoration in Bash.command: restores JSON-decoded \x08/\x0c back to \b/\f and strips stray C0 control characters so Claude Code's Zod validator no longer rejects regex commands.

v0.2.5 2026-11-21

  • No more auto web-search hijacking: explicitly sends webEnabled: false, webScrapeEnabled: false, and xSearchEnabled: false unless :web / :xsearch is requested.
  • Claude Code 2.1.329 tool-schema parity: maps snake_case arguments (file_path, old_string, new_string, replace_all, run_in_background, skill) and Agent alongside Task.
  • New tool routing aliases: sql_query / sqlite_query → read-only sqlite3 on Bash, get_current_date → date -u, deferred grep/glob → Bash, plus double-encoded command unwrapping and removal of literal example_tool from the reminder prompt.
  • claude-venice --resume fix: pairs --dangerously-skip-permissions with --permission-mode bypassPermissions so resumed sessions stay autonomous (optional short alias: cv).

v0.2.4 2026-11-21

  • Images and documents in chat (OpenAI, Anthropic and Responses formats, base64 only, 17 file types).
  • Speech-to-text at /v1/audio/transcriptions (no quota) and image generation at /v1/images/generations.
  • tool_choice, parallel_tool_calls, response_format, stop, Anthropic thinking blocks.
  • Proactive session-token refresh, GET /stats, and an opt-in multi-account cookie pool.

v0.2.3 2026-11-21

  • Runaway loops are cut. In tool mode a reply with more than 40 tool calls or 150,000 characters is cut at a call boundary instead of streaming for minutes (VENICE_BRIDGE_LOOP_MAX_CALLS, VENICE_BRIDGE_LOOP_MAX_CHARS).
  • Code written instead of run goes to the judge: a reply with no tool call that only shows a code block, while a shell tool is declared.
  • bash_tool reaches the shell tool.
  • claude-venice --lean starts Claude Code with no MCP servers.
  • A "when to use venice-bridge vs local vs paid" section.

v0.2.2 2026-11-21

  • Bare-string tool calls are no longer dropped. A bare string reply reaches the bridge as {"content": "..."}; when the tool has no content parameter and exactly one required string parameter, the string goes there.
  • This "What's new" section and a changelog.

v0.2.1 2026-11-21

  • Double-nested tool arguments are unwrapped ({"arguments": {...}}, {"input": {...}}, a JSON string in arguments), so the inner command is no longer dropped.
  • The format reminder asks for parameters directly in arguments and a heredoc for multi-line SQL or Python.
  • On PyPI: pipx install venice-bridge gives venice-bridge, venice-adapters and claude-venice.

v0.2.0 2026-11-21

  • Claude Code and Codex CLI through the adapter (127.0.0.1:18892), and the claude-venice launcher.
  • Local models by prefix (ollama/, lmstudio/, backends.json) and the venice-auto fallback model.
  • Opt-in web search (:web, :xsearch) and reasoning (:think); response cache.

Screenshots

Terminal: the offline self-check passes; GET /health returns ok true with the remaining chat quota; a chat completion answers PONG
Self-check, health check with the remaining chat quota, and a first chat completion.
Terminal: a request that declares a read tool; the model's plain-text JSON reply comes back from the bridge as an OpenAI tool_calls message with finish_reason tool_calls
A model's plain-text reply becomes a real OpenAI tool_calls message.
Terminal: an Anthropic Messages request to the adapter on port 18892 that declares a Read tool comes back as a tool_use block with stop_reason tool_use
The adapter answers Claude Code in Anthropic's shape: a tool_use block.

Requirements

  • macOS. The bridge streams through the system curl, which passes Cloudflare. Linux and Windows are untested.
  • Python 3.10+ and curl_cffi (pip install curl_cffi).
  • A venice.ai web account, logged in in your browser. Everything was tested on a paid plan (Pro). The agent route needs a paid plan (a free account gets 403 creator_access_required); a free account has a very small chat quota.
  • A client: OpenCode or any client that speaks OpenAI Chat Completions (bridge only); the Claude Code CLI or Codex CLI (bridge plus adapter).

The adapter needs nothing beyond the Python standard library. The claude-venice launcher is a bash script and needs claude and curl on your PATH.

Quick start

1. Get the code and the dependency

git clone https://github.com/nsozturk/venice-bridge.git
cd venice-bridge
pip install curl_cffi

Or install the commands venice-bridge, venice-adapters and claude-venice from PyPI: pipx install venice-bridge.

2. Save your login cookie (the only setup step)

The bridge needs the value of the __client cookie of clerk.venice.ai, a long-lived Clerk cookie. From it the bridge mints a session JWT of about 60 seconds and a client attestation for every request window.

  1. Log in on venice.ai in Chrome.
  2. Open DevTools, then Application → Cookies → https://clerk.venice.ai.
  3. Copy the Value of __client, then run:
mkdir -p ~/.config/venice-bridge && pbpaste > ~/.config/venice-bridge/client-cookie.txt && chmod 600 ~/.config/venice-bridge/client-cookie.txt

The file may hold the bare value or a pasted __client=...; string. Override its path with VENICE_BRIDGE_COOKIE_FILE. Clerk rotates the cookie while it is used; the bridge saves the rotated value to ~/.config/venice-bridge/rotated-client.json (mode 0600, override with VENICE_BRIDGE_CLIENT_FILE).

Optional second source: a local session daemon. Set VENICE_BRIDGE_SESSION_DIR to a folder containing a client.py that exposes get_session(domain) returning {"timestamp": <ms>, "tokens": {"clerk_client": "<value>"}}. The cookie file wins when both are present.

3. Run the bridge

python3 venice_bridge.py                 # default 127.0.0.1:18891
python3 venice_bridge.py --host 127.0.0.1 --port 18891

It prints [+] Venice AI Bridge listening on http://127.0.0.1:18891/v1. Logs go to stderr. VENICE_BRIDGE_HOST sets the bind address too; keep it on 127.0.0.1: the bridge has no authentication of its own.

For Claude Code or Codex CLI, also start the adapter in a second terminal:

python3 venice_adapters.py               # default 127.0.0.1:18892, forwards to the bridge

4. Check it

curl -s http://127.0.0.1:18891/health

A working login answers {"ok": true, "venice_session": "active", "chat_quota": {...}} with the remaining web chat quota. An offline self-check needs no network:

python3 test_venice_bridge.py     # prints: cookie file ok, session ok, ok, end to end ok, local backends ok, reasoning + venice-auto prefix ok
python3 test_venice_adapters.py   # prints: messages ok, pick_model ok, responses ok

See Tests for what they cover.

5. Add the provider to OpenCode

Copy the provider block from examples/opencode.json into ~/.config/opencode/opencode.json (or a project opencode.json). Shortened to one model it looks like this:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "venice-bridge": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Venice Web (local bridge)",
      "options": {
        "baseURL": "http://127.0.0.1:18891/v1",
        "apiKey": "local"
      },
      "models": {
        "deepseek-v4-1-flash-uncensored": {
          "name": "DeepSeek V4.1 Flash Uncensored (Venice Web)",
          "modalities": { "input": ["text"], "output": ["text"] },
          "limit": { "context": 524288, "output": 131072 }
        }
      }
    }
  }
}

The example config lists deepseek-v4-1-flash-uncensored, deepseek-v4-1-flash, z-ai-glm-5-3-flash, kimi-k2-5, default, qwen3-coder-480b-a35b-instruct-turbo, qwen3-6-27b, zai-org-glm-5.2 and venice-uncensored-1-2. GET /v1/models lists whatever your account's web catalogue offers without credits, plus the virtual venice-auto model.

6. First run

opencode -m venice-bridge/deepseek-v4-1-flash-uncensored

Any other OpenAI-compatible client works with base URL http://127.0.0.1:18891/v1 and any API key. For Claude Code see Claude Code (claude-venice), for Codex see Codex CLI.

Autostart (launchd)

examples/com.example.venice-bridge.plist is a launchd template. It starts the bridge at login (RunAtLoad), restarts it when it exits (KeepAlive, at most once per 60 s via ThrottleInterval) and writes stdout and stderr to venice_bridge.log in the repository folder.

  1. Replace every /PATH/TO in the file with real absolute paths (your python3 and the repository folder).
  2. Copy it to ~/Library/LaunchAgents/.
  3. Load it:
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.venice-bridge.plist

The adapter has its own template, examples/com.example.venice-adapters.plist, with the same settings; it logs to venice_adapters.log.

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.venice-adapters.plist

Claude Code (claude-venice)

claude-venice is a bash launcher in the repository root. It runs the Claude Code CLI against the adapter in an isolated profile, ~/.claude-venice (CLAUDE_CONFIG_DIR), so your normal claude install, its login and its settings are not touched. It unsets ANTHROPIC_API_KEY, sets ANTHROPIC_BASE_URL=http://127.0.0.1:18892 and a filler ANTHROPIC_AUTH_TOKEN, and points ANTHROPIC_MODEL and the opus/sonnet/haiku default-model variables at the chosen Venice model id.

Warning: claude-venice skips permission prompts by default

It adds --dangerously-skip-permissions --permission-mode bypassPermissions to every run (including --resume sessions previously saved in default mode), so Claude Code runs tools (shell commands, file edits) without asking you. The reason: Venice's fast models cannot drive Claude Code's auto-mode safety classifier, which then blocks with "Auto mode could not evaluate this action and is blocking it for safety". Run it only in a folder you are ready to lose changes in.

To turn it off, set VENICE_CLAUDE_SKIP_PERMS=0, or pass your own --permission-mode; either way the normal prompts or your chosen mode apply.

Install

ln -s "$PWD/claude-venice" ~/.local/bin/claude-venice   # or run ./claude-venice from the repository

Usage

claude-venice                                          # default model deepseek-v4-1-flash-uncensored
claude-venice --lean                                   # disable MCP servers (--strict-mcp-config)
claude-venice -m <venice-model-id>                     # -m and --lean work anywhere before --
claude-venice --resume <session-id>                    # resumes in bypassPermissions mode
claude-venice --models                                 # list the model ids the bridge serves
claude-venice --quota                                  # remaining web quota and cache stats
VENICE_CLAUDE_MODEL=<venice-model-id> claude-venice
claude-venice -m deepseek-v4-1-flash-uncensored:web    # with Venice web search, see below
VENICE_CLAUDE_SKIP_PERMS=0 claude-venice               # keep the permission prompts

Before it starts Claude Code it checks both /health endpoints (bridge on 18891, adapter on 18892, both fixed in the script) and that the Venice session is active, and warns when fewer than 500 requests of the daily quota are left. Other arguments go to claude unchanged.

Codex CLI

Codex CLI talks to the adapter's /v1/responses. The provider is passed on the command line, so nothing is written to ~/.codex:

VB_KEY=local codex exec --skip-git-repo-check -c 'model_providers.vb={name="vb",base_url="http://127.0.0.1:18892/v1",wire_api="responses",env_key="VB_KEY"}' -c model_provider=vb -m deepseek-v4-1-flash-uncensored "<task>"

Measured with Codex CLI 0.163.0: it ran exec_command and answered. Limits: Codex's namespace tools (MCP servers, multi-agent) and its built-in web_search do not pass through. A model id the bridge does not list (for example a gpt-... id) is replaced by the adapter's default model (VENICE_ADAPTER_MODEL); an id with a / (a local backend/model) is passed through and never falls back to Venice.

Local models

A model id <backend>/<model>, for example ollama/qwen3:8b or lmstudio/<id>, is passed straight to that local OpenAI-compatible server: no Venice login, no tool emulation, no quota, no response cache. Only the prefix is removed from the model id; a leading venice-bridge/ is stripped first. The route is chosen by the prefix alone: a local-prefixed model whose backend is down answers 502 (type local_backend_error) and never falls through to Venice.

PrefixDefault base URL
ollama/http://127.0.0.1:11434/v1
lmstudio/http://127.0.0.1:1234/v1

Add llama.cpp, MLX or other servers in ~/.config/venice-bridge/backends.json (path override VENICE_BRIDGE_BACKENDS). A file replaces the defaults, so list them again if you want them; an empty list turns local backends off. The file is read per request. examples/backends.json is a starting point:

{"backends": [
  {"name": "ollama",   "base_url": "http://127.0.0.1:11434/v1"},
  {"name": "lmstudio", "base_url": "http://127.0.0.1:1234/v1"},
  {"name": "llamacpp", "base_url": "http://127.0.0.1:8080/v1", "api_key": null}
]}

GET /v1/models returns the Venice models plus the models of every reachable local backend (as <backend>/<id>, owned_by the backend name). A backend that is down is skipped and never breaks the list.

Model list and venice-auto

GET /v1/models lists only the Venice models your web subscription covers. Models that cost credits (usesCredits: true in Venice's catalogue) are hidden, and end-to-end-encrypted models (e2ee-*) are always hidden, because they need client-side keys the bridge does not handle. VENICE_EXCLUDE_MODELS hides more, as comma-separated glob patterns (for example qwen3-vl-*,venice-uncensored-*). The filter only changes the list: a hidden model can still be requested by its id.

The list starts with one virtual id, venice-auto. It resolves to the first Venice id in VENICE_AUTO_MODELS (comma-separated, default deepseek-v4-1-flash-uncensored,ollama/qwen3:8b). While the bridge knows the daily web quota is used up, it resolves to the first local <backend>/<model> entry instead, until the reset time Venice reports. The fallback is local only because the web quota is plan-wide: every Venice model shares it, so another Venice model would fail the same way.

opencode -m venice-bridge/venice-auto      # add "venice-auto" to the models block of your OpenCode config
claude-venice -m venice-auto               # works through the adapter, because venice-auto is in the model list
  • The bridge learns that the quota is gone from a failed request, so the request that hits the limit still fails once (403 venice_quota_exhausted); the requests after it go to the local model.
  • The local backend must be running, or the request answers 502 (local_backend_error). Without a local entry in VENICE_AUTO_MODELS there is no fallback and the quota error stays.
  • A suffix (venice-auto:think, venice-auto:web) is kept for the Venice model and dropped for the local one.
  • The over-quota state lives in memory. POST /reload and a restart clear it; when Venice reports no reset time, the bridge asks again after about a minute.
  • A local model is not a Venice model: expect different quality, speed and context size.

Reasoning (opt-in)

Venice's reasoning models can return their chain of thought. It is off by default, and a thinking turn is made only on the chat route and only for requests that declare no tools.

HowScope
Model suffix :think (also :reason, :reasoning), combinable: deepseek-v4-1-flash-uncensored:web:thinkone request
VENICE_REASONING=1 in the bridge's environmentwhole process
reasoning_effort medium or high (none, minimal, low or unset = off)one request

The chain of thought comes back as OpenAI reasoning_content: a field on the message (non-stream) and delta.reasoning_content chunks (stream), sent before the normal content. On a thinking turn the bridge also lets Venice include its own system prompt, as the official web client does; without it the chat route returns no reasoning.

With tools in the request, :think and VENICE_REASONING=1 are ignored, because a reasoning turn makes the model expect its reasoning_content passed back on the next turn, which coding agents do not do (HTTP 400). OpenCode, Claude Code and Codex always send tools, so :think has no effect in their agent loops; it is for plain chat and scripts. The same holds for reasoning_effort: with tools in the request it is ignored and nothing about reasoning is sent to Venice. The adapter does not forward a reasoning effort.

curl -s http://127.0.0.1:18891/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-1-flash-uncensored:think","messages":[{"role":"user","content":"Is 1001 prime?"}]}'

Response cache

A byte-identical repeat request (same model, messages, tools and parameters; stream aside) is answered from an in-memory LRU cache with a time limit, without a Venice call. Only clean successes (a real answer or a tool call) are stored. A stored non-stream result can replay as a stream and the reverse. The hit rate is modest by design: agent turns rarely repeat verbatim, so it mostly catches exact retries. Requests to local backends are not cached.

VariableDefaultMeaning
VENICE_BRIDGE_CACHEon0 disables the cache.
VENICE_BRIDGE_CACHE_MAX256Maximum entries.
VENICE_BRIDGE_CACHE_TTL3600Seconds an entry stays valid.

GET /health reports cache: {hits, misses, stores, entries, enabled}; a hit is logged as cache hit (no Venice call spent).

Quota and cost model

The Venice web plan is limited by a daily request quota, not by tokens. Fewer requests save quota; shorter prompts do not.

  • usage numbers are an estimate of about 4 characters per token, because Venice returns no token counts. The adapter's /v1/messages/count_tokens uses the same estimate, and the adapter reports cached_tokens: 0.
  • GET /health shows chat_quota.remaining and resets_in_min; claude-venice --quota prints them with the cache stats.
  • In-bridge retries and the judge are extra requests; the response cache saves one on an exact repeat.
  • When the quota is used up the bridge answers 403 venice_quota_exhausted with the reset time, without calling Venice (see Error mapping).
  • The quota is plan-wide: every Venice model shares it. To keep working after it runs out, use venice-auto with a local fallback.
curl -s http://127.0.0.1:18891/health

How it works

Request flow. Both inference routes are routes of the venice.ai web app itself; VENICE_BRIDGE_ROUTE chooses between them.

The bridge reads the __client cookie, finds the active Clerk session, mints a short-lived session JWT and a client attestation, and streams the reply from the Venice route chosen by VENICE_BRIDGE_ROUTE. A 401 from Venice is retried once with a fresh JWT and attestation. A model id with a local backend prefix skips all of this and goes to that backend (see Local models).

Two processes

Two processes: the bridge does all the Venice work; the optional adapter only translates APIs for clients that do not speak Chat Completions.

OpenCode and other OpenAI clients talk to the bridge directly; the adapter's upstream (VENICE_ADAPTER_UPSTREAM) can be any Chat Completions server.

ProcessFileDefault addressSpeaks
Bridgevenice_bridge.py127.0.0.1:18891OpenAI Chat Completions POST /v1/chat/completions, GET /v1/models, GET /health, POST /reload
Adapter (optional)venice_adapters.py127.0.0.1:18892Anthropic Messages POST /v1/messages (+ /v1/messages/count_tokens), OpenAI Responses POST /v1/responses, GET /v1/models, GET /health

Settings sent to Venice

On the plain chat route, temperature and top_p are forwarded when the client sets them; otherwise Venice's own defaults apply. max_tokens is ignored by the route. Reasoning is off by default. A thinking turn is made only when asked for (:think, VENICE_REASONING=1 or reasoning_effort medium / high) and only when the request declares no tools (see Reasoning), because reasoning models want reasoning_content passed back on tool turns, which most clients do not do (HTTP 400), so a request with tools never gets reasoning, whatever it asks for. Always sent: large-context chat on. Venice's own system prompt is off, except on a thinking turn.

Routes

Routes: VENICE_BRIDGE_ROUTE is auto (default), chat or agent. The chat route is the default path because Venice runs no agent loop there and gives the model no tools of its own, so nothing collides with the client's tools and no call is swallowed.

SettingRouteWhat happens
auto (default)chat, agent as fallbackUses the chat route. If Venice answers 400 modelNotFound for a model (measured for kimi-k2-5), the bridge remembers that model until it restarts and sends it to the agent route.
chatPOST outerface.venice.ai/api/inference/chatThe web app's plain chat route (JSON lines, one object per line with a kind). No agent loop, no Venice tools, no swallowed calls.
agentPOST outerface.venice.ai/api/inference/chat/agents/ad-hocThe agent route (Responses-style SSE). Needs a paid plan (a free account gets 403 creator_access_required). Venice runs its own agent loop: the model gets Venice's server tools as native tools, a native call to a client tool is swallowed, and turns can end in "Tool not found".

On the chat route the client's system prompt is folded into the first user message ([SESSION INSTRUCTIONS] … [END OF SESSION INSTRUCTIONS], then [USER REQUEST]), because that route's 413 userPromptTooLong limit (about 150,000 characters) applies to the systemPrompt field only; 460,000 characters inside a user message were accepted (measured). The log line timing open: … route=chat|agent shows which route a request used.

On the agent route a swallowed call shows only the tool name in the stream, never its arguments, so it cannot be forwarded; Venice's own get_attachment / view_media run there with made-up ids.

Tool emulation and the tiered tool list

Venice's web routes do not give the model the client's declared tools (measured on the agent route /agents/ad-hoc and on /agents/venice: a declared bash client tool is invisible to the model; the chat route offers the model no tools). So tools are emulated in text:

  • The tool list goes into the system prompt. Built-in tools and tools already used in the conversation get a compact full JSON schema (tier A); the rest are one-liners (tier B). The whole block has a budget of 78,000 characters; over budget, tier B degrades from the end to shorter descriptions, then to names only. Tier A is never cut.
  • For scale: a real OpenCode request measured 411 tools and about 441,000 characters of system prompt.
  • The model replies {"tool_calls":[{"name":"...","arguments":{...}}]}. A format reminder with one example is appended as the last user message.

Tolerant parser

tolerant_parser.py, a port of the opencode-venice-web parser (MIT), reads calls that are bare, fenced, after prose, in several envelopes, or structurally broken (8 of 8 real malformed replies in the fixtures). Two more call readers and tool routing follow below.

Call readers

Call readers: a native call reader for the model's own markup and a tagged call reader for <tool_calls>.

  • Native call reader. Some models write tool calls in their own markup, with arguments, as text. On the chat route DeepSeek V4.1 Flash writes <|DSML| invoke name="shell"><|DSML| parameter name="command" string="true">ls</|DSML| parameter></|DSML| invoke>. The bridge reads that form and plain <invoke name=…><parameter name=…>, several calls per reply, takes string="false" parameters as JSON, and never shows the markup as text.
  • Tagged call reader. <tool_calls>{"name":…,"arguments":…}</tool_calls>, including file content with unescaped quotes.

Tool routing

Tool routing: a call to a tool the client did not declare is routed to the client's tool for the same job. A call to an unknown name with no counterpart is passed to the client when the reply is only that call (under 200 characters of other text), so the client can tell the model; otherwise it is dropped and logged.

The model callsRouted to
cat, read_file, viewread
shell, execute, run_commandbash (or shell on clients that name it so)
str_replace, edit_fileedit
create_file, write_filewrite
search, rggrep
find_filesglob
web_searchwebsearch
web_scrape, fetchwebfetch
ls, list_dirlist, or a shell ls
Venice's get_attachment, view_mediaread, only when the id is a file path

The tool block in the prompt also tells the model that Venice's own tools and built-in function calling do not reach this computer, and which client tool does which job (read a file, run a command, search the web, fetch a web page).

The table above shows the common cases. The full alias lists (tool names, argument names, Venice server-tool names mapped back to the client's tools, and what is deliberately not routed) are in docs/TOOL_ROUTING.md.

Argument fitting

Argument fitting renames arguments the model named differently: path / file_path / filename → filePath, cmd / script → command, old_str → oldString, new_str → newString, contents / text → content, query / regex → pattern, link → url. This happens only when the tool expects that name, did not get it, and does not know the other name. Before renaming, envelopes the model adds around the real arguments ({"arguments": {...}}, {"input": {...}}, {"parameters": {...}}, a JSON string in arguments) are unwrapped, up to three levels, when the tool has no field of that name. A bare string ({"content": "..."}) goes into the tool's one required string parameter when it has no content of its own.

Completion check

A reply counts only after its completion signal: response.completed on the agent route; on the chat route, which sends no closing event, a clean end of the HTTP response (curl exit code 0). A cut stream never becomes a half-written file.

Server-loop cut (agent route only)

On the agent route Venice sometimes takes a model's native tool call for one of its own server tools, or runs one of its own tools, and answers the model "Tool not found" in a loop. The bridge tolerates 3 such steps, then cuts the response and retries with a reminder that names the tools. Cutting at the first step in which Venice runs its own tool was tried and removed: it made DeepSeek V4.1 Flash fail 7 of 8 turns, because the model usually recovers inside the same response.

In-bridge retries

In tools mode the bridge retries by itself, with a budget of 2 (VENICE_BRIDGE_FORMAT_RETRIES), for: a server loop, an unreadable call, an empty reply, and a broken stream (resent once, unchanged). Each retry adds a targeted reminder and is a full upstream request; a retry never replaces a better reply. A reply that was already streamed live (see the stream gate) is neither retried nor judged.

Judge

When a reply ends the turn right after a tool result without calling a tool, a small judge model (qwen3-5-35b-a3b) checks it for an early stop, an ignored failure or a missing result, and can trigger one more attempt (VENICE_BRIDGE_JUDGE_RETRIES, default 1). It only sees the latest user request, the last two tool results and the reply, as tails. Any judge failure keeps the reply. Disable it with VENICE_BRIDGE_JUDGE=0.

Stream gate

With tools, a prose reply longer than 200 characters is streamed while it is written; anything that may still become a tool call is held back. Failures before the status line are returned as HTTP 502, because OpenCode retries a 502 but not an error inside a started stream (measured). Without tools, text and reasoning stream as they arrive. A stream that fails after it started ends with a data: {"error": {...}} line and no data: [DONE], never with a normal ending.

Error mapping

Upstream situationClient seesError type
Chat quota used up (Venice 429, 0 remaining)403venice_quota_exhausted (body code 429), message with the reset time
Passing rate limit (Venice 429, quota left)429venice_rate_limited
Request too large (Venice 413)400invalid_request_error, code context_length_exceeded
Cloudflare challenge502venice_upstream_error (body code 403), with a clear message
Model not on the chat route (Venice 400 modelNotFound)auto: agent route; chat: 502venice_upstream_error (body code 400), "Venice answered HTTP 400: …"
Plan or credits do not cover the model (Venice 402)402venice_upstream_error
Auth rejected (Venice 401 after one retry, or 403)401 / 403venice_upstream_error
Other upstream failure, empty or cut reply502venice_upstream_error or bridge_error

The quota is answered as 403 on purpose: OpenCode retries a 429 silently. While the quota is known to be used up, the bridge answers at once without calling Venice; POST /reload clears that lock.

Configuration

Command-line options

OptionDefaultMeaning
--hostVENICE_BRIDGE_HOST, else 127.0.0.1Address the bridge listens on.
--port18891Port the bridge listens on.

The adapter has no command-line options; it is configured with the environment variables below.

Bridge environment variables

VariableDefaultMeaning
VENICE_BRIDGE_HOST127.0.0.1Bind address (--host wins). The bridge has no authentication of its own: keep it on 127.0.0.1.
VENICE_BRIDGE_ROUTEautoVenice web route: auto (chat route; agent route for a model the chat route does not know), chat (chat route only), agent (agent route only; needs a paid plan). See Routes.
VENICE_BRIDGE_COOKIE_FILE~/.config/venice-bridge/client-cookie.txtText file with the __client cookie value.
VENICE_BRIDGE_SESSION_DIRunsetFolder with a local session daemon's client.py exposing get_session(domain).
VENICE_BRIDGE_CLIENT_FILE~/.config/venice-bridge/rotated-client.jsonWhere the rotated Clerk cookie is saved (mode 0600).
VENICE_BRIDGE_FORMAT_RETRIES2In-bridge retries for server loop, unreadable call, empty reply and broken stream.
VENICE_BRIDGE_JUDGEon0 turns the judge off.
VENICE_BRIDGE_JUDGE_MODELqwen3-5-35b-a3bModel used as the judge.
VENICE_BRIDGE_JUDGE_RETRIES1Extra attempts the judge may trigger.
VENICE_WEBoff1 turns on Venice web search and URL scraping for every request. See Web search.
VENICE_X_SEARCHoff1 turns on Venice X search for every request.
VENICE_REASONINGoff1 turns on reasoning for every request that declares no tools. See Reasoning.
VENICE_EXCLUDE_MODELSunsetComma-separated glob patterns hidden from GET /v1/models (on top of credit models and e2ee-*), for example qwen3-vl-*,venice-uncensored-*.
VENICE_AUTO_MODELSdeepseek-v4-1-flash-uncensored,ollama/qwen3:8bCandidates for venice-auto: the first Venice id normally, the first local <backend>/<model> while the quota is used up. See venice-auto.
VENICE_BRIDGE_BACKENDS~/.config/venice-bridge/backends.jsonLocal backends file. See Local models.
VENICE_BRIDGE_CACHEon0 disables the response cache. See Response cache.
VENICE_BRIDGE_CACHE_MAX256Maximum cache entries.
VENICE_BRIDGE_CACHE_TTL3600Seconds a cache entry stays valid.

Adapter environment variables

VariableDefaultMeaning
VENICE_ADAPTER_HOST127.0.0.1Address the adapter listens on.
VENICE_ADAPTER_PORT18892Port the adapter listens on.
VENICE_ADAPTER_UPSTREAMhttp://127.0.0.1:18891/v1The Chat Completions server it forwards to (the bridge by default).
VENICE_ADAPTER_MODELdeepseek-v4-1-flash-uncensoredUsed when the client asks for a model the upstream does not list (for example claude-... or gpt-...).
VENICE_ADAPTER_DUMPunsetA folder: saves every request body there. Debugging only: the bodies contain your prompts.

claude-venice variables

VariableDefaultMeaning
VENICE_CLAUDE_MODELdeepseek-v4-1-flash-uncensoredVenice model id (-m wins).
VENICE_CLAUDE_SKIP_PERMS10 keeps Claude Code's permission prompts. See the warning.

API reference

Bridge (127.0.0.1:18891)

Bridge: base URL http://127.0.0.1:18891. Errors use the OpenAI shape {"error": {"message", "type"}}; upstream errors also carry code, while 404 and invalid-JSON errors carry only message. /health uses its own shape. Unknown paths answer 404.

POST /v1/chat/completions

OpenAI Chat Completions, streaming ("stream": true, server-sent events ending with data: [DONE]) and non-streaming. Declared tools come back as tool_calls with finish_reason: "tool_calls"; when the model returns reasoning (see Reasoning), it arrives as reasoning_content (a message field, or delta.reasoning_content chunks when streaming). venice-auto is resolved to a concrete model first (see venice-auto). If model is missing, qwen3-coder-480b-a35b-instruct-turbo is used. temperature and top_p are forwarded when set; max_tokens is ignored (see Settings sent to Venice). A :web / :xsearch suffix turns on Venice web search for that request; a local backend prefix (ollama/...) sends the request to that backend unchanged. usage is an estimate (about 4 characters per token).

curl -s http://127.0.0.1:18891/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-1-flash-uncensored","messages":[{"role":"user","content":"Reply with PONG"}]}'
StatusWhen
200chat.completion object, or an SSE stream of chat.completion.chunk
400Invalid JSON body, or context_length_exceeded
401 / 403Venice rejected the login, or the agent route on a free account (creator_access_required); type venice_upstream_error
402Plan or credits do not cover the model
403Chat quota used up; type venice_quota_exhausted
429Passing rate limit; type venice_rate_limited
502Upstream failure, Cloudflare challenge, empty or cut reply; a local backend that did not answer (type local_backend_error)

GET /v1/models

Lists the virtual venice-auto first (owned_by: "venice-bridge"), then the models of your account's web catalogue that do not use credits (owned_by: "venice-web"; e2ee-* and VENICE_EXCLUDE_MODELS patterns hidden), followed by the models of every reachable local backend (<backend>/<id>, owned_by the backend name). A local backend that is down is skipped. When Venice cannot be read, the local models are still listed; it answers 502 (bridge_error) only when Venice fails and no local model is listed.

curl -s http://127.0.0.1:18891/v1/models

GET /health

200 {"ok": true, "venice_session": "active", "chat_quota": {"reset_at", "remaining", "resets_in_min"}, "cache": {"hits", "misses", "stores", "entries", "enabled"}} when a session JWT can be minted; chat_quota is null when the quota cannot be read. 503 {"ok": false, "error": "..."} when the login does not work.

curl -s http://127.0.0.1:18891/health

POST /reload

Drops the cached auth (Clerk cookie, session, JWT, attestation) and the quota lock (also the over-quota state of venice-auto). Answers 200 {"ok": true}.

curl -s -X POST http://127.0.0.1:18891/reload

Adapter (127.0.0.1:18892)

Adapter: base URL http://127.0.0.1:18892. It ignores authentication headers and forwards every model call to its upstream's /chat/completions. An upstream error status is passed on before any stream starts, so the client sees the real status; an upstream that does not answer gives 502.

EndpointWhat it does
POST /v1/messagesAnthropic Messages (streaming and non-streaming), with tool declarations, tool_use / tool_result blocks and stream events translated to and from Chat Completions. A query string such as ?beta=true is ignored.
POST /v1/messages/count_tokensAnswers {"input_tokens": N}, an estimate of about 4 characters per token. No upstream call.
POST /v1/responsesOpenAI Responses (streaming and non-streaming), with function calls and their outputs translated. usage carries cached_tokens: 0.
GET /v1/modelsThe upstream's model list, unchanged.
GET /health200 {"ok": true, "upstream": "...", "default_model": "..."}. It does not check the upstream.
curl -s http://127.0.0.1:18892/health
curl -s http://127.0.0.1:18892/v1/messages -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-1-flash-uncensored","max_tokens":256,"messages":[{"role":"user","content":"Reply with PONG"}]}'

Tests

Both self-checks run offline: they use temporary files and fake servers on localhost, never the real Venice endpoints. Success prints the lines below and exits with status 0; a failure stops with an AssertionError traceback and a non-zero exit status.

1. Bridge

python3 test_venice_bridge.py
cookie file ok
session ok
ok
end to end ok
local backends ok
reasoning + venice-auto prefix ok

2. Adapter

python3 test_venice_adapters.py
messages ok
pick_model ok
responses ok

3. Live check (both processes running)

Not a self-check: it needs your login and spends no model request.

curl -s http://127.0.0.1:18891/health   # {"ok": true, "venice_session": "active", ...}
curl -s http://127.0.0.1:18892/health   # {"ok": true, "upstream": "http://127.0.0.1:18891/v1", ...}
claude-venice --quota                   # Venice web quota  remaining=...  resets_in_min=...

Measured performance

One machine, one account, November 2026. These numbers describe what was measured, not what you will get. Venice's load, your plan and your network change them.

  • Bridge overhead per request: about 21 ms with a 441k-character prompt and 401 tools (local fake upstream).
  • A short model step through the bridge: 1.5–3 s. A warm OpenCode session: 2.8–4.5 s per message.
  • On the agent route, swallowed calls cost roughly 20–50 % of bridge time on models that prefer native tool calls; on the chat route none were seen.

Small-project benchmark: the coding client builds a Python todo CLI with tests and a README from one prompt. Wall time includes the client's own startup.

Model idRoute usedResultTime
deepseek-v4-1-flashchatworking project, 3 of 3 runs, 0 retries, 0 swallowed calls34–51 s
deepseek-v4-1-flash (before, agent route)agent2 of 4 runs produced a project63–203 s
deepseek-v4-1-flash-uncensoredchatworking project, 3 of 3 runs16 s, 56 s, and one 460 s run where the model itself took 86 steps to debug a test
z-ai-glm-5-3-flashchatworking project84 s
qwen3-coder-480b-a35b-instruct-turbochatworking project86 s
kimi-k2-5agent (not on the chat route)commands work, its own tests left failing146 s

When to use venice-bridge vs local vs paid

Because the Venice web route has no native tools / tool_choice and no prompt cache (cached_tokens: 0), match the backend to the job. On short synthetic tool benchmarks across four Venice models, the bridge scored 52/52 with 0 runaway cuts; caveat: that score comes from short synthetic tasks — in long real sessions before the runaway cutoff, 15 of 7,167 streams entered repetition loops, so 52/52 is not proof of 95%+ reliability on long sessions.

WorkloadRecommended routeWhy
High-volume / parallel exploration, cheap throwaway runsvenice-bridge (use claude-venice --lean if the repo has .mcp.json)Request-metered web plan, ~4–5 s per step, short synthetic tool benchmarks: 52/52
Offline / private / zero-quota work needing native toolsLocal models via Ollama / LM Studio / llama.cpp (direct or <backend>/<model> via the bridge)Native tool grammar, no external network or daily request cap
Deep multi-step coding, architecture, security review, strict schema / long-context fidelityPaid native-tools APIs (including the metered api.venice.ai/api/v1)Native tools + tool_choice + real prompt caching; web login cookies do not work on api.venice.ai

Troubleshooting

SymptomCauseFix
Connection refused on port 18891The bridge is not running.Start python3 venice_bridge.py, or check venice_bridge.log when launchd runs it.
/health answers 503No cookie, or Clerk no longer accepts it.Copy a fresh __client value into the cookie file, then POST /reload.
403 with creator_access_required (type venice_upstream_error)The request went to the agent route on a free Venice account.The agent route needs a paid Venice web plan (Pro); with VENICE_BRIDGE_ROUTE=agent, try auto.
403 with type venice_quota_exhaustedWeb chat quota used up.Wait for the reset time in the message; /health shows resets_in_min. To keep working meanwhile, use venice-auto with a local fallback.
429 with type venice_rate_limitedVenice is rate limiting briefly; quota is left.Retry after a short wait.
502 "Cloudflare challenged the request"Cloudflare wants a browser check.Open venice.ai in your browser, refresh the cookie file (or sync your session daemon), and try again.
400 context_length_exceededThe request is larger than Venice accepts.Start a new session or compact the conversation; declare fewer tools.
402Your plan or credits do not cover the model.Pick a model from GET /v1/models.
The model stops early or a tool call fails now and thenTool calling is emulated; open models sometimes need a retry.Ask again or switch models (see the benchmark).
Short replies appear all at once in tools modeThe stream gate holds replies under 200 characters until they are complete.Expected behaviour.
The model says its tools are unavailable, or "Tool not found" (for example "the tool layer is down — shell, execute and read all return Tool not found")The request went through the agent route (check route= in the log).Use VENICE_BRIDGE_ROUTE=auto or chat, or pick a model that exists on the chat route. In an existing conversation the model may keep believing its tools are broken: tell it they work now, or start a new session.
502 "Venice answered HTTP 400: … modelNotFound" with VENICE_BRIDGE_ROUTE=chatThat model exists only on the agent route.Use VENICE_BRIDGE_ROUTE=auto.
claude-venice: "venice-adapters (http://127.0.0.1:18892) is down"The adapter is not running.Start python3 venice_adapters.py, or load its launchd template.
claude-venice: "Venice web session is not active"The bridge is up but the login expired.Copy a fresh __client value into the cookie file, then POST /reload.
Claude Code: "Auto mode could not evaluate this action and is blocking it for safety"Venice's fast models cannot drive Claude Code's auto-mode classifier.That is why claude-venice skips permission prompts by default; with VENICE_CLAUDE_SKIP_PERMS=0, use another --permission-mode.
502 with type local_backend_errorThe local backend for that model prefix is not running or not reachable.Start Ollama, LM Studio or your server, or check base_url in backends.json. The request is never sent to Venice instead.
A local model is missing from GET /v1/modelsIts backend is down, or a backends.json file replaced the defaults.Start the backend; list every backend you want in the file.
Claude Code or Codex answers with a different model than askedThe adapter replaces ids the bridge does not list (claude-..., gpt-...) with VENICE_ADAPTER_MODEL.Pass a Venice id from GET /v1/models (claude-venice -m <id>).

FAQ

Does it need a Venice API key?

No. venice-bridge does not use the paid Venice API. It talks to the backend of the venice.ai web app with your own browser login (the __client cookie of clerk.venice.ai). The apiKey value in the OpenCode config is a placeholder that the bridge does not check.

Does it work on a free Venice account?

It was not tested on one. Everything was measured on a paid Venice web plan (Pro). The agent route needs a paid plan; on a free account it answers 403 creator_access_required. A free account also has a very small chat quota (about 5 messages per ~4 hours when it was observed).

Does it work with Claude Code or Codex?

Yes, through the adapter. Run python3 venice_adapters.py next to the bridge: it serves the Anthropic Messages API (/v1/messages) and the OpenAI Responses API (/v1/responses) on 127.0.0.1:18892 and forwards them to the bridge. For Claude Code the claude-venice launcher sets everything up in an isolated profile (~/.claude-venice) and, by default, skips Claude Code's permission prompts (opt out with VENICE_CLAUDE_SKIP_PERMS=0; see the warning). Codex CLI is pointed at the adapter with -c model_providers settings (see Codex CLI); its MCP servers, multi-agent tools and built-in web_search do not pass through.

Does it run local models?

Yes. A model id with a backend prefix, such as ollama/qwen3:8b or lmstudio/<id>, is passed straight to that local OpenAI-compatible server, with no Venice login, no tool emulation and no quota. Ollama (127.0.0.1:11434) and LM Studio (127.0.0.1:1234) are the defaults; others such as llama.cpp or MLX servers are added in ~/.config/venice-bridge/backends.json. GET /v1/models lists the models of every reachable local backend next to the Venice models. See Local models.

What happens when my daily Venice quota runs out?

Venice requests answer 403 venice_quota_exhausted with the reset time until the quota resets. The quota is plan-wide, so switching to another Venice model does not help. To keep working, use the virtual model venice-auto: it serves a Venice model normally and a local model (default ollama/qwen3:8b) while the quota is used up. The request that hits the limit still fails once, the local backend must be running, and a local model may differ in quality, speed and context size. See Model list and venice-auto.

Does it cost tokens?

No. The Venice web plan is limited by a daily request quota, not by tokens. The usage numbers the bridge returns are estimates (about 4 characters per token), because Venice returns no token counts. Fewer requests save quota; shorter prompts do not. GET /health shows chat_quota.remaining and resets_in_min, and a byte-identical repeat request is answered from the response cache without a Venice call. See Quota and cost model.

Can I use it from Docker?

Yes. A container reaches a bridge bound to 127.0.0.1 on the host through http://host.docker.internal:18891/v1 (measured with Docker Desktop on macOS). Binding the bridge to 0.0.0.0 is not needed and not recommended: the bridge has no authentication of its own.

Does it work on Linux or Windows?

Untested. The bridge streams through the system curl of macOS, which passes Cloudflare. Linux and Windows have not been tried.

Is this allowed by Venice?

venice-bridge is unofficial and not affiliated with, endorsed by, or supported by Venice.ai. It automates your own logged-in web session through undocumented endpoints, which may be against Venice's terms of service. Use it at your own risk, with your own account only, and never share cookies or accounts.

Where do my chats go?

From your client to the bridge on 127.0.0.1, then to the venice.ai web backend under your own account (clerk.venice.ai for login, outerface.venice.ai for inference), as with the web app. When the judge is on, a short excerpt of the turn is sent to Venice as a second request. The bridge keeps no conversation history: each request body sits in a private temporary folder (mode 0700) only while its upstream call runs and is deleted afterwards. Its log records sizes, timings and outcomes and can include short excerpts of unreadable replies or swallowed tool calls. Exceptions: a model with a local backend prefix (for example ollama/...) goes only to that local server, never to Venice; successful replies are kept in the in-memory response cache until their time limit (1 hour by default, VENICE_BRIDGE_CACHE=0 turns it off) and are lost when the bridge stops; with a :web or :xsearch suffix Venice also searches the web on its side; and when VENICE_ADAPTER_DUMP is set, the adapter writes every request body to that folder.

Is it an alternative to opencode-venice-web?

Yes, it is an independent Python implementation of the same idea. opencode-venice-web (Node) is the most mature Venice web proxy and sends the full schema of every tool; venice-bridge is a small Python bridge (plus an optional adapter for Claude Code and Codex) that sends a tiered tool list within a fixed budget. Its tolerant tool-call parser is a port of the opencode-venice-web parser (MIT).

Alternatives

AI agent integration

These files in the repository are written for coding agents:

  • AGENTS.md: the contract for agents that work on or with this repository: how to start, stop and check the bridge, endpoints, environment variables, tests, rules and common failures.
  • GLOBAL_AGENT_RULE.md: a standalone snippet you can paste into your own agent's instructions so it knows how to start, check and use the bridge.
  • docs/TOOL_ROUTING.md: the tool-name and argument-name routing reference.

For LLM ingestion this site also serves llms.txt and llms-full.txt.

License and credits

MIT License, Copyright (c) 2026 venice-bridge contributors. See LICENSE.

tolerant_parser.py is a Python port of the tolerant tool-call parser of opencode-venice-web, and the real malformed replies in test_fixtures_real_replies.json come from its test fixtures; several reminder texts and the judge prompt are adapted from the same project. All are used under the MIT License; see NOTICE.md.

Venice and venice.ai are trademarks of their respective holder, used here only to describe compatibility.

No section matches your search.