> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/integrations/unsloth-start.md).

# Run Coding Agents with Local LLMs using Unsloth Start

Unsloth lets you connect [Claude Code](/docs/basics/claude-code.md), [Codex](/docs/basics/codex.md), Hermes, OpenCode, Pi, and other coding agents to a local model via the `unsloth start` command. The entire workflow can run offline on your own hardware. [Unsloth Studio](/docs/new/studio.md) automatically configures the endpoint, API key, provider, model, and context length for each launch, so you can use your preferred agent without modifying them. This guide will show you how to launch models from the command line for offline use, and connect to Unsloth Studio.

{% columns %}
{% column width="58.333333333333336%" %}

### Quickstart

First, make sure you have [Unsloth installed](/docs/new/studio/install.md). Then open Unsloth, load a model, go to your project folder, and run the command in terminal:

```bash
unsloth start claude
```

You can replace `claude` with any agent below:
{% endcolumn %}

{% column width="41.666666666666664%" %}

<figure><img src="/files/HrMdgp7HDGelphJEpwCG" alt=""><figcaption><p>Claude Code running with Qwen3.5 locally.</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

| Agent                                                              | Command                  |
| ------------------------------------------------------------------ | ------------------------ |
| <i class="fa-claude">:claude:</i> Claude Code                      | `unsloth start claude`   |
| <i class="fa-openai">:openai:</i> OpenAI Codex                     | `unsloth start codex`    |
| <i class="fa-caduceus">:caduceus:</i> Hermes Agent                 | `unsloth start hermes`   |
| <i class="fa-lobster">:lobster:</i> OpenClaw                       | `unsloth start openclaw` |
| <i class="fa-rectangle-vertical">:rectangle-vertical:</i> OpenCode | `unsloth start opencode` |
| <i class="fa-pi">:pi:</i> Pi Coding Agent                          | `unsloth start pi`       |

Unsloth uses temporary or session-scoped provider configuration. It does not add an Unsloth provider to the agent's normal configuration files.

{% hint style="info" %}
Codex currently requires a GGUF model served through the `llama-server` backend.
{% endhint %}

### Agent Guides

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Claude Code</td><td><a href="/files/SQea9SE3lYsQ81yTgdHa">/files/SQea9SE3lYsQ81yTgdHa</a></td><td><a href="/pages/w020xJgdCTBtTvfHtvye">/pages/w020xJgdCTBtTvfHtvye</a></td></tr><tr><td>Codex</td><td><a href="/files/lc9muACUvI9NGz5e4i31">/files/lc9muACUvI9NGz5e4i31</a></td><td><a href="/pages/PCjZ57h5pE0QccKyJMYD">/pages/PCjZ57h5pE0QccKyJMYD</a></td></tr><tr><td>Hermes Agent</td><td><a href="/files/JWfTGA1IyyNYAoRZgDH8">/files/JWfTGA1IyyNYAoRZgDH8</a></td><td><a href="/pages/q1ZbCTKGY7P8eXLeDdEN">/pages/q1ZbCTKGY7P8eXLeDdEN</a></td></tr><tr><td>OpenClaw</td><td><a href="/files/DB1O5gm73B7wigNpR3hn">/files/DB1O5gm73B7wigNpR3hn</a></td><td><a href="/pages/CwQEpEmkKPmyEYdnEngt">/pages/CwQEpEmkKPmyEYdnEngt</a></td></tr><tr><td>OpenCode</td><td><a href="/files/1CeptjdIcQaih70dC3iD">/files/1CeptjdIcQaih70dC3iD</a></td><td><a href="/pages/qaA8ZjTxsH2GTuBOHyra">/pages/qaA8ZjTxsH2GTuBOHyra</a></td></tr><tr><td>Unsloth API</td><td><a href="/files/kw2LlDbFk91VBhcoAc2g">/files/kw2LlDbFk91VBhcoAc2g</a></td><td><a href="/pages/7sCtc6YWnJBYthTjQsr7">/pages/7sCtc6YWnJBYthTjQsr7</a></td></tr></tbody></table>

### Load a model from the command line

<div align="center"><figure><img src="/files/WX0G6n7O1CvsZ6eVWVHL" alt="unsloth start launching Codex with a local GGUF model in Unsloth Studio" width="563"><figcaption><p>Unsloth start finds or loads the model, configures the coding agent and launches it from the current project.</p></figcaption></figure></div>

You can select and load a model while launching the agent:

{% tabs %}
{% tab title="With quant suffix" %}

```bash
unsloth start codex \
  --model unsloth/gemma-4-E2B-it-GGUF:UD-Q4_K_XL \
  --context-length 32768
```

The `:UD-Q4_K_XL` suffix selects the GGUF quant.
{% endtab %}

{% tab title="With `--gguf-variant`" %}

```bash
unsloth start codex \
  --model unsloth/gemma-4-E2B-it-GGUF \
  --gguf-variant UD-Q4_K_XL \
  --context-length 32768
```

An explicit `--gguf-variant` overrides the quant written after the model name.
{% endtab %}
{% endtabs %}

On the default local address, passing `--model` lets `unsloth start` start a temporary server when Unsloth Studio is not already running. The temporary server stops when the agent exits. If Unsloth is already running, the command connects to it and leaves it running.

See below for examples of agents being connected to a local LLM:

{% columns %}
{% column width="50%" %}

<div align="left"><figure><img src="/files/ECtwB96Ob4AiLBLpQ3Sq" alt=""><figcaption><p>OpenCode</p></figcaption></figure></div>
{% endcolumn %}

{% column width="50%" %}

<div align="left"><figure><img src="/files/gjh3Yo18OEOPBME5ip3M" alt=""><figcaption><p>Hermes</p></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% columns %}
{% column width="33.33333333333333%" %}

<figure><img src="/files/aDIEWsDR444JLL2lyzV9" alt=""><figcaption><p>Claude Code</p></figcaption></figure>
{% endcolumn %}

{% column width="33.33333333333333%" %}

<figure><img src="/files/X5tE4Q16valzHajyCMN7" alt=""><figcaption><p>Codex</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/2CK4jhHmnYiV6jUZZwvh" alt=""><figcaption><p>Openclaw</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

### Connect to a remote Unsloth server

Set the Unsloth URL and API key before launching an agent:

```bash
export UNSLOTH_STUDIO_URL=https://studio.example.com
export UNSLOTH_API_KEY=sk-unsloth-...
unsloth start claude
```

You can also pass the key with `--api-key`. For a verified local Unsloth server, `unsloth start` creates or reuses the API key automatically.

### Options

| Option                                       | What it does                                                          |
| -------------------------------------------- | --------------------------------------------------------------------- |
| `--model`, `-m`                              | Select a model. Without it, use the first model reported by Unsloth.  |
| `--api-key`                                  | Supply a Unsloth API key. You can also set `UNSLOTH_API_KEY`.         |
| `--launch` / `--no-launch`                   | Launch the agent or print the generated environment and command.      |
| `--serve` / `--no-serve`                     | Allow or prevent automatic local server startup.                      |
| `--gguf-variant`                             | Select a GGUF quantization variant.                                   |
| `--context-length`, `--max-seq-length`       | Set the requested context length when loading the model.              |
| `--load-in-4bit` / `--no-load-in-4bit`       | Control 4-bit loading for non-GGUF Hugging Face models.               |
| `--tensor-parallel` / `--no-tensor-parallel` | Enable or disable tensor-parallel GGUF loading for multi-GPU systems. |
| `--persist` / `--no-persist`                 | Keep the Unsloth-managed agent home where applicable.                 |
| `--yolo`                                     | Use the selected agent's non-prompting or trust mode.                 |
| `-h`, `--help`                               | Show command help.                                                    |

Load options are used when Unsloth needs to load or reconcile the requested model.

### Pass normal commands to the agent

Arguments that are not Unsloth options are passed to the selected agent:

```bash
unsloth start claude --continue
unsloth start codex --persist resume --last
unsloth start opencode run --continue "Continue the previous task"
unsloth start pi --persist --continue
```

Use the agent's own help command for its complete list of native options.

### Sessions and `--persist`

`--persist` keeps managed storage. It does not resume a conversation by itself; also pass the agent's normal resume command.

| Agent           | Do you need `--persist`?                                              | Resume example                                                   |
| --------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Claude Code     | No. Claude uses its normal session store.                             | `unsloth start claude --continue`                                |
| OpenAI Codex    | Yes. Its managed Codex home is temporary by default.                  | `unsloth start codex --persist resume --last`                    |
| OpenClaw        | Yes. Managed config, workspace and sessions are temporary by default. | Use `--persist` with the same native session ID.                 |
| OpenCode        | No. OpenCode uses its normal session store.                           | `unsloth start opencode run --continue "Continue"`               |
| Hermes Agent    | Yes. Its managed Hermes home is temporary by default.                 | `unsloth start hermes --persist --continue --oneshot "Continue"` |
| Pi Coding Agent | Yes. Its managed Pi home is temporary by default.                     | `unsloth start pi --persist --continue`                          |

For Codex, OpenClaw, Hermes and Pi, use `--persist` from the first launch and again when returning to the session.

{% tabs %}
{% tab title="Codex" %}

```bash
unsloth start codex --persist
unsloth start codex --persist resume --last
```

{% endtab %}

{% tab title="OpenClaw" %}
Use a stable session ID for a named session:

```bash
unsloth start openclaw --persist \
  agent --local --session-id my-session --message "Inspect this repository"

unsloth start openclaw --persist \
  agent --local --session-id my-session --message "Continue"
```

{% endtab %}

{% tab title="Hermes Agent" %}

```bash
unsloth start hermes --persist --oneshot "Inspect this repository"
unsloth start hermes --persist --continue --oneshot "Continue"
```

{% endtab %}

{% tab title="Pi Coding Agent" %}

```bash
unsloth start pi --persist --print "Inspect this repository"
unsloth start pi --persist --continue --print "Continue"
```

{% endtab %}
{% endtabs %}

#### Print the launch command without running it

```bash
unsloth start claude --no-launch
```

This prints the generated environment and command. The output can contain connection credentials, so do not publish it in logs or screenshots.

### Permission-bypass mode

`--yolo` maps to the selected agent's trust or non-prompting mode. It can reduce approval prompts and allow the agent to run commands without asking first.

{% hint style="warning" %}
Only use it in an environment where unrestricted agent actions are acceptable.
{% endhint %}

#### Common issues

<details>

<summary>No Unsloth server was found</summary>

Start Unsloth and load a model, or pass \`--model\` so Unsloth can start a temporary local server.

</details>

<details>

<summary>Codex does not connect</summary>

Use a GGUF model running through \`llama-server\`. The current Codex integration does not use the Unsloth transformers backend.

</details>

<details>

<summary>A session was not restored</summary>

For Codex, OpenClaw, Hermes and Pi, use \`--persist\` on the first and later launches, then pass the agent's native resume option.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unsloth.ai/docs/integrations/unsloth-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.