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.
- 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.
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.commandregex fallback: unwraps{"command": "..."}even when unescaped inner shell double quotes break JSON parsing. - Control-character restoration in
Bash.command: restores JSON-decoded\x08/\x0cback to\b/\fand 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, andxSearchEnabled: falseunless:web/:xsearchis 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) andAgentalongsideTask. - New tool routing aliases:
sql_query/sqlite_query→ read-onlysqlite3onBash,get_current_date→date -u, deferredgrep/glob→Bash, plus double-encodedcommandunwrapping and removal of literalexample_toolfrom the reminder prompt. claude-venice--resumefix: pairs--dangerously-skip-permissionswith--permission-mode bypassPermissionsso 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_toolreaches the shell tool.claude-venice --leanstarts 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 nocontentparameter 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 inarguments), so the inner command is no longer dropped. - The format reminder asks for parameters directly in
argumentsand a heredoc for multi-line SQL or Python. - On PyPI:
pipx install venice-bridgegivesvenice-bridge,venice-adaptersandclaude-venice.
v0.2.0 2026-11-21
- Claude Code and Codex CLI through the adapter (
127.0.0.1:18892), and theclaude-venicelauncher. - Local models by prefix (
ollama/,lmstudio/,backends.json) and thevenice-autofallback model. - Opt-in web search (
:web,:xsearch) and reasoning (:think); response cache.
Screenshots
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.
- Log in on venice.ai in Chrome.
- Open DevTools, then Application → Cookies →
https://clerk.venice.ai. - 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.
- Replace every
/PATH/TOin the file with real absolute paths (yourpython3and the repository folder). - Copy it to
~/Library/LaunchAgents/. - 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.
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.
| Prefix | Default 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 inVENICE_AUTO_MODELSthere 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 /reloadand 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.
Web search (opt-in)
Venice can search the web server-side on the plain chat route. It is off by default, because Venice runs it on its side and it can compete with the client's own tools in an agent loop.
| How | Scope | Effect |
|---|---|---|
Model suffix :web (also :scrape) | one request | Venice web search and URL scraping |
Model suffix :xsearch (also :xweb, :x) | one request | X search |
VENICE_WEB=1 in the bridge's environment | whole process | web search and URL scraping on every request |
VENICE_X_SEARCH=1 in the bridge's environment | whole process | X search on every request |
Suffixes combine (deepseek-v4-1-flash-uncensored:web:xsearch) and are removed before the id reaches Venice. The adapter keeps the suffix when the base id is valid, so claude-venice -m <id>:web works. Measured: a :web request returned a current fact with ^1^-style citation markers.
curl -s http://127.0.0.1:18891/v1/chat/completions -H 'Content-Type: application/json' \
-d '{"model":"deepseek-v4-1-flash-uncensored:web","messages":[{"role":"user","content":"What is the latest Python release?"}]}'
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.
| How | Scope |
|---|---|
Model suffix :think (also :reason, :reasoning), combinable: deepseek-v4-1-flash-uncensored:web:think | one request |
VENICE_REASONING=1 in the bridge's environment | whole 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.
| Variable | Default | Meaning |
|---|---|---|
VENICE_BRIDGE_CACHE | on | 0 disables the cache. |
VENICE_BRIDGE_CACHE_MAX | 256 | Maximum entries. |
VENICE_BRIDGE_CACHE_TTL | 3600 | Seconds 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.
usagenumbers are an estimate of about 4 characters per token, because Venice returns no token counts. The adapter's/v1/messages/count_tokensuses the same estimate, and the adapter reportscached_tokens: 0.GET /healthshowschat_quota.remainingandresets_in_min;claude-venice --quotaprints 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_exhaustedwith 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-autowith a local fallback.
curl -s http://127.0.0.1:18891/health
How it works
Your client
- Sends messages and declared tools
- Runs the returned
tool_calls
venice-bridge
- Route:
auto,chatoragent - Tool list into the prompt
- Call readers, tool routing, argument fitting
- Retries, judge, stream gate
- Error mapping
Clerk
__client→ session (~60 s JWT)
Venice web backend
- Client attestation
- Chat route
/api/inference/chat(JSON lines; default) - Agent route
/api/inference/chat/agents/ad-hoc(SSE; fallback)
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.
Claude Code
- via
claude-venice
Codex CLI
- via
-c model_providers
Adapter
- Messages, tool declarations, tool calls and results, stream events
- Standard library only
- Nothing Venice-specific
Bridge
- Venice login, routes, tool emulation
- Response cache
- Local backends by prefix
OpenCode and other OpenAI clients talk to the bridge directly; the adapter's upstream (VENICE_ADAPTER_UPSTREAM) can be any Chat Completions server.
| Process | File | Default address | Speaks |
|---|---|---|---|
| Bridge | venice_bridge.py | 127.0.0.1:18891 | OpenAI Chat Completions POST /v1/chat/completions, GET /v1/models, GET /health, POST /reload |
| Adapter (optional) | venice_adapters.py | 127.0.0.1:18892 | Anthropic 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.
| Setting | Route | What happens |
|---|---|---|
auto (default) | chat, agent as fallback | Uses 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. |
chat | POST outerface.venice.ai/api/inference/chat | The web app's plain chat route (JSON lines, one object per line with a kind). No agent loop, no Venice tools, no swallowed calls. |
agent | POST outerface.venice.ai/api/inference/chat/agents/ad-hoc | The 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, takesstring="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 calls | Routed to |
|---|---|
cat, read_file, view | read |
shell, execute, run_command | bash (or shell on clients that name it so) |
str_replace, edit_file | edit |
create_file, write_file | write |
search, rg | grep |
find_files | glob |
web_search | websearch |
web_scrape, fetch | webfetch |
ls, list_dir | list, or a shell ls |
Venice's get_attachment, view_media | read, 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 situation | Client sees | Error type |
|---|---|---|
| Chat quota used up (Venice 429, 0 remaining) | 403 | venice_quota_exhausted (body code 429), message with the reset time |
| Passing rate limit (Venice 429, quota left) | 429 | venice_rate_limited |
| Request too large (Venice 413) | 400 | invalid_request_error, code context_length_exceeded |
| Cloudflare challenge | 502 | venice_upstream_error (body code 403), with a clear message |
Model not on the chat route (Venice 400 modelNotFound) | auto: agent route; chat: 502 | venice_upstream_error (body code 400), "Venice answered HTTP 400: …" |
| Plan or credits do not cover the model (Venice 402) | 402 | venice_upstream_error |
| Auth rejected (Venice 401 after one retry, or 403) | 401 / 403 | venice_upstream_error |
| Other upstream failure, empty or cut reply | 502 | venice_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
| Option | Default | Meaning |
|---|---|---|
--host | VENICE_BRIDGE_HOST, else 127.0.0.1 | Address the bridge listens on. |
--port | 18891 | Port the bridge listens on. |
The adapter has no command-line options; it is configured with the environment variables below.
Bridge environment variables
| Variable | Default | Meaning |
|---|---|---|
VENICE_BRIDGE_HOST | 127.0.0.1 | Bind address (--host wins). The bridge has no authentication of its own: keep it on 127.0.0.1. |
VENICE_BRIDGE_ROUTE | auto | Venice 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.txt | Text file with the __client cookie value. |
VENICE_BRIDGE_SESSION_DIR | unset | Folder with a local session daemon's client.py exposing get_session(domain). |
VENICE_BRIDGE_CLIENT_FILE | ~/.config/venice-bridge/rotated-client.json | Where the rotated Clerk cookie is saved (mode 0600). |
VENICE_BRIDGE_FORMAT_RETRIES | 2 | In-bridge retries for server loop, unreadable call, empty reply and broken stream. |
VENICE_BRIDGE_JUDGE | on | 0 turns the judge off. |
VENICE_BRIDGE_JUDGE_MODEL | qwen3-5-35b-a3b | Model used as the judge. |
VENICE_BRIDGE_JUDGE_RETRIES | 1 | Extra attempts the judge may trigger. |
VENICE_WEB | off | 1 turns on Venice web search and URL scraping for every request. See Web search. |
VENICE_X_SEARCH | off | 1 turns on Venice X search for every request. |
VENICE_REASONING | off | 1 turns on reasoning for every request that declares no tools. See Reasoning. |
VENICE_EXCLUDE_MODELS | unset | Comma-separated glob patterns hidden from GET /v1/models (on top of credit models and e2ee-*), for example qwen3-vl-*,venice-uncensored-*. |
VENICE_AUTO_MODELS | deepseek-v4-1-flash-uncensored,ollama/qwen3:8b | Candidates 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.json | Local backends file. See Local models. |
VENICE_BRIDGE_CACHE | on | 0 disables the response cache. See Response cache. |
VENICE_BRIDGE_CACHE_MAX | 256 | Maximum cache entries. |
VENICE_BRIDGE_CACHE_TTL | 3600 | Seconds a cache entry stays valid. |
Adapter environment variables
| Variable | Default | Meaning |
|---|---|---|
VENICE_ADAPTER_HOST | 127.0.0.1 | Address the adapter listens on. |
VENICE_ADAPTER_PORT | 18892 | Port the adapter listens on. |
VENICE_ADAPTER_UPSTREAM | http://127.0.0.1:18891/v1 | The Chat Completions server it forwards to (the bridge by default). |
VENICE_ADAPTER_MODEL | deepseek-v4-1-flash-uncensored | Used when the client asks for a model the upstream does not list (for example claude-... or gpt-...). |
VENICE_ADAPTER_DUMP | unset | A folder: saves every request body there. Debugging only: the bodies contain your prompts. |
claude-venice variables
| Variable | Default | Meaning |
|---|---|---|
VENICE_CLAUDE_MODEL | deepseek-v4-1-flash-uncensored | Venice model id (-m wins). |
VENICE_CLAUDE_SKIP_PERMS | 1 | 0 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"}]}'
| Status | When |
|---|---|
| 200 | chat.completion object, or an SSE stream of chat.completion.chunk |
| 400 | Invalid JSON body, or context_length_exceeded |
| 401 / 403 | Venice rejected the login, or the agent route on a free account (creator_access_required); type venice_upstream_error |
| 402 | Plan or credits do not cover the model |
| 403 | Chat quota used up; type venice_quota_exhausted |
| 429 | Passing rate limit; type venice_rate_limited |
| 502 | Upstream 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.
| Endpoint | What it does |
|---|---|
POST /v1/messages | Anthropic 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_tokens | Answers {"input_tokens": N}, an estimate of about 4 characters per token. No upstream call. |
POST /v1/responses | OpenAI Responses (streaming and non-streaming), with function calls and their outputs translated. usage carries cached_tokens: 0. |
GET /v1/models | The upstream's model list, unchanged. |
GET /health | 200 {"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 id | Route used | Result | Time |
|---|---|---|---|
deepseek-v4-1-flash | chat | working project, 3 of 3 runs, 0 retries, 0 swallowed calls | 34–51 s |
deepseek-v4-1-flash (before, agent route) | agent | 2 of 4 runs produced a project | 63–203 s |
deepseek-v4-1-flash-uncensored | chat | working project, 3 of 3 runs | 16 s, 56 s, and one 460 s run where the model itself took 86 steps to debug a test |
z-ai-glm-5-3-flash | chat | working project | 84 s |
qwen3-coder-480b-a35b-instruct-turbo | chat | working project | 86 s |
kimi-k2-5 | agent (not on the chat route) | commands work, its own tests left failing | 146 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.
| Workload | Recommended route | Why |
|---|---|---|
| High-volume / parallel exploration, cheap throwaway runs | venice-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 tools | Local 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 fidelity | Paid 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
| Symptom | Cause | Fix |
|---|---|---|
| Connection refused on port 18891 | The bridge is not running. | Start python3 venice_bridge.py, or check venice_bridge.log when launchd runs it. |
/health answers 503 | No 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_exhausted | Web 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_limited | Venice 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_exceeded | The request is larger than Venice accepts. | Start a new session or compact the conversation; declare fewer tools. |
| 402 | Your 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 then | Tool 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 mode | The 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=chat | That 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_error | The 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/models | Its 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 asked | The 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
- CanArslanDev/opencode-venice-web: Node; the most mature Venice web proxy; sends full schemas for every tool.
- aintlikeu/unofficial-venice-proxy and zalo-alex/venice-opencode: other Venice web proxies.
- The official Venice API with an API key (metered credits), and OpenCode's built-in
veniceprovider.
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.


