# Use LM Studio open models with crystl

> Install LM Studio, download and serve a model, connect it to crystl, and start a Claude Code shard.

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](https://lmstudio.ai/download), 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:

```bash
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:

```bash
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

```bash
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.

## Other setup tutorials

- [Ollama](/docs/open-models-ollama/): a lighter command-line runtime.
- [vLLM](/docs/open-models-vllm/): high-throughput serving on a Linux GPU machine.
- [llama.cpp](/docs/open-models-llama-cpp/): a small native server with direct control over quantization.
- [z.ai](/docs/open-models-zai/): hosted GLM models, no local GPU.

## Related

- [Open Models](/docs/open-models/) for agent behavior, orchestration, and model-size profiles.
- [LM Studio's Claude Code guide](https://lmstudio.ai/docs/integrations/claude-code) for the underlying compatibility layer.

---
Source: https://crystl.dev/docs/open-models-lm-studio/