Run translations locally with LM Studio

Most words you click in Lector never touch the network. They resolve straight from an on-device dictionary. But that dictionary is small, so plenty of lookups still fall through to a cloud LLM, and in a thinly-resourced language like Afrikaans, plenty is an understatement. Each one sends a slice of what you're reading to someone else's server, and adds to a per-token bill.

Lector's click-to-translate, phrase translation, journal correction, and LLM tutor all run through one pluggable translation agent, and LM Studio is one of the providers you can point it at: a desktop app that downloads open models and serves them over an OpenAI-compatible API. This guide wires that agent up to a model on your own hardware, so the lookups that would have gone to the cloud are answered locally instead — no API key, no cloud round-trip, no per-token bill.

Why an OpenAI-compatible local server

Lector doesn't hard-code a translation API. It selects a provider and calls it through a small interface (complete() for translations and explanations). For local models, that interface is satisfied by anything that implements the OpenAI shape:

• POST /v1/chat/completions — the actual translation/definition call
• GET /v1/models — so Lector can list the models you have available
• an optional Authorization: Bearer <key> header for protected servers

LM Studio exposes exactly these endpoints. That means your reading history, vocabulary, and the text you're translating never leave your hardware, and you can swap the underlying model whenever you like without touching Lector.

What you'll need

• A running Lector instance. See the installation guide if you don't have one yet.
• A machine to run LM Studio on (macOS on Apple Silicon, Windows, or Linux). This can be the same machine as Lector or a different one on your network.
• Enough memory for your chosen model. A 7-8B model quantised to 4-bit needs roughly 5-6 GB of RAM or VRAM.

Step 1 · Install LM Studio and download a model

1. Download LM Studio from lmstudio.ai and install it.
2. Open the Discover (search) tab and download an instruction-tuned model. Good starting points are a compact model like Google's Gemma (the efficient E4B variant runs comfortably on a laptop), Llama 3.1 8B Instruct, or Qwen2.5 7B Instruct. Pick a 4-bit (Q4) quant to keep memory use modest.
3. Wait for the download to finish. You don't need to chat with it in the LM Studio UI; we only need the server.

Step 2 · Start LM Studio's local server

LM Studio runs the OpenAI-compatible API on port 1234 by default.

From the app

Open the Developer tab (called the Local Server tab in older versions) and start the server. It will begin listening on http://localhost:1234.

Or from the CLI

LM Studio ships a headless CLI, which is handy if the app runs on a server:

# Start the OpenAI-compatible server on :1234
lms server start

# (optional) load a model so the first request isn't slow
lms load <model-name>

Verify it's up

From the same machine, confirm the API answers and reports your models:

curl http://localhost:1234/v1/models

You should get back a JSON list with at least one model id. That's what you'll select in Lector.

Step 3 · Point Lector at LM Studio

In Lector, open Settings → AI Provider, set the provider to Local / self-hosted (OpenAI-compatible), and choose the LM Studio preset (it autofills the endpoint to localhost:1234). Then:

Endpoint

The base URL of your LM Studio server, without the /v1 suffix. Lector adds that itself.

• LM Studio on the same OS as Lector: http://localhost:1234
• LM Studio on a different machine: use that machine's address, e.g. http://192.168.1.50:1234
• Lector in Docker: see the Docker section. localhost will not work here.

API Key (optional)

Leave this empty for a normal local setup. You only need it if your LM Studio is behind a reverse proxy or you're using LM Studio Cloud. When set, Lector sends it as a Bearer token from the server side, never exposed to the browser after you save it.

Model

Click Fetch models. Lector queries /v1/models and populates the dropdown with what LM Studio has available; pick the one you downloaded. If the fetch fails (e.g. the server isn't reachable yet), you can type the model id in manually.

That's it. Open a book or article, click a word, and the lookup is answered by your local model. The first request after the server starts can be slow while LM Studio loads the model into memory; enable just-in-time / auto-load, or run lms load (from step 2) to pre-load it. If LM Studio is ever unreachable, Lector quietly falls back to its built-in dictionary of the most common words, so reading never breaks.

Running Lector in Docker

This is the part that trips people up, so it gets its own section. Lector's translation call happens server-side, inside the container. So when you type http://localhost:1234, "localhost" means the container itself, not your host machine where LM Studio is running. The container has no LM Studio, so the connection is refused.

There are two things to get right:

1. Make LM Studio reachable off-localhost

As noted above, enable "Serve on Local Network" in LM Studio so it binds to 0.0.0.0:1234 instead of 127.0.0.1:1234. A container can't reach a host's loopback-only service.

2. Use a host-reachable address in the Endpoint

On Linux, host.docker.internal isn't defined by default. Add it to your compose service:

services:
  lector:
    image: ghcr.io/heuwels/lector:latest
    container_name: lector
    restart: unless-stopped
    ports:
      - "3400:3000"
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=production
    # Lets the container resolve host.docker.internal on Linux
    extra_hosts:
      - "host.docker.internal:host-gateway"

Then set the Endpoint to http://host.docker.internal:1234 in Lector's settings.

Configuring it without the UI

If you'd rather not click through settings (handy for reproducible deployments), you can configure the provider entirely with environment variables. The settings you save in the UI take precedence; these env vars are the fallback when a setting isn't set.

A complete Docker Compose example, pointing at LM Studio running on the Docker host:

services:
  lector:
    image: ghcr.io/heuwels/lector:latest
    container_name: lector
    restart: unless-stopped
    ports:
      - "3400:3000"
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      - LLM_PROVIDER=lmstudio
      - LMSTUDIO_URL=http://host.docker.internal:1234
      - LMSTUDIO_MODEL=google/gemma-4-e4b
    extra_hosts:
      - "host.docker.internal:host-gateway"

Troubleshooting

You're not locked in

Because Lector speaks the OpenAI-compatible API, LM Studio is one option among several behind the same provider: Ollama, vLLM, or a remote OpenAI-compatible endpoint all use the same endpoint / model / optional-key flow (Ollama and LM Studio even get presets that autofill the endpoint). The other provider is Anthropic (Claude), for when you want cloud quality. Start local with LM Studio, switch to Claude for a tricky language, switch back — your books and progress don't care which agent is doing the translating.

← Back to the blog