Running Athos Locally with Ollama

Athos normally talks to a hosted AI provider. It can instead talk to Ollama, an application that runs language models on hardware you control.

Choose Ollama when:

• Prompts must not leave your network. Questions, project data, and query results stay on your own machines.
• You work offline — in the field, on an air-gapped network, or somewhere with poor connectivity.
• You would rather not pay per request. The cost is the hardware instead.

The trade-off is quality and speed: a model small enough to run locally is less capable than a hosted frontier model, and answers arrive more slowly. Some Athos features are also unavailable (see What works and what doesn't).

Where to run it

Ollama exposes a network service, so it does not have to run on the same computer as VRGS.

On a separate machine (recommended)

This is the arrangement we recommend. One reasonably-specified machine on your network runs Ollama and serves every VRGS workstation. It keeps the language model off the GPU that VRGS is already using, so 3D rendering and the AI segmentation tools are unaffected, and one machine's hardware benefits the whole team.

A dedicated box, a spare workstation, or an on-premises server all work.

On the same machine as VRGS

Supported, and genuinely useful — for a single user, a laptop in the field, or anywhere a second machine isn't practical. The constraint is the graphics card.

VRGS already asks a lot of your GPU: it renders the 3D scene, and the AI tools (Segment Anything, fracture detection) load their own models onto the same card. A language model running beside all of that competes for the same memory. On a card with too little to go around, you will see slower rendering, slower segmentation, or the model falling back to the CPU — which is dramatically slower.

This is why model size matters more than anything else when running locally. See Choosing a model.

Install Ollama

1. Download and install Ollama for your platform from ollama.com/download.

2. Use version 0.12.7 or later — the recommended model needs it.

3. Download the model. In a terminal on the machine running Ollama:

   ollama pull qwen3-vl:8b

   The download is around 6 GB and only happens once.

4. Check it responds:

   ollama run qwen3-vl:8b "Reply with OK"

Choosing a model

VRGS defaults to qwen3-vl:8b. It is a good balance for this application: small enough to share a graphics card with VRGS, with a large context window so long conversations survive intact.

Pick by the memory on your graphics card, and remember VRGS needs its own share:

Graphics card memory	Model	Download	Notes
8–12 GB	qwen3-vl:4b	3.3 GB	Step down when sharing a card with VRGS
16 GB or more	qwen3-vl:8b	6.1 GB	Default. The recommended choice
Separate machine, 24 GB+	qwen3-vl:32b	21 GB	Noticeably better answers — but only on a machine not running VRGS

Don't run the largest models beside VRGS

The 30B and 32B models need 20–21 GB before VRGS has asked for anything. On a shared card they will starve the renderer and the segmentation tools. Use them only on a separate machine.

The download size is not the whole story — memory use grows as a conversation gets longer, so leave headroom rather than filling the card exactly.

To use a different model, pull it with ollama pull <name> and set it in the Athos settings. Any model Ollama can run will work, but models without tool support answer general questions only and cannot query your project database.

Point VRGS at the server

VRGS looks for Ollama at http://localhost:11434 — the standard address on the same machine. If that is your setup, there is nothing to configure: start Ollama, open Athos, and type /switch ollama.

For a separate machine, set an environment variable on each VRGS workstation:

Variable	Value
VRGS_OLLAMA_SERVER	http://<server-name-or-ip>:11434

For example, http://ollama-box.local:11434 or http://192.168.1.50:11434. Set it as a system environment variable so it applies to VRGS however it is launched, then restart VRGS.

Let the server accept connections

By default Ollama only accepts connections from its own machine — a remote VRGS will fail to connect until you change this. On the Ollama machine, set:

Variable	Value
OLLAMA_HOST	0.0.0.0

Then restart Ollama and allow port 11434 through that machine's firewall.

Ollama has no password

Ollama does not authenticate connections. Anyone who can reach port 11434 can use the model and see what is asked of it. Only expose it on a trusted internal network — never forward it to the internet.

What works and what doesn't

Everything Athos does runs through the same slash commands regardless of provider, but a local model is more limited:

Capability	Local Ollama
Answering how-to questions from the built-in documentation	Yes
Geoscience questions from your literature library	Yes
Querying your project database in plain English	Yes
Moving the camera / describing what is displayed	Yes
Looking at a screenshot of the 3D view	No — see below

Athos does not currently send images to Ollama, so questions that depend on how something looks are answered from the scene description alone. The recommended model is capable of reading images, so this may change in a future release. For visual questions today, switch to a hosted provider with /switch openai or /switch claude.

Answers will also be shorter and less reliable than a hosted frontier model's, particularly on multi-step questions. That is the cost of running locally.

Troubleshooting

Symptom	Cause and fix
Athos reports it cannot reach the AI provider	Ollama isn't running, or VRGS_OLLAMA_SERVER points at the wrong address. Open http://<server>:11434 in a browser — you should see "Ollama is running".
Works locally, fails from another machine	OLLAMA_HOST is not set to 0.0.0.0 on the server, or port 11434 is blocked by its firewall.
Very slow replies, high CPU, idle GPU	The model didn't fit in graphics memory and fell back to the CPU. Use a smaller model, or close other GPU-heavy work.
Replies fine, then VRGS renders slowly	The model and VRGS are competing for the same card. Step down a model size, or move Ollama to a separate machine.
"model not found"	The model hasn't been pulled on the server. Run ollama pull qwen3-vl:8b there.
Environment variable seems ignored	Set it as a system variable, not for one terminal session, and restart VRGS afterwards.

Related

• Using the Athos AI Assistant — what Athos can do and how to talk to it
• AI & Machine Learning Requirements — how Athos differs from the GPU-based AI tools
• Graphics Settings — making sure VRGS uses the right graphics card