Organisation gears
Define the gears every venom CLI user in your organisation sees, pick a model and route for each role, set the default gear and lock members to your gears.
A gear is a preset the venom CLI switches to in one keystroke: a model for the main agent and, optionally, a model for each kind of side work. On the console's /gears page an admin defines gears for the whole organisation. Every venom CLI pointed at Venom Cloud with one of the organisation's keys reads them from GET /v1/gears along with the model list, and shows them next to its built-in gears (see Gears and route profiles for how the CLI merges them).
Make a gear
- Open
/gearsand pick a template, or New gear. - Name it (
team, for example) and give it a key from 1 to 9 so CLI users can press it. - Pick the main model from the list. Each entry shows whether one of your daemons or provider keys serves it now, and its price per 1M tokens.
- Optionally pick models for the other roles, a route for each, and a thinking level.
- Press Check to see which daemon or provider each role would hit right now. Nothing is sent and nothing is billed.
A new gear waits in the bar at the bottom of the page until it has a name: press Create gear there. After that, edits save on their own: a typed change about a second after you stop typing, a pick from a list, a toggle or a removal at once. The bar says how the last save went.
In a terminal, the gear appears in /gear, labelled with your organisation's name:
export VENOM_BASE_URL=https://cloud.usevenom.dev/v1
export VENOM_API_KEY=vck_…
venom gear listTemplates
| Template | What it sets up |
|---|---|
| Cloud only | Every role on your provider keys, never a daemon. |
| Own daemons, cloud for vision/browser | Your daemons for the work, a cloud vision model for images and the browser. |
| Daemons only | Every role on your own daemons, never a cloud provider. |
| Auto (by difficulty) | venom-auto for every role: the cloud picks a cheap, balanced or premium model per request, by the model choice rules on the Routing page. |
A template fills in models your organisation serves now where it can, else the usual names, which then show a warning.
Fields
| Field | Type | Rule |
|---|---|---|
| Name | text | 1 to 64 characters of a-z 0-9 . _ -, unique |
| Key | 1 to 9, or none | Unique. Gears with a key come first, in key order, then the rest by name |
| Description | text | At most 200 characters |
| Model | one model id, or a list of up to 8 | The first one served wins. Letters, digits and . _ : / @ + -, an optional trailing * |
| Route | cloud, cloud-first, daemons, daemons-first or none |
Sent as x-venom-profile; narrows your routing for that role, never widens it |
| Thinking | off, minimal, low, medium, high, xhigh |
Optional |
| Service tier | auto, default, flex, priority, batch |
Optional; never inherited from the main row |
Roles, in the order the editor shows them: main, workers, smart, vision, browser, classifier, summary, reflex. Each role has the same model, route, thinking and service tier fields. What runs on each role is in Gears and route profiles.
| Route | Meaning |
|---|---|
cloud |
Only provider keys. |
cloud-first |
Provider keys first, then daemons. |
daemons |
Only your own daemons. |
daemons-first |
Daemons first, then provider keys. |
An organisation may have at most 32 gears.
Default gear and lock
- Default gear (the card above the editor): the gear new sessions start in when the user's own config names no
gear:. - Members can only use these gears: CLI users see only the organisation's gears. Their own config's gears are ignored with one notice, and
/gear save,editandrmrefuse.
When a gear experiment is running (the Experiments button), a notice names it, and its two gears can't be removed until it ends.
Where a gear is chosen
Besides the CLI and its default gear, a gear is picked for what the cloud runs itself: a quick chat and a bot
(Quick chat), People's AI, People signals and classification (People → Settings), and the
failure classifier (Failures). Each of these lists every gear of your organisation, then venom's built-ins (eco, qwen,
china, …) unless Members can only use these gears is on. A gear runs on the first model it names that your provider
keys or live daemons serve (a wildcard on the first served match). One that cannot run now stays on the list, greyed out,
with the reason: no provider key for its model (and which provider), its daemon is offline, its wildcard matches nothing, or
your organisation uses only its own daemons. The run uses the same list, so it runs on the model the picker shows.
The Slack bot, gear experiments, shadow tests and evals still offer only your organisation's gears: experiments, shadow tests and evals compare or change those gears, and the Slack bot's picker moves to the shared list later.
Who can do what
| Action | Permission | Roles |
|---|---|---|
See /gears, run Check |
routing:read |
owner, admin, developer, viewer |
| Change gears, the default and the lock | org:manage |
owner, admin |
A platform operator picks the organisation in the org switcher first.
Troubleshooting
| Message | Cause and fix |
|---|---|
"x" is not served by any of your daemons or provider keys right now |
A warning, not an error: the gear saves. A daemon may be offline; otherwise connect a provider key that lists the model or fix the id. |
name must be 1-64 characters of a-z 0-9 . _ -. |
Rename the gear. |
key N is already gear "x"'s. |
Two gears share a key. Free it on the other gear first. |
at most 8 models. |
Shorten the model list. |
| Your role cannot change gears (org:manage). | Ask an owner or admin. |
| Name a model first. | Check needs a model on the role. |
| CLI users don't see a change | The CLI caches the gear list with the model list. Restarting venom reads it again. |
Related
- Gears and route profiles: gears in the CLI and in
venom.yaml. - Routing: model choice for
venom-auto, and where each model runs. - Providers and provider keys: the models your keys serve.
- Budgets: a spend limit per gear.