Skip to content
Docs menu

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.

View .md

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

  1. Open /gears and pick a template, or New gear.
  2. Name it (team, for example) and give it a key from 1 to 9 so CLI users can press it.
  3. 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.
  4. Optionally pick models for the other roles, a route for each, and a thinking level.
  5. 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 list

Templates

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, edit and rm refuse.

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.