Use LM Studio open models with crystl

This tutorial takes you from a new LM Studio installation to Claude Code running against a model on your own hardware. LM Studio provides an Anthropic-compatible API, so Claude Code can connect directly without a translation proxy.

1. Install LM Studio

Download and install LM Studio, then open it once. Its lms command ships with the app; run lms --help in a terminal to confirm that the CLI is available.

The desktop app is the easiest route. LM Studio also offers a headless daemon for a Linux model server.

2. Download and load a model

In LM Studio, open Discover, choose a tool-capable coding model that fits your memory, and download it. This example uses openai/gpt-oss-20b, which LM Studio says can run within 16 GB of memory:

lms get openai/gpt-oss-20b
lms load openai/gpt-oss-20b --context-length 32768

Claude Code consumes a large standing prompt. LM Studio recommends more than roughly 25K context for coding agents; more context also uses more memory.

3. Start the local server

Open LM Studio’s Developer tab and turn on Start server, or run:

lms server start --port 1234
curl http://localhost:1234/v1/models

The response should list openai/gpt-oss-20b. LM Studio can load models just in time, but explicitly loading one makes the first test easier to understand.

4. Add LM Studio to crystl

Open Settings → agents → providers & keys, scroll to the open-model connections, and add:

Field	Value
Label	`lm-studio`
Kind	anthropic-compatible
Base URL	`http://localhost:1234`
As seen from remote	leave empty
Key	leave empty unless LM Studio authentication is enabled
Context window	the context length set for the loaded model
Enabled	on

Do not add /v1 to the Anthropic-compatible base URL. Claude Code appends /v1/messages itself.

The context window field is optional, and it is worth filling in. crystl uses it to warn you when an endpoint is too small for the work you are about to start, which is the most common cause of an agent producing broken tool calls or stopping partway. Record the context length your server is actually configured for.

If you enabled Require Authentication in LM Studio, create an API token in the Developer page and paste it into the connection’s Key field. crystl stores it in your macOS Keychain.

5. Start Claude Code

crystl shard create --gem myapp --agent claude --local lm-studio \
  --model openai/gpt-oss-20b \
  --prompt "inspect this project and suggest the best first task"

crystl shard create is a Guild control command. You can create the same shard from the desktop app without Guild.

If Claude Code asks whether to use the supplied API key, choose Yes. The model name in the command ensures LM Studio receives the id it actually serves.

Inside the shard, echo $ANTHROPIC_BASE_URL should print http://localhost:1234. Give the agent a small task that reads a file and uses a tool to verify the complete path.

Run LM Studio on another machine

LM Studio’s server settings can enable Serve on Local Network. Use the model machine’s private LAN or Tailscale address in crystl, and keep authentication on when other devices can reach the server. If the agent runs on that same machine over SSH, set As seen from remote to http://localhost:1234.

Troubleshooting

lms is not found: open LM Studio once, then retry. The app installs the CLI integration.

Claude Code says model not found: run curl http://localhost:1234/v1/models and pass the exact returned id with --model.

The server rejects the key: either turn off Require Authentication for a private local-only server or copy a current LM Studio API token into the crystl connection.

Tool use is unreliable: choose a model marked for native tool use in LM Studio and give it at least the context LM Studio recommends for coding tools.