Skip to main content

Models & providers

Vision (Image Understanding)

Bodega can look at images - screenshots, diagrams, UI mockups, error dialogs - using a vision-capable model. You do not have to switch your main model to do it.

How vision works

Keep your text model as the default. When you attach an image and your active model can't read images, Bodega routes just that question to a vision model and brings the answer back - your text model stays in place.

Three paths, depending on your setup:

  • A vision-capable cloud model - reads the image directly. No swap, nothing to install.
  • Ollama - uses an Ollama vision model directly; no process swap.
  • llama.cpp - briefly hot-swaps to your downloaded vision model, answers, then restores your text model (see below).

Attach an image

  1. Drag an image file onto the chat window, or click + → Take a screenshot to capture one, or paste an image with Ctrl+V.
  2. Ask your question about it.
  3. The answer streams back in the conversation.

Works in both Chat and Code mode. In Code mode the Agent panel has its own camera button.

Local vision: the auto-swap (llama.cpp)

On llama.cpp, Bodega owns one model process, so seeing an image means temporarily loading the vision model. You'll see a brief "switching to the vision model" indicator with progress - the first load takes ~10–60s while weights load; subsequent queries are fast. After the answer, your text model is loaded back automatically.

Choose how vision is handled in Settings → Models → Vision - prefer the no-swap engine (Ollama) when one is available, or allow the llama.cpp swap.

Get a vision model

Download a VLM from Models → Discover:

  • Qwen2.5-VL - strong general-purpose vision
  • LLaVA - widely supported
  • Moondream - tiny, fast, low-VRAM

Ollama also has its own vision models. Once a VLM is installed the routing above picks it up automatically - you do not have to assign it to a panel role.

If you have several installed and want a specific one, pin it at Settings → Models → Vision → Vision companion (vision.default_companion). The picker lists each installed candidate with its engine and rough VRAM cost. Leave it on Automatic and Bodega picks the smallest model that fits. The resolution order is: a per-session pick → this pinned default (if still installed) → a cached pairing → smallest-first.

Vision in the agent loop

The agent can use vision as a tool, not just in chat:

  • vision_query takes an image and a question and sends both to your bound vision model - this is how a text-only model driving the loop can "see."
  • preview_interaction can screenshot the live Preview tab or the agent browser; the agent then runs vision_query on that screenshot to read what rendered. That's how it can check a UI it just built, or read a page it navigated to.

Screenshots the agent takes stay in the transcript after the turn ends, in both modes, so you can see what it actually looked at.

Air-gap

In air-gap mode only local vision models are used - cloud vision is blocked along with all other cloud traffic.

Vault-aware end to end. The network dispatch of an image (VisionRouter.routeVisionCall) checks the effective air-gap - global OR the project's Air-Gap Vault - so a vaulted project's chat-attached image cannot reach a non-local vision model (fixed 2026-08-10). The earlier step that decides which local vision model to bind is vault-aware too: BoundVisionService passes the project vault into each engine adapter's isOperational() probe, so a vaulted project with global air-gap off never probes a non-local Ollama URL either (fixed 2026-08-23; before that the probe read only the global flag).

Tips

The first llama.cpp vision answer is slow; the rest are not. Loading the VLM weights is a cold load - the backend estimates roughly 10–60 seconds depending on model size and disk speed, not a measured figure for your specific hardware. Subsequent vision questions in the same stretch are fast. If you have several images to ask about, ask about them together rather than spreading them across a session - each gap risks paying the swap again.

You can refuse the swap entirely. Turn off allow llama.cpp swap (vision.allow_llamacpp_swap) at Settings → Models → Vision and your text model is never paused. Vision questions then route to Ollama if it has a vision model, or are declined outright - declined, not silently answered by a model that cannot see. That is the right setting if a pause mid-task is worse to you than no answer.

Automatic prefers Ollama for a reason. With vision.engine_preference on auto and both engines holding a vision model, Ollama wins - it swaps internally with no pause, while llama.cpp has to stop your text model. Pinning llama.cpp is a deliberate trade, not an optimisation.

Attaching an image is not free context. Images are base64-encoded into the request. Watch the context budget meter - a couple of full-resolution screenshots will fill a small window quickly.

This page mirrors the in-app docs hub for app version 1.0.0-beta.41. Found something unclear or out of date? Tell us on Discord. New here? Download the free beta and follow along.