# 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

Saving the connection also created an agent named after it: `claude@lm-studio`. Open a new shard and type it:

```bash
claude@lm-studio
```

Claude Code starts and runs on LM Studio. Plain `claude` in the same shard still runs hosted Claude, so you can move one task across without moving all of them.

If Claude Code asks whether to use the supplied API key, choose **Yes**.

Set the model each size runs so LM Studio receives the id it actually serves:

```bash
crystl endpoint set --label lm-studio --standard openai/gpt-oss-20b
```

Then `claude@lm-studio --size standard` runs that model.

To start a background worker instead of typing into a shard:

```bash
crystl shard create --gem myapp --agent claude@lm-studio --size standard \
  --prompt "inspect this project and suggest the best first task"
```

`crystl shard create` is a Guild control command. Typing `claude@lm-studio` into a shard is not.

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/