# 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.
Version 0.2.6 · MIT · Repository: https://github.com/nsozturk/venice-bridge · Docs: https://nsozturk.github.io/venice-bridge/
---
# README
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 has two small Python processes. The **bridge** (`venice_bridge.py`, with the tolerant tool-call parser
`tolerant_parser.py`) runs an OpenAI Chat Completions server on `127.0.0.1:18891` and forwards each request to
the backend of the venice.ai web app, signed in with your own browser login. The optional **adapter**
(`venice_adapters.py`, standard library only) runs on `127.0.0.1:18892` and translates Anthropic Messages
(Claude Code) and OpenAI Responses (Codex CLI) into Chat Completions for the bridge. A launcher,
`claude-venice`, starts Claude Code against the adapter in its own profile. Nothing uses the paid Venice API,
and no API key is needed.
Documentation site: · Agent contract: [AGENTS.md](https://github.com/nsozturk/venice-bridge/blob/main/AGENTS.md) ·
Changelog: [CHANGELOG.md](https://github.com/nsozturk/venice-bridge/blob/main/CHANGELOG.md) ·
Tool routing reference: [docs/TOOL_ROUTING.md](https://github.com/nsozturk/venice-bridge/blob/main/docs/TOOL_ROUTING.md)
> [!WARNING]
> **Unofficial. Read this before you use it.**
> - venice-bridge is not affiliated with, endorsed by, or supported by Venice.ai. It talks to undocumented web
> endpoints that can change or break at any time.
> - It automates your own logged-in web session. That may be against Venice's terms of service. You use it at
> your own risk, with your own account. Do not share cookies or accounts.
> - It was tested on a paid Venice web plan (Pro). The agent route needs a paid plan (a free account gets
> `403 creator_access_required`), and a free account has a very small chat quota.
> - macOS only so far. No images. With tools, short replies are sent only when complete; long prose is
> streamed while it is written.
> - Tool calling is emulated in text. Venice's fast models are weak at long agentic chains (see
> [Model quality](#model-quality)); use it for cheap exploratory runs, not high-stakes work.
> - `claude-venice` starts Claude Code with `--dangerously-skip-permissions` by default, so Claude Code runs
> tools **without asking**. See [Use it with Claude Code](#use-it-with-claude-code) for why and how to turn it
> off.
## Requirements
| Item | Notes |
|---|---|
| macOS | The system `curl` is used for the chat stream because it passes Cloudflare. Linux and Windows are untested. |
| Python 3.10+ | With `curl_cffi` (`pip install curl_cffi`, or `pip install -r requirements.txt`). The adapter needs only the standard library. |
| A venice.ai web account | Logged in on venice.ai in your browser. 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 anything else that speaks OpenAI Chat Completions talks to the bridge directly. Claude Code (Anthropic Messages) and Codex CLI (OpenAI Responses) go through the adapter. |
## Quick start
This path sets up the bridge and OpenCode. Claude Code and Codex CLI need the same bridge plus the adapter; see
[Use it with Claude Code](#use-it-with-claude-code) and [Use it with Codex CLI](#use-it-with-codex-cli).
### 1. Save your venice.ai login cookie
The bridge needs the value of the `__client` cookie of `clerk.venice.ai`. This is a long-lived login cookie; from
it the bridge mints a short-lived (about 60 s) session token and a client attestation for every request window.
1. Log in on venice.ai in Chrome.
2. Open DevTools → **Application** → **Cookies** → `https://clerk.venice.ai`.
3. Copy the **Value** of `__client`.
4. Save it to the cookie file:
```bash
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. The cookie is a live
credential for your Venice account: never commit it and never share it.
### 2. Run the bridge
```bash
pip install curl_cffi
python3 venice_bridge.py # options: --host, --port (default 127.0.0.1:18891)
```
Or install it from [PyPI](https://pypi.org/project/venice-bridge/) as commands (`venice-bridge`,
`venice-adapters`, `claude-venice`):
```bash
pipx install venice-bridge # or: pip install venice-bridge
venice-bridge # same options; venice-adapters starts the adapter
```
### 3. Check it
```bash
curl -s http://127.0.0.1:18891/health
```
A working setup answers `200` with `"ok": true`, `"venice_session": "active"`, the remaining web chat quota
(`chat_quota`) and the response-cache counters (`cache`). If the login is missing or rejected it answers `503`
with `"ok": false` and the reason.
### 4. Add the provider to OpenCode
Copy the provider block from [`examples/opencode.json`](https://github.com/nsozturk/venice-bridge/blob/main/examples/opencode.json) into
`~/.config/opencode/opencode.json` (or a project `opencode.json`). The example lists nine models; this is the
same block with one of them:
```json
{
"$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 }
}
}
}
}
}
```
`apiKey` is a placeholder; the bridge does not read it.
### 5. First run
```bash
opencode -m venice-bridge/deepseek-v4-1-flash-uncensored
```
Models in the example config: `deepseek-v4-1-flash-uncensored`, `deepseek-v4-1-flash`, `z-ai-glm-5-3-flash`,
`kimi-k2-5`, `default` (Venice "Auto"), `qwen3-coder-480b-a35b-instruct-turbo`, `qwen3-6-27b`, `zai-org-glm-5.2`,
`venice-uncensored-1-2`. `GET /v1/models` lists whatever your account's web catalogue offers without credits,
plus the models of every reachable [local backend](#local-models-ollama-lm-studio-llamacpp) and the virtual
[`venice-auto`](#model-list-and-venice-auto) model.
Any other OpenAI-compatible client works the same way: base URL `http://127.0.0.1:18891/v1`, any API key.
## Use it with Claude Code
Claude Code speaks Anthropic Messages, so it goes through the adapter. Start both processes:
```bash
python3 venice_bridge.py # 127.0.0.1:18891
python3 venice_adapters.py # 127.0.0.1:18892, forwards to the bridge
```
Then use the `claude-venice` launcher from this folder:
```bash
ln -s "$PWD/claude-venice" ~/.local/bin/claude-venice # or run ./claude-venice
ln -s "$PWD/claude-venice" ~/.local/bin/cv # optional short alias (defaults to bypassPermissions)
claude-venice # default model deepseek-v4-1-flash-uncensored
claude-venice --lean # disable MCP servers (--strict-mcp-config)
claude-venice -m # another Venice model
VENICE_CLAUDE_MODEL= claude-venice # same, from the environment
claude-venice -m deepseek-v4-1-flash-uncensored:web # with Venice web search (see below)
claude-venice --resume # resumes in bypassPermissions mode
claude-venice --models # list the model ids the bridge serves
claude-venice --quota # remaining web quota and cache counters
```
`-m` and `--lean` may appear anywhere before `--`; `--models` and `--quota` must be the first argument. Everything else is passed to `claude`.
What the launcher does:
- Runs the `claude` CLI in an isolated profile, `~/.claude-venice` (`CLAUDE_CONFIG_DIR`). Your normal `claude`
install, its login and its settings are not touched.
- 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 id. A model id that the bridge does not list (such as `claude-...`) is replaced by the
adapter with `VENICE_ADAPTER_MODEL`; an id with a `/` (a local `backend/model`) is passed through as is.
- Checks before it starts: both `/health` endpoints answer and the Venice session is active. It warns when fewer
than 500 requests are left in the web quota.
- The ports `18891` and `18892` are fixed in the script. If you run either process on another port, edit the
`BRIDGE` and `ADAPTER` lines at the top of `claude-venice`.
> [!WARNING]
> **`claude-venice` adds `--dangerously-skip-permissions --permission-mode bypassPermissions` by default.** Claude Code then runs every tool
> (shell commands, file writes) **without asking you first** — including when resuming an older session with `--resume` that was originally saved in `default` mode. 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". Shell commands run with your full user permissions and are not confined to the
> working folder, and these models make mistakes: use it only on a machine and with files you can afford to have
> changed or deleted. To get permission prompts back,
> set `VENICE_CLAUDE_SKIP_PERMS=0`, or pass your own `--permission-mode ` (any permission flag you pass
> turns the default off; passing `--permission-mode bypassPermissions` still pairs it with `--dangerously-skip-permissions`).
## Use it with Codex CLI
Codex CLI speaks OpenAI Responses, so it also goes through the adapter (bridge and adapter running as above).
This command configures a provider on the command line and writes nothing to `~/.codex`:
```bash
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 ""
```
Measured with Codex CLI 0.163.0 on one machine: 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 the adapter; function tools and
freeform tools such as `apply_patch` do.
## Local models (Ollama, LM Studio, llama.cpp)
A model id of the form `/` is passed straight to that local OpenAI-compatible server, for example
`ollama/qwen3:8b` or `lmstudio/`. Such a request needs no Venice login, uses no tool emulation and spends no
Venice quota. A leading `venice-bridge/` is stripped first, so `venice-bridge/ollama/qwen3:8b` works too.
| Backend | Default base URL |
|---|---|
| `ollama` | `http://127.0.0.1:11434/v1` |
| `lmstudio` | `http://127.0.0.1:1234/v1` |
To add llama.cpp, MLX or any other OpenAI-compatible server, write `~/.config/venice-bridge/backends.json`
(path override: `VENICE_BRIDGE_BACKENDS`). A file **replaces** the defaults, so list every backend you want;
[`examples/backends.json`](https://github.com/nsozturk/venice-bridge/blob/main/examples/backends.json) lists the two defaults plus llama.cpp:
```json
{"backends":[{"name":"llamacpp","base_url":"http://127.0.0.1:8080/v1","api_key":null}]}
```
`api_key` is optional; when set it is sent as `Authorization: Bearer `. An empty list turns local backends
off. The file is read on every request, so edits apply without a restart.
- `GET /v1/models` lists the Venice models plus the models of every reachable backend as `/`. A
backend that is down is skipped and never breaks the list; when Venice itself is unreachable, the local models
are still listed.
- A request to the bridge for a local-prefixed model whose backend is down answers `502` (`local_backend_error`)
and never falls through to Venice.
- The same holds through the adapter: it passes any id that contains a `/` straight to the bridge, so a local
model asked from Claude Code or Codex reaches its backend or fails with `502`; it is never sent to Venice.
## 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.
- End-to-end-encrypted models (`e2ee-*`) are always hidden; they need client-side keys the bridge does not handle.
- `VENICE_EXCLUDE_MODELS` hides more, as comma-separated glob patterns, for example
`VENICE_EXCLUDE_MODELS='qwen3-vl-*,venice-uncensored-*'`.
The filter only changes the list: a hidden model can still be requested by its id.
The list also 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 `/` 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.
```bash
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
```
Limits, so you know what to expect:
- 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.
## Web search (opt-in)
Venice can run its own web search on the chat route. It is **off by default**, because Venice runs it on the
server side and it can compete with the client's own tools in an agent loop.
- Per request, with a suffix on the model id: `:web` (web search and URL scraping), `:xsearch`
(X search), or both, `deepseek-v4-1-flash-uncensored:web:xsearch`. The suffix is removed before the id
reaches Venice. The adapter keeps the suffix when the base id is valid, so `claude-venice -m :web` works.
- For the whole process: start the bridge with `VENICE_WEB=1` and/or `VENICE_X_SEARCH=1`.
Measured: a `:web` request returned a current fact, with `^1^`-style citation markers in the text. Search queries
and the pages Venice fetches go through your Venice account.
## 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**.
- Per request, with a suffix on the model id: `:think` (aliases `:reason`, `:reasoning`). It combines with
the web suffixes, for example `deepseek-v4-1-flash-uncensored:web:think`.
- For the whole process: start the bridge with `VENICE_REASONING=1`.
- From the client: `reasoning_effort` `medium` or `high`. `none`, `minimal`, `low` or no effort means off.
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.
## Response cache
A byte-identical repeat request (same model, messages, tools and parameters; `stream` aside) is answered from an
in-memory cache without a Venice call. Only clean successes (a real answer or a tool call) are stored, and a
stored non-stream result can be replayed as a stream and the reverse. The hit rate is modest by design: it
catches exact retries, and agent turns rarely repeat word for word. Local-backend requests are not cached.
| Variable | Default | Meaning |
|---|---|---|
| `VENICE_BRIDGE_CACHE` | on | `0` disables the cache. |
| `VENICE_BRIDGE_CACHE_MAX` | `256` | Entries kept (least recently used is dropped first). |
| `VENICE_BRIDGE_CACHE_TTL` | `3600` | Seconds an entry stays valid. |
`GET /health` returns the counters: `cache: {hits, misses, stores, entries, enabled}`. The cache lives in memory
only and is emptied when the bridge restarts.
## What it costs: requests, not tokens
The Venice web plan is limited by a daily **request** quota, not by tokens. Every model step an agent takes is
one request; in-bridge retries and the early-stop judge can add more. Fewer requests save quota; shorter prompts
do not. `GET /health` shows `chat_quota.remaining` and `resets_in_min` (`claude-venice --quota` prints both).
To keep working after the quota runs out, use [`venice-auto`](#model-list-and-venice-auto) with a local fallback.
The `usage` numbers in responses are an estimate (about 4 characters per token), because Venice returns no token
counts; the adapter reports `cached_tokens: 0`. Do not read them as billing.
## Autostart with launchd
[`examples/com.example.venice-bridge.plist`](https://github.com/nsozturk/venice-bridge/blob/main/examples/com.example.venice-bridge.plist) is a launchd template that
starts the bridge at login and restarts it if it exits.
[`examples/com.example.venice-adapters.plist`](https://github.com/nsozturk/venice-bridge/blob/main/examples/com.example.venice-adapters.plist) does the same for the
adapter.
1. Replace every `/PATH/TO` with real absolute paths (your `python3` and this folder).
2. Copy the file(s) to `~/Library/LaunchAgents/`.
3. Load them:
```bash
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.venice-bridge.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.venice-adapters.plist
```
The templates write their logs to `venice_bridge.log` and `venice_adapters.log` in this folder. Because they set
`KeepAlive`, a killed process is started again; unload them with
`launchctl bootout gui/$(id -u)/com.example.venice-bridge` (and `…/com.example.venice-adapters`) to stop them.
## How it works
```text
OpenCode / any OpenAI client ──────── POST /v1/chat/completions ────────┐
│
Claude Code ── POST /v1/messages ──┐ │
Codex CLI ──── POST /v1/responses ──┤ │
▼ ▼
venice-adapters 127.0.0.1:18892 ── chat/completions ──► venice-bridge 127.0.0.1:18891
(translation only, optional) │
model "/" ┌────────┴────────┐ any other model
▼ ▼
local server (Ollama, LM Studio, …) venice.ai web backend
```
The adapter only translates messages, tool declarations, tool calls and results, and stream events, then
forwards to the bridge. Nothing about Venice lives in it; its upstream (`VENICE_ADAPTER_UPSTREAM`) can be any
Chat Completions server. Inside the bridge, a Venice request goes like this:
```text
venice-bridge 127.0.0.1:18891
│ 1. __client cookie ──► clerk.venice.ai (session id, ~60 s session JWT)
│ 2. JWT ─────────────► outerface.venice.ai (client attestation)
│ 3. chat request ────► outerface.venice.ai, route chosen by VENICE_BRIDGE_ROUTE (default auto):
│ chat route: /api/inference/chat (JSON lines; auto uses it first)
│ agent route: /api/inference/chat/agents/ad-hoc (SSE; auto uses it on 400 modelNotFound)
▼
Venice web models ──► stream ──► bridge (call readers, tool routing) ──► OpenAI chunks / tool_calls
```
### Routes
`VENICE_BRIDGE_ROUTE` chooses the Venice web route that carries the chat:
| 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`). 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. |
| `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 here: 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.
### Settings sent on the 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](#reasoning-opt-in). Reasoning models want their `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. The adapter
does not forward `temperature`, `top_p` or a reasoning effort, so Claude Code and Codex always run with
reasoning off.
- Always sent: large-context chat on. Venice's own system prompt is off, except on a thinking turn.
- Web search is added only when asked for (see [Web search](#web-search-opt-in)); it applies to the chat route
only.
### Tool calling
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 was invisible to the model; the
chat route offers the model no tools). The bridge therefore emulates tool calling in text. The full mapping
tables (tool-name aliases, argument-name aliases, Venice server-tool names, what is dropped) are in
[docs/TOOL_ROUTING.md](https://github.com/nsozturk/venice-bridge/blob/main/docs/TOOL_ROUTING.md).
- **Tool emulation.** The tool list goes into the system prompt: built-in tools and tools already used in the
conversation with a compact full JSON schema, the rest as one-liners, inside a 78,000-character budget. A real
OpenCode request measured 411 tools and about 441,000 characters of system prompt. The model answers
`{"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 opencode-venice-web's 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).
- **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 ``, several calls per reply, takes
`string="false"` parameters as JSON, and never shows the markup as text.
- **Tagged call reader.** `{"name":...,"arguments":...}` is read too, including file
content with unescaped quotes.
- **Tool routing.** A call to a tool the client did not declare is routed to the client's tool for the same job
(examples in the table below), and Venice server-tool names are mapped back to the client's tools. 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.
- **Argument fitting.** Arguments the model named differently are renamed, for example `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. Leftover arguments the tool's schema
does not know are dropped and logged.
- **Prompt-header hint.** The tool block 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).
- **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.
- **Retries.** In-bridge retries (budget 2) for a server loop, an unreadable call, an empty reply, or a broken
stream.
- **Judge.** A small model (`qwen3-5-35b-a3b` by default) checks short turn endings after a tool result for early
stops, such as a reply that only announces the next step. 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).
- **Error mapping.** Quota used up → 403 `venice_quota_exhausted` with the reset time (OpenCode retries a 429
silently); a passing rate limit → 429; request too large (Venice 413) → 400 `context_length_exceeded`;
Cloudflare challenge → 502 with a clear message; a model the chat route does not know (Venice 400
`modelNotFound`) → sent to the agent route with `auto`, or 502 "Venice answered HTTP 400" with `chat`.
Tool routing examples (foreign name → client tool):
| 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 |
Clerk rotates the `__client` cookie while it is used. The bridge saves the rotated value to
`~/.config/venice-bridge/rotated-client.json` (mode 0600) and keeps using it across restarts.
## Configuration
Environment variables are read when a process starts. Set them before you start it.
### Bridge (`venice_bridge.py`)
| Variable | Default | Purpose |
|---|---|---|
| `VENICE_BRIDGE_HOST` | `127.0.0.1` | Bind address. Keep it on loopback (see [SECURITY.md](https://github.com/nsozturk/venice-bridge/blob/main/SECURITY.md)). `--host` overrides it. |
| `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](#routes). |
| `VENICE_BRIDGE_COOKIE_FILE` | `~/.config/venice-bridge/client-cookie.txt` | File holding the `__client` cookie value. |
| `VENICE_BRIDGE_SESSION_DIR` | empty (off) | Folder with a `client.py` exposing `get_session(domain)` that returns `{"timestamp": , "tokens": {"clerk_client": ""}}`, for a local session daemon. Used when the cookie file is missing or empty. |
| `VENICE_BRIDGE_CLIENT_FILE` | `~/.config/venice-bridge/rotated-client.json` | Where the rotated cookie is saved (mode 0600). |
| `VENICE_BRIDGE_BACKENDS` | `~/.config/venice-bridge/backends.json` | Local backends file. Without it: `ollama` and `lmstudio` defaults. See [Local models](#local-models-ollama-lm-studio-llamacpp). |
| `VENICE_WEB` | off | `1` turns on Venice web search and URL scraping for every request. |
| `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](#reasoning-opt-in). |
| `VENICE_EXCLUDE_MODELS` | empty | 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 `/` while the quota is used up. See [venice-auto](#model-list-and-venice-auto). |
| `VENICE_BRIDGE_CACHE` | on | `0` disables the response cache. |
| `VENICE_BRIDGE_CACHE_MAX` | `256` | Cache entries. |
| `VENICE_BRIDGE_CACHE_TTL` | `3600` | Cache entry lifetime in seconds. |
| `VENICE_BRIDGE_FORMAT_RETRIES` | `2` | In-bridge retries for server loops, unreadable calls, empty replies and broken streams. |
| `VENICE_BRIDGE_JUDGE` | on | `0` turns the early-stop judge off. |
| `VENICE_BRIDGE_JUDGE_MODEL` | `qwen3-5-35b-a3b` | Model used by the judge. |
| `VENICE_BRIDGE_JUDGE_RETRIES` | `1` | Retries the judge may add per turn. |
| `VENICE_BRIDGE_LOOP_MAX_CALLS` | `40` | Tool calls per reply before a runaway reply is cut. |
| `VENICE_BRIDGE_LOOP_MAX_CHARS` | `150000` | Characters per tool-mode reply before it is cut. |
| `VENICE_BRIDGE_PROACTIVE_REFRESH_S` | `30` | Refresh the session token in the background when fewer seconds than this remain. |
| `VENICE_BRIDGE_COOKIE_POOL` | empty (off) | Opt-in multi-account pool: a 0600 file, one `__client` cookie per line (see `cookie-pool.example.txt`). On a quota 429 the bridge moves to the next account. |
| `VENICE_BRIDGE_MAX_ATTACHMENT_BYTES` | `10485760` | Per-file limit for image/document attachments (413 above it). |
| `VENICE_BRIDGE_MAX_TOTAL_ATTACHMENT_BYTES` | `20971520` | Total attachment limit per request. |
| `VENICE_BRIDGE_MAX_AUDIO_BYTES` | `26214400` | Upload limit for `/v1/audio/transcriptions`. |
| `VENICE_BRIDGE_ASR_MODEL` | `nvidia/parakeet-tdt-0.6b-v3` | Venice speech-to-text model. |
Command-line options: `--host` (default `VENICE_BRIDGE_HOST`, else `127.0.0.1`) and `--port` (default `18891`).
The bridge has no client authentication, so keep the host on loopback.
### Adapter (`venice_adapters.py`)
| Variable | Default | Purpose |
|---|---|---|
| `VENICE_ADAPTER_HOST` | `127.0.0.1` | Bind address. Keep it on loopback. |
| `VENICE_ADAPTER_PORT` | `18892` | Port. |
| `VENICE_ADAPTER_UPSTREAM` | `http://127.0.0.1:18891/v1` | The Chat Completions server it forwards to (the bridge). |
| `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` | empty (off) | An existing folder: every request body is saved there as JSON. Debugging only; the bodies contain your prompts and file contents. |
The adapter has no command-line options.
### Launcher (`claude-venice`)
| Variable | Default | Purpose |
|---|---|---|
| `VENICE_CLAUDE_MODEL` | `deepseek-v4-1-flash-uncensored` | Venice model id (`-m ` overrides it). |
| `VENICE_CLAUDE_SKIP_PERMS` | `1` | `0` stops the launcher from adding `--dangerously-skip-permissions`. |
## API
### Bridge, `127.0.0.1:18891`
| Method and path | Purpose | Status codes |
|---|---|---|
| `POST /v1/chat/completions` | OpenAI Chat Completions, streaming and non-streaming, with `tools` / `tool_calls`. A `/` id is passed to that local backend; `venice-auto` is resolved first. When the model returns reasoning (see [Reasoning](#reasoning-opt-in)), it comes as `reasoning_content` (message field, or `delta.reasoning_content` when streaming). | `200`; `400` invalid JSON or `context_length_exceeded`; `402` plan or credits; `401`/`403` Venice refusal; `403` quota used up; `429` passing rate limit; `502` upstream, local backend (`local_backend_error`) or bridge failure |
| `GET /v1/models` | `venice-auto` first, then the Venice models the account's web catalogue offers without credits (minus `e2ee-*` and `VENICE_EXCLUDE_MODELS`), plus `/` for every reachable local backend. | `200`; `502` when nothing can be listed |
| `GET /health` | Session state, remaining web chat quota (`chat_quota`), cache counters (`cache`). | `200`; `503` no usable login |
| `GET /stats` | Live runtime counters (requests, models, TTFT, retries, cache, pool, endpoint counts); `?format=html` renders a minimal dark dashboard. | `200` |
| `POST /v1/audio/transcriptions` | OpenAI Whisper-compatible speech-to-text (`multipart/form-data`: `file`, `model`, `response_format` `json`/`text`/`verbose_json`), backed by Venice ASR (`nvidia/parakeet-tdt-0.6b-v3`). Supports mp3/wav/m4a/webm/ogg/flac up to `VENICE_BRIDGE_MAX_AUDIO_BYTES` (25 MB). | `200`; `400` bad format; `413` too large; `502` upstream failure |
| `POST /v1/images/generations` | OpenAI Image Generation (`{"prompt", "n": 1, "size", "response_format": "b64_json"|"url"}`, where `url` returns a `data:` URI), backed by Venice in-chat image generation (`image_chunk`). Uses 1 chat + 1 image quota call. | `200`; `400` invalid prompt / `n != 1`; `502` upstream failure |
| `POST /reload` | Drops cached auth (cookie, session, token, attestation) and the local quota lock (also the over-quota state of `venice-auto`). | `200` |
### Adapter, `127.0.0.1:18892`
| Method and path | Purpose | Status codes |
|---|---|---|
| `POST /v1/messages` | Anthropic Messages (Claude Code), streaming and non-streaming, with tools. | `200`; upstream status passed through; `400` body not JSON; `502` the bridge did not answer |
| `POST /v1/messages/count_tokens` | An estimate (`input_tokens` ≈ request size / 4). | `200` |
| `POST /v1/responses` | OpenAI Responses (Codex CLI), streaming and non-streaming, with function and freeform tools. | as `/v1/messages` |
| `GET /v1/models` | The upstream's model list, passed through. | `200`; `502` |
| `GET /health` | `{"ok": true, "upstream": "...", "default_model": "..."}`. It does not check the bridge. | `200` |
On both processes any other path answers `404`.
## Measured performance
Measured in November 2026 on one machine with one account. These are observations, not guarantees.
- Bridge overhead per request: about 21 ms with a 441k-character prompt and 401 tools (against a 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 |
### 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. Measured on one machine, one account. Treat venice-bridge as a cheap runner for exploratory
work, check what it produces, and do not use it for high-stakes changes.
### 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`** (pass `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 `/` through 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 |
|---|---|---|
| `403` with "Venice rejected the request (403): creator_access_required" | The request went to the agent route on a free account; that route needs a paid plan. | Use an account with a paid Venice web plan (Pro). With `VENICE_BRIDGE_ROUTE=agent`, try `auto`. |
| `403` with `error.type` `venice_quota_exhausted` and "Resets in about N min" | The web chat quota of the account is used up. The bridge answers locally until the reset. | Wait for the reset. `GET /health` shows the remaining quota and the reset time. To keep working meanwhile, use [`venice-auto`](#model-list-and-venice-auto) with a local fallback. |
| `429` with `error.type` `venice_rate_limited` | A passing Venice rate limit while quota is left. | Retry after a short wait; clients usually back off on their own. |
| `502` with "Cloudflare challenged the request" | Cloudflare challenged the upstream call. | Open venice.ai in your browser, refresh the cookie file (or sync your session daemon), then retry. |
| "No venice.ai login found" (`503` on `/health`, `502` on chat) | The cookie file is missing or empty and no session daemon is configured. | Save the cookie as in [Quick start](#1-save-your-veniceai-login-cookie), or set `VENICE_BRIDGE_COOKIE_FILE`. |
| "Clerk ... rejected" or "token mint failed" | The saved cookie is no longer valid. | Log in on venice.ai again, save a fresh cookie, then `curl -s -X POST http://127.0.0.1:18891/reload`. |
| `400` with `context_length_exceeded` | The request is larger than Venice accepts (Venice 413). | Start a new session or compact the conversation; use a model with a larger context. |
| `402` "Your Venice plan or credits do not cover this model" | The model needs credits or a higher plan. | Pick a model that `GET /v1/models` lists. |
| 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). Venice took the model's native tool call for one of its own server tools. | 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` with "Venice answered HTTP 400: … modelNotFound" while `VENICE_BRIDGE_ROUTE=chat` | That model exists only on the agent route. | Use `VENICE_BRIDGE_ROUTE=auto`. |
| `claude-venice`: "venice-bridge (…) is down" or "venice-adapters (…) is down" | The bridge or the adapter is not running on its default port. | Start it (`python3 venice_bridge.py`, `python3 venice_adapters.py`), or load the launchd templates. |
| `claude-venice`: "Venice web session is not active" | The login cookie expired. | Save a fresh cookie as in [Quick start](#1-save-your-veniceai-login-cookie), then `POST /reload`. |
| Claude Code: "Auto mode could not evaluate this action and is blocking it for safety" | Auto mode's safety classifier needs a model that Venice's fast models cannot replace. | Leave the launcher's default (`VENICE_CLAUDE_SKIP_PERMS=1`), or pass a `--permission-mode ` other than `auto` to be asked before tools run. |
| `502` with `local_backend_error` "Local backend '…' (…) did not answer" | The local server for that model prefix is not running, or its URL is wrong. | Start it; check `~/.config/venice-bridge/backends.json`. |
| Log line "backends.json is not valid JSON; using the default backends" | A syntax error in the backends file. | Fix the JSON; it is read again on the next request. |
| Codex cannot use MCP servers, multi-agent tools or `web_search` | Namespace tools and Codex's built-in `web_search` do not pass through the adapter. | Use function tools only, or the bridge's opt-in [web search](#web-search-opt-in). |
The bridge logs to stderr (or to `venice_bridge.log` under the launchd template). Lines start with
`[venice-bridge]` and include upstream status codes, per-request timing and cache hits; the `timing open:` line
ends with `route=chat` or `route=agent`. The adapter logs one `[venice-adapters]` line per request (model, stream,
number of tools and messages, time).
## FAQ
### Does it need a Venice API key?
No. It uses the venice.ai web app's own backend with your browser login (the `__client` cookie). It does not
call the paid Venice API. The `apiKey` value in the OpenCode config is a placeholder.
### Does it cost tokens?
No. The Venice web plan is limited by a daily number of requests, not by tokens. The `usage` numbers in responses
are estimates (about 4 characters per token). Fewer requests save quota; shorter prompts do not. See
[What it costs](#what-it-costs-requests-not-tokens).
### 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 (`venice_adapters.py` on `127.0.0.1:18892`), which translates Anthropic Messages and
OpenAI Responses into Chat Completions for the bridge. For Claude Code use the `claude-venice` launcher; for
Codex CLI pass a provider on the command line. See [Use it with Claude Code](#use-it-with-claude-code) and
[Use it with Codex CLI](#use-it-with-codex-cli). Venice's fast models are weak at long agentic chains, so expect
to check their work.
### Does it run local models?
Yes. A model id `/` (for example `ollama/qwen3:8b`) goes straight to that local
OpenAI-compatible server: Ollama and LM Studio by default, llama.cpp, MLX or others through
`~/.config/venice-bridge/backends.json`. No Venice login, no tool emulation, no quota. See
[Local models](#local-models-ollama-lm-studio-llamacpp).
### 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](#model-list-and-venice-auto).
### Can I use it from Docker?
Yes. A container reaches a bridge bound to `127.0.0.1` 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: it has no
client authentication.
### Does it work on Linux or Windows?
Untested. It relies on the system `curl` to pass Cloudflare, and that has only been verified on macOS.
### Is this allowed by Venice?
venice-bridge is unofficial and uses undocumented web endpoints. Automating your logged-in web session may be
against Venice's terms of service. Use it at your own risk, with your own account only, and do not share cookies
or accounts.
### Where do my chats go?
From the bridge, Venice requests go only to Venice (`clerk.venice.ai` for login, `outerface.venice.ai` for
models, quota and chat), under your own account. With the judge on, a short extra request per checked turn also
goes to Venice. With web search on, Venice runs the searches and fetches the pages under your account. A
local-prefixed model goes only to its local backend. The adapter talks only to its upstream (the bridge by
default).
On disk, the bridge keeps only the rotated login cookie; each upstream call writes its headers and body to a
private temporary folder that is removed when the call ends. The response cache is in memory only. The adapter
writes request bodies to disk only when `VENICE_ADAPTER_DUMP` is set. The logs record request sizes, timing,
status codes, model names and short fragments of Venice's own tool steps. How Venice stores chats is governed by
Venice, not by this project.
### Is it an alternative to opencode-venice-web?
It solves the same problem in Python instead of Node. opencode-venice-web is the most mature Venice web proxy and
sends full schemas for every tool; venice-bridge sends full schemas only for built-in and already-used tools and
one-liners for the rest, to fit large tool lists. Its tolerant parser is a port of opencode-venice-web's.
## Alternatives / compared with
| Project | What it is |
|---|---|
| [CanArslanDev/opencode-venice-web](https://github.com/CanArslanDev/opencode-venice-web) | Node. The most mature Venice web proxy; sends full schemas for every tool. |
| [aintlikeu/unofficial-venice-proxy](https://github.com/aintlikeu/unofficial-venice-proxy) | Another Venice web proxy. |
| [zalo-alex/venice-opencode](https://github.com/zalo-alex/venice-opencode) | Another Venice web proxy. |
| Official Venice API | Paid, metered credits with an API key; OpenCode has a built-in `venice` provider for it. |
## Tests
Two offline self-checks. They use temporary files and fake servers on localhost, never the real Venice
endpoints, and need no running bridge.
```bash
python3 test_venice_bridge.py
```
```text
cookie file ok
session ok
ok
end to end ok
local backends ok
reasoning + venice-auto prefix ok
```
```bash
python3 test_venice_adapters.py
```
```text
messages ok
pick_model ok
responses ok
```
Success is these lines and exit status 0. A failure stops with an `AssertionError` traceback and a non-zero exit
status.
A live check of a running setup (bridge up and logged in):
```bash
claude-venice --quota
```
```text
Venice web quota remaining= resets_in_min=
Bridge cache hits= misses= entries= enabled=True
```
If the bridge does not answer it prints `could not read http://127.0.0.1:18891/health`.
## Credits
`tolerant_parser.py` is a Python port of the tolerant tool-call parser of
[opencode-venice-web](https://github.com/CanArslanDev/opencode-venice-web), and the malformed-reply fixtures come
from the same project; several reminder texts and the judge prompt are adapted from it. All are used under the MIT
License. See [NOTICE.md](https://github.com/nsozturk/venice-bridge/blob/main/NOTICE.md) and
[THIRD_PARTY_LICENSE-opencode-venice-web.txt](https://github.com/nsozturk/venice-bridge/blob/main/THIRD_PARTY_LICENSE-opencode-venice-web.txt).
## License
[MIT](https://github.com/nsozturk/venice-bridge/blob/main/LICENSE) © 2026 venice-bridge contributors.
---
# AGENTS.md — venice-bridge
Contract for coding agents (Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Antigravity) that use this tool or
change this repository. Read it before you run, configure, or edit anything here.
## What it is
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.
- **Bridge** (`venice_bridge.py`) on `127.0.0.1:18891`, speaking OpenAI Chat Completions. Upstream is the
venice.ai web app's own backend (`clerk.venice.ai` for login, `outerface.venice.ai` for chat), authenticated with
the user's browser login. It is not the paid Venice API and needs no API key.
- **Adapter** (`venice_adapters.py`, optional, standard library only) on `127.0.0.1:18892`, speaking Anthropic
Messages (Claude Code) and OpenAI Responses (Codex CLI). It only translates and forwards to the bridge; nothing
about Venice lives in it.
- **Launcher** (`claude-venice`, bash) runs the Claude Code CLI against the adapter in an isolated profile.
- `VENICE_BRIDGE_ROUTE` picks the Venice route: `auto` (default) uses the chat route `/api/inference/chat` and
sends a model it does not know (`400 modelNotFound`) to the agent route `/api/inference/chat/agents/ad-hoc`;
`chat` and `agent` force one route. The chat route has no Venice agent loop and no Venice tools, so no call is
swallowed; the client's system prompt travels in the first user message. The log line `timing open: … route=`
shows the route.
- A model id `/` (default backends `ollama`, `lmstudio`) is passed straight to that local
OpenAI-compatible server: no Venice login, no tool emulation, no quota.
- Tested on a paid Venice web 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.
- Unofficial; the endpoints are undocumented and may change. Using it may be against Venice's terms of service.
- No images. Venice's fast models are weak at long agentic chains: do not trust their output on high-stakes work.
- Cost is a daily **request** quota, not tokens. `usage` numbers are estimates (about 4 characters per token).
## Start, stop, check
| Action | Command |
|---|---|
| Install the dependency | `pip install curl_cffi` (or `pip install -r requirements.txt`); the adapter needs nothing extra |
| Start the bridge | `python3 venice_bridge.py` (options: `--host`, `--port`; default `127.0.0.1:18891`) |
| Start the adapter (Claude Code, Codex) | `python3 venice_adapters.py` (environment only, no options; default `127.0.0.1:18892`) |
| Stop a foreground run | Ctrl-C |
| Check the bridge | `curl -s http://127.0.0.1:18891/health` → `200` with `"ok": true`, `"venice_session": "active"`, `chat_quota`, `cache` |
| Check the adapter | `curl -s http://127.0.0.1:18892/health` → `200` `{"ok": true, "upstream": ..., "default_model": ...}` (does not probe the bridge) |
| List models | `curl -s http://127.0.0.1:18891/v1/models` (`venice-auto` first, then the Venice models the web subscription covers, plus `/` of reachable local backends) |
| Drop cached auth after a new cookie | `curl -s -X POST http://127.0.0.1:18891/reload` |
| Autostart (launchd) | Fill in `examples/com.example.venice-bridge.plist` and `examples/com.example.venice-adapters.plist`, copy to `~/Library/LaunchAgents/`, `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/` |
| Stop under launchd | `launchctl bootout gui/$(id -u)/com.example.venice-bridge` (and `…/com.example.venice-adapters`); the plists set `KeepAlive`, so killing the process restarts it |
Before starting a second instance, check `/health`: the port may already be in use by a running process.
The only setup step is the login cookie: the value of the `__client` cookie of `clerk.venice.ai`, saved to
`~/.config/venice-bridge/client-cookie.txt` (mode 0600). Only the user can obtain it from their browser. If it is
missing, ask the user to follow README "Quick start" step 1; never try to obtain it yourself.
## Clients
| Client | How |
|---|---|
| OpenCode | Provider block from `examples/opencode.json`, then `opencode -m venice-bridge/`. |
| Any OpenAI Chat Completions client | Base URL `http://127.0.0.1:18891/v1`, any API key. |
| Docker container | `http://host.docker.internal:18891/v1` reaches a bridge bound to `127.0.0.1` (measured with Docker Desktop on macOS). Do not bind to `0.0.0.0`. |
| Claude Code | `claude-venice` (needs bridge and adapter). See below. |
| Codex CLI | `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 ""` (writes nothing to `~/.codex`; measured with Codex CLI 0.163.0). Namespace tools (MCP, multi-agent) and Codex's built-in `web_search` do not pass through. |
### `claude-venice`
- Usage: `claude-venice` · `claude-venice -m ` · `VENICE_CLAUDE_MODEL= claude-venice` ·
`claude-venice --models` · `claude-venice --quota`. `-m`, `--models` and `--quota` must be the first argument;
everything else goes to `claude`.
- Sets `CLAUDE_CONFIG_DIR=~/.claude-venice`, unsets `ANTHROPIC_API_KEY`, sets `ANTHROPIC_BASE_URL=http://127.0.0.1:18892`,
a filler `ANTHROPIC_AUTH_TOKEN`, and points `ANTHROPIC_MODEL` and the opus/sonnet/haiku default-model variables
at the chosen id. The user's normal `claude` profile is not touched.
- Preflight: exits 1 with a message if the bridge or adapter `/health` does not answer, or the Venice session is
not active; warns when fewer than 500 requests are left. Ports `18891` and `18892` are fixed in the script.
- **It adds `--dangerously-skip-permissions` by default, so Claude Code runs tools without asking.** Reason:
Venice's fast models cannot drive Claude Code's auto-mode safety classifier ("Auto mode could not evaluate this
action and is blocking it for safety"). Opt out with `VENICE_CLAUDE_SKIP_PERMS=0` or by passing any
`--permission-mode`. Never start it on the user's behalf in a folder they have not chosen, and tell the user
that prompts are off.
- `--quota` prints two lines and exits 0 even when the bridge is down (it then prints `could not read …/health`).
## Endpoints
### Bridge, `127.0.0.1:18891`
| Method and path | Success | Errors |
|---|---|---|
| `POST /v1/chat/completions` | `200` JSON, or `200` `text/event-stream` when `"stream": true` | `400` invalid JSON; `400` `context_length_exceeded` (Venice 413); `402` plan or credits; `403` `venice_quota_exhausted`; `401`/`403` Venice refusal (for example `creator_access_required`); `429` `venice_rate_limited`; `502` `venice_upstream_error`, `bridge_error` or `local_backend_error` |
| `GET /v1/models` | `200` `{"object":"list","data":[...]}`: `venice-auto` first, then Venice models without credits (never `e2ee-*`, minus `VENICE_EXCLUDE_MODELS` globs), then local models (local models alone when Venice is unreachable). Hidden models can still be requested by id. | `502` `bridge_error` when nothing can be listed |
| `GET /health` | `200` `{"ok":true,"venice_session":"active","chat_quota":{"remaining","resets_in_min",...},"cache":{"hits","misses","stores","entries","enabled"}}` | `503` `{"ok":false,"error":"..."}` |
| `POST /reload` | `200` `{"ok":true}` | — |
| any other path | — | `404` |
Upstream and bridge errors use the OpenAI shape `{"error":{"message","type","code"}}`; the `404` and
invalid-JSON `400` bodies carry only `message`. The HTTP status and `error.code` can differ on purpose:
- Quota used up: HTTP `403`, `type` `venice_quota_exhausted`, `code` `429`. It is a 403 because OpenCode retries a
429 silently. While the quota is known to be used up, the bridge answers locally without calling Venice.
- Cloudflare challenge: HTTP `502`, `type` `venice_upstream_error`, `code` `403`.
- In a stream that has already started, a failure is sent as a final `data: {"error":{...}}` event without a
normal ending; failures before the status line are a `502`, which OpenCode retries.
- A local-prefixed model whose backend is down: `502` `local_backend_error`; it never falls through to Venice.
A request without `model` uses `qwen3-coder-480b-a35b-instruct-turbo`. A `venice-bridge/` prefix on the model id
is stripped. A suffix `:web` (web search and URL scraping) or `:xsearch` (X search), combinable, turns on Venice
web search for that request on the chat route and is removed before the id reaches Venice; off by default.
Other request behaviour on the chat route: `temperature` and `top_p` are forwarded when set; `max_tokens` is
ignored. A byte-identical repeat request (stream flag aside) is answered from the in-memory response cache without
a Venice call; local-backend requests are not cached.
Reasoning is off by default. A thinking turn is made only when asked for (model suffix `:think`, aliases `:reason`
/ `:reasoning`, combinable with `:web`; `VENICE_REASONING=1`; or `reasoning_effort` `medium` / `high`) **and** the
request declares no tools. The chain of thought comes back as `reasoning_content` (message field, or
`delta.reasoning_content` chunks before `content` when streaming). Chat route only. With tools, `:think` and
`VENICE_REASONING` are ignored: reasoning models want `reasoning_content` passed back on the next tool turn, which
agents do not do (HTTP 400). So `:think` has no effect in OpenCode / Claude Code / Codex agent loops. A
`reasoning_effort` is ignored with tools too: nothing about reasoning reaches Venice on a tool request.
`venice-auto` (virtual model) resolves to the first Venice id in `VENICE_AUTO_MODELS`; while the bridge knows the
web quota is used up, to the first local `/` entry, until the reset Venice reports. The request
that hits the limit still fails once with `403` `venice_quota_exhausted`; the local backend must be running
(else `502`); a suffix is kept for the Venice model and dropped for the local one; `POST /reload` clears the
over-quota state. Use: `opencode -m venice-bridge/venice-auto` (list it in the OpenCode provider's `models`),
`claude-venice -m venice-auto`.
### Adapter, `127.0.0.1:18892`
| Method and path | Success | Errors |
|---|---|---|
| `POST /v1/messages` | `200` Anthropic Messages JSON or SSE | upstream status passed through; `400` body not JSON; `502` the bridge did not answer. Body `{"type":"error","error":{"type","message"}}` |
| `POST /v1/messages/count_tokens` | `200` `{"input_tokens": }` (estimate) | — |
| `POST /v1/responses` | `200` OpenAI Responses JSON or SSE (ends with `response.completed`) | as above; body `{"error":{"type","message","code":null,"param":null}}` |
| `GET /v1/models` | the upstream's list, passed through | `502` |
| `GET /health` | `200` `{"ok":true,"upstream":"...","default_model":"..."}` | — |
| any other path | — | `404` |
The adapter forwards tool declarations, tool calls and results, `max_tokens` (`max_output_tokens` for Responses)
and the stream flag. It does not forward `temperature`, `top_p` or a reasoning effort. Freeform Responses tools
(such as `apply_patch`) become a function with one `input` string. An id that contains a `/` (a local `backend/model`, or
`venice-bridge/...`) is passed through unchanged, so a local model never falls back to Venice; any other id the
upstream does not list (checked against a model list refreshed every 5 minutes) is replaced with
`VENICE_ADAPTER_MODEL`; a `:web` / `:xsearch` suffix is kept when the base id is listed. Images and documents are replaced by a short
"omitted" note. `usage` reports `cached_tokens: 0`.
## Environment variables
Read once at start; set them before starting the process.
### Bridge
| Variable | Default | Meaning |
|---|---|---|
| `VENICE_BRIDGE_HOST` | `127.0.0.1` | Bind address (`--host` overrides). |
| `VENICE_BRIDGE_ROUTE` | `auto` | `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). |
| `VENICE_BRIDGE_COOKIE_FILE` | `~/.config/venice-bridge/client-cookie.txt` | Cookie file (bare value or `__client=...;`). |
| `VENICE_BRIDGE_SESSION_DIR` | empty | Folder with a `client.py` exposing `get_session(domain)` → `{"timestamp": , "tokens": {"clerk_client": ""}}`. Used when the cookie file is missing or empty. |
| `VENICE_BRIDGE_CLIENT_FILE` | `~/.config/venice-bridge/rotated-client.json` | Rotated cookie, written with mode 0600. |
| `VENICE_BRIDGE_BACKENDS` | `~/.config/venice-bridge/backends.json` | Local backends: `{"backends":[{"name","base_url","api_key"}]}`. A file replaces the defaults (`ollama` → `http://127.0.0.1:11434/v1`, `lmstudio` → `http://127.0.0.1:1234/v1`); an empty list turns them off. Read per request. Example: `examples/backends.json`. |
| `VENICE_WEB` | off | `1`: Venice web search and URL scraping on every chat-route request. |
| `VENICE_X_SEARCH` | off | `1`: Venice X search on every chat-route request. |
| `VENICE_REASONING` | off | `1`: reasoning on every request that declares no tools. |
| `VENICE_EXCLUDE_MODELS` | empty | Comma-separated globs hidden from `GET /v1/models` (credit models and `e2ee-*` are always hidden). |
| `VENICE_AUTO_MODELS` | `deepseek-v4-1-flash-uncensored,ollama/qwen3:8b` | `venice-auto` candidates: first Venice id normally, first local `/` while over quota. |
| `VENICE_BRIDGE_CACHE` | on | `0` disables the response cache. |
| `VENICE_BRIDGE_CACHE_MAX` | `256` | Cache entries (LRU). |
| `VENICE_BRIDGE_CACHE_TTL` | `3600` | Cache entry lifetime, seconds. |
| `VENICE_BRIDGE_FORMAT_RETRIES` | `2` | In-bridge retries: server loop, unreadable call, empty reply, broken stream. |
| `VENICE_BRIDGE_JUDGE` | on | `0` disables the early-stop judge. |
| `VENICE_BRIDGE_JUDGE_MODEL` | `qwen3-5-35b-a3b` | Judge model. |
| `VENICE_BRIDGE_JUDGE_RETRIES` | `1` | Retries the judge may add per turn. |
### Adapter
| Variable | Default | Meaning |
|---|---|---|
| `VENICE_ADAPTER_HOST` | `127.0.0.1` | Bind address. |
| `VENICE_ADAPTER_PORT` | `18892` | Port. |
| `VENICE_ADAPTER_UPSTREAM` | `http://127.0.0.1:18891/v1` | Chat Completions server to forward to. |
| `VENICE_ADAPTER_MODEL` | `deepseek-v4-1-flash-uncensored` | Model used when the client asks for one the upstream does not list (`claude-...`, `gpt-...`). |
| `VENICE_ADAPTER_DUMP` | empty | An existing folder: every request body is written there as JSON. Debugging only; bodies contain prompts and file contents. |
### Launcher
| Variable | Default | Meaning |
|---|---|---|
| `VENICE_CLAUDE_MODEL` | `deepseek-v4-1-flash-uncensored` | Venice model id (`-m` overrides). |
| `VENICE_CLAUDE_SKIP_PERMS` | `1` | `0`: do not add `--dangerously-skip-permissions`. |
## Tests
```bash
python3 test_venice_bridge.py
python3 test_venice_adapters.py
```
Offline: temporary files and fake servers on localhost; no running bridge needed. Success is exit status 0 and
these lines, in order:
```text
cookie file ok
session ok
ok
end to end ok
local backends ok
reasoning + venice-auto prefix ok
```
```text
messages ok
pick_model ok
responses ok
```
Any `AssertionError` or non-zero exit is a failure. Run `test_venice_bridge.py` after every change to
`venice_bridge.py` or `tolerant_parser.py`, and `test_venice_adapters.py` after every change to
`venice_adapters.py`. After editing `claude-venice`, run `bash -n claude-venice`.
Live check of a running setup: `claude-venice --quota` prints `Venice web quota remaining=… resets_in_min=…` and
`Bridge cache hits=… misses=… entries=… enabled=…`.
## Files
| File | Owns |
|---|---|
| `venice_bridge.py` | HTTP server, Clerk login and cookie rotation, attestation, route choice (chat / agent), OpenAI ↔ Venice translation, chat-route settings, opt-in web search, local-backend passthrough, response cache, tool emulation prompt, native and tagged call readers, tool routing and argument fitting, retries, judge, stream gate, error mapping. |
| `venice_adapters.py` | Anthropic Messages and OpenAI Responses ↔ Chat Completions translation, model fallback, stream events. Standard library only. |
| `claude-venice` | Bash launcher for Claude Code on the adapter (isolated profile, preflight, permission default). |
| `tolerant_parser.py` | Reading tool calls from model text (lenient JSON, envelopes, broken replies). Port of opencode-venice-web, MIT. |
| `test_venice_bridge.py`, `test_venice_adapters.py` | Offline self-checks. |
| `test_fixtures_real_replies.json` | Real malformed model replies (from opencode-venice-web, MIT). |
| `test_fixture_tagged_call.json` | Fixture for the `...` reader. |
| `docs/TOOL_ROUTING.md` | Tool-name and argument-name mapping reference. |
| `examples/opencode.json` | OpenCode provider block with the example models. |
| `examples/backends.json` | Local backends file (the two defaults plus llama.cpp). |
| `examples/com.example.venice-bridge.plist`, `examples/com.example.venice-adapters.plist` | launchd templates (replace `/PATH/TO`). |
| `NOTICE.md`, `THIRD_PARTY_LICENSE-opencode-venice-web.txt` | Third-party attribution. |
| `LICENSE` | MIT. |
| `pyproject.toml`, `requirements.txt` | Package metadata and the single dependency (`curl_cffi`). |
## Rules
1. **Never print, log, paste, or commit the cookie**, the rotated-client file, a session JWT, or an attestation
token. Use placeholders such as `` in examples. `client-cookie.txt` and
`rotated-client.json` are in `.gitignore`; keep them there.
2. **Never point tests at the real Venice endpoints.** Tests use fake upstreams on localhost and temp files;
keep `CLIENT_STATE_FILE` and `COOKIE_FILE` redirected to a temp dir in any new test.
3. **Tools mode never sends a partial tool call.** The status line and the first 200 characters are held until
the reply can no longer become a tool call or a retry; only prose past that point streams live, and a tail
that may still become a call is held back. Keep this property when changing the stream path, because it is
what lets a failed turn reach OpenCode as a retryable 502.
4. **A reply counts only after its completion signal**: `response.completed` on the agent route, a clean end of
the HTTP response (curl exit code 0) on the chat route. Do not emit a cut stream as a normal answer.
5. **Keep the attribution** in `tolerant_parser.py`, `NOTICE.md`, and `THIRD_PARTY_LICENSE-opencode-venice-web.txt`.
6. **Bind to loopback only.** Neither process has client authentication; never start the bridge with a
non-loopback `--host` or `VENICE_BRIDGE_HOST`, or the adapter with a non-loopback `VENICE_ADAPTER_HOST`. Docker
containers use `host.docker.internal` instead.
7. **Never leave `VENICE_ADAPTER_DUMP` set** outside a debugging session, and never commit a dump folder.
8. **A local-prefixed model must never fall through to Venice in the bridge**: the route is chosen by the prefix
alone, never by asking the backend.
9. **Respect the quota.** Every model step is one Venice request; do not loop on retries after a `403`
`venice_quota_exhausted`.
## Common failures
| Symptom | What to do |
|---|---|
| `/health` → `503` "No venice.ai login found" | Ask the user to save the cookie (README Quick start step 1). |
| "Clerk ... rejected" / "token mint failed" | The cookie expired. Ask the user to log in on venice.ai and save a fresh cookie, then `POST /reload`. |
| `403 creator_access_required` | The agent route on a free account. Nothing to fix in code; the agent route needs a paid web plan. If `VENICE_BRIDGE_ROUTE=agent` is set, try `auto`. |
| `403 venice_quota_exhausted` | Wait for the reset shown in the message; do not loop on retries. Another Venice model will not help (the quota is plan-wide); `venice-auto` with a running local backend keeps working. |
| `502` "Cloudflare challenged the request" | Ask the user to open venice.ai in the browser and refresh the cookie file. |
| `400 context_length_exceeded` | Shorten or compact the conversation. |
| Model claims its tools are unavailable / "Tool not found" | The request used the agent route (check `route=` in the log), where Venice swallows native tool calls. Use `VENICE_BRIDGE_ROUTE=auto` or `chat`, or a model that exists on the chat route; in an existing conversation tell the model its tools work now, or start a new session. |
| `502` "Venice answered HTTP 400: … modelNotFound" with `VENICE_BRIDGE_ROUTE=chat` | The model exists only on the agent route. Use `auto`. |
| `502` `local_backend_error` | The local server for that prefix is down or misconfigured in `backends.json`. Start it; do not retry against Venice. |
| `claude-venice` exits "… is down" / "session is not active" | Start the bridge and adapter / ask the user for a fresh cookie. |
| Claude Code "Auto mode could not evaluate this action" | Auto mode cannot work with these models; use the launcher default or a `--permission-mode ` other than `auto`. |
| `Address already in use` on start | A process is already running on that port; check `/health` instead of starting another. |
---
# Tool routing — Claude Code / OpenCode / Codex → Venice
How a client's tools reach the Venice web model and how the model's tool calls are mapped back.
Source of truth is the code (`venice_bridge.py`, `venice_adapters.py`); this page describes v0.2.6.
## TL;DR
No client tool is dropped. The adapter forwards **every** well-formed tool 1:1; the bridge describes **all** of them to the model. Venice never receives a `tools` array — the bridge
puts a `[TOOLS]` block in the system prompt (`openai_to_venice_chat` → `_build_tool_instructions`,
`venice_bridge.py`) and the model replies with `{"tool_calls":[…]}`, which the bridge parses and
routes. The two places behaviour varies are: **how much schema detail** each tool gets (an 78 KB budget),
and **how a wrong tool name / argument name the model invents is mapped** to the real client tool.
## 1. Forwarding — adapter (Anthropic → OpenAI), `messages_to_chat` (`venice_adapters.py`)
| Incoming (Claude Code) | Mapped to | Status |
|---|---|---|
| `name` | `function.name` | verbatim |
| `description` | `function.description` | verbatim |
| `input_schema` | `function.parameters` | verbatim |
| `tools` array | all of them | forwarded; only a tool with **no name** or a non-dict `input_schema` is skipped |
| `tool_choice` | — | not carried (the bridge ignores it anyway) |
| `max_tokens` | `max_tokens` | forwarded when an int |
The bridge does **not** send tools to Venice: `payload["tools"]=[]`, `payload["clientTools"]=[]`
(`venice_bridge.py`). Tools travel as text in the system prompt instead.
## 2. Schema-detail tiers — `_build_tool_instructions` (`venice_bridge.py`), budget `TOOL_BLOCK_BUDGET=78_000`
| Tier | Which tools | Detail given to the model |
|---|---|---|
| **A** (never cut) | tools already called earlier in the conversation · names **without an underscore** (the CC built-ins: `Bash Read Write Edit Glob Grep Task WebFetch WebSearch TodoWrite …`) · `CORE_TOOL_NAMES` = `apply_patch` | **full compact argument schema** |
| **B** (underscore names → mostly `mcp__*`) | everything else | one-liner → (over budget) shorter description → name-only, announced on the last line |
Floor guarantee: header + all of Tier A in full + **every** tool at least by name — nothing disappears. So a plain `claude-venice` with no MCP servers sends essentially **all** tools with full
schema; the budget only degrades Tier B when many `mcp__*` tools are present. The per-request log line
`tool list: A=… B=… names only=… block=… of 78000 … full schema for: …` reports exactly what
each request sent.
## 3. Name routing — model invents a wrong name → real client tool, `TOOL_ALIASES` / `_route_call` (`venice_bridge.py`)
| Client tool | Names the model uses that map to it |
|---|---|
| `bash` | shell, sh, zsh, terminal, execute, exec, run, run_command, run_shell_command, run_terminal_cmd, python, code_interpreter, calculator, container.exec, exec_command, local_shell … |
| `read` | cat, read_file, view, view_file, open, open_file, get_file, head, tail, get_attachment, view_media, hydrate_content |
| `write` | write_file, create_file, save_file, write_to_file, replace_file |
| `edit` | edit_file, str_replace, str_replace_editor, apply_edit, update_file, search_replace |
| `grep` | search, rg, ripgrep, search_files, grep_search, find_in_files, codebase_search, content_search … |
| `glob` | find, find_files, file_search, search_file_names |
| `websearch` | web_search, search_web, google, google_search, bing_search, brave_search … |
| `webfetch` | web_scrape, web_fetch, fetch, fetch_url, browse, open_url, http_get, scrape |
| `task` | agent, sub_agent, spawn_agent, launch_agent, dispatch_agent, delegate, new_task, create_subagent … |
| `skill` | use_skill, load_skill, run_skill, invoke_skill |
| `question` | askuserquestion, ask_user, ask_followup_question, ask, clarify … |
| listing (`ls`, `list_files`, `dir`, `tree` …) | to a declared `list` tool, else `bash: ls -la ` |
| SQL (`sql_query`, `sqlite_query`, `db_query`, `execute_sql`, `run_sql`, `sql` …) | `bash: sqlite3 -readonly ` (when both database path and SQL query are given) |
| date/time (`get_current_date`, `get_date`, `current_date`, `get_time`, `date` …) | `bash: date -u '+%Y-%m-%d %H:%M:%S UTC'` |
| deferred `grep` / `glob` (when absent from declared tools) | `bash: grep -rn -- \| head -n 50` / `find -name \| head -n 50` |
Mapping only fires when the client **does not** declare that exact name; a declared name always wins and
is left alone. `SAME_TOOL` resolves the same role across client versions (CLI `bash` vs desktop
`shell`, `task` vs `agent`), and `ARG_ALIASES` maps camelCase/generic keys to Claude Code's snake_case
parameters (`file_path`, `old_string`, `new_string`, `replace_all`, `run_in_background`, `skill`).
Unless `:web` or `:xsearch` is requested, `_to_chat_payload` explicitly sends `webEnabled: false`,
`webScrapeEnabled: false`, and `xSearchEnabled: false` so Venice does not inject automatic web-search
results into tool-calling turns.
## 4. Venice's own server tools → client tool, `VENICE_SERVER_TOOLS` (`venice_bridge.py`)
| Venice server tool | Routed to |
|---|---|
| view_media · get_attachment · hydrate_content | `read` (only when the id is a real file path) |
| web_search | `websearch` / `webfetch`; web_scrape · web_fetch → `webfetch` |
| calculator · code_interpreter · python | `bash` |
A call Venice **swallows** (runs itself) arrives with the name only, no arguments, so it cannot be
forwarded — it is asked for again by name, in the right format.
## 5. Argument-name aliasing — `ARG_ALIASES` / `_fit_arguments` (`venice_bridge.py`)
Before renaming, `_fit_arguments` unwraps envelopes the model adds around the real arguments: `{"arguments": {...}}`, `{"name": ..., "arguments": {...}}`, a JSON string in `arguments`, and `{"input": {...}}` / `{"parameters": {...}}`, up to three levels and only when the tool's own schema has no field of that name. Keys already present at the outer level win. A bare string reply (`{"content": "..."}`) goes into the tool's
one required string parameter when the tool has no `content` parameter of its own.
| Expected arg | Names the model may use |
|---|---|
| `filePath` / `path` | path, file, file_path, filename, file_name, target_file, dir, directory, folder, cwd, absolute_path |
| `command` | cmd, script, code, shell_command, input, expression |
| `oldString` / `newString` | old_string/old/old_text/search/find · new_string/new/new_text/replace |
| `content` | contents, text, file_text, data, body |
| `pattern` / `query` | query/regex/glob/q/search/name · q/search/pattern/text/prompt |
| `url` | link, uri, href, address |
| `prompt` | task, instructions, message, request, query |
| `agent` | subagent_type, agent_type, subagent, agent_name, role, mode |
| `limit` · `include` · `replaceAll` · `workdir` | max_results/max/count · glob/file_pattern/globs · replace_all/all/global · cwd/dir/working_directory |
Rule: only an argument the tool **expects but did not receive** is filled, and only from a name the tool
**does not know**.
## 6. Value fixes + expansions — `_coerce_arguments`, `_expand_call`
| Transform | What it does |
|---|---|
| command list → string | Codex `["bash","-lc","…"]` → one command |
| url extraction | pulls `https?://…` out of `prompt`/`query`/`text` |
| agent/description defaults | fills the sub-agent tool's required fields (default `general`) |
| questions normalize | reshapes to OpenCode's question-tool schema |
| MultiEdit / Cline SEARCH-REPLACE diff / read_many_files | one model call → **several** `edit`/`read` calls |
## 7. Deliberately NOT routed, and why
| Thing | Why |
|---|---|
| `patch` · `replace_in_file` · `apply_diff` | their diff/patchText can't be turned into `oldString`/`newString`, so the model gets a clean **"no such tool"** instead of a broken edit |
| a call Venice swallowed | only the name streams back, never the arguments → can't be forwarded |
| arguments not in the tool's schema | CC/OpenCode tools are `additionalProperties:false`, so extras are **dropped** (log `dropped args not in schema`, ) |
| a Venice media call whose id isn't a file | no file-read equivalent → not mapped (returns None, ) |
---
Verify against the code before relying on any row — the alias tables change as new clients appear. The
per-request `tool list: …` stderr line is the ground truth for what a given request actually sent.