Unsloth Desktop puts local model downloads, chat, training and agent connections into one app. The sensible way to try it is not to begin with the biggest model on the page. Install the official build, keep it local, load a small GGUF model and prove the basic chat works. Then—and only then—connect tools such as Claude Code or Codex.
Scope note: I checked this guide against Unsloth’s official website, repository and the current v0.1.701-beta release on 13 August 2026. I have not installed this release on all three operating systems, so this is a documentation-verified guide to the official installers and setup flow—not a claim that I personally benchmarked every platform.
The quick answer
- Open the official Unsloth Desktop download page or the GitHub Releases page.
- Download the Windows
.exe, macOS.dmg, or the appropriate Linux package. - Install and open Unsloth Desktop.
- In the model hub, choose a small instruction-tuned GGUF model and a lower-memory quantization for your first test.
- Load it, start a new chat and confirm that a simple prompt works.
- Leave remote access and code-execution tools alone until the basic local setup is reliable.
If you only want a local OpenAI-style server on Windows and prefer Docker, my LocalAI Windows guide is the more server-first route. Unsloth Desktop is the more ambitious all-in-one option.
What is Unsloth Desktop?
Unsloth Desktop is Unsloth’s new free, open-source desktop application for running and training supported AI models locally. It is available for Windows, macOS and Linux. The app combines model discovery, downloads, chat, training workflows, exports and connections to external agents in one interface.
There are three similarly named things, which is an easy source of confusion:
- Unsloth Desktop is the packaged desktop app and the easiest place to start.
- Unsloth Studio is the local web interface launched from the command line.
- Unsloth Core is the Python-based framework for people who want to work in code and notebooks.
This article focuses on Desktop. You do not need to begin by building a Python environment or cloning the repository.
As of publication, v0.1.701-beta is the latest GitHub release. The word beta matters. I would expect fast changes, occasional rough edges and frequent updates rather than treating this as a sleepy, finished desktop utility.
Before you install: pick a realistic first goal
Unsloth supports a wide range of hardware, including CPU-only systems and NVIDIA, AMD, Intel and Apple Silicon hardware. That does not mean every model will run well on every computer, or that every training backend works on every device.
There is no honest universal RAM or VRAM number I can give you here. Model size, quantization, context length, backend and workload all change the requirement. My first-run rule is deliberately boring:
- Choose an instruction-tuned model, not a base model.
- Start with a small parameter count.
- If GGUF quantizations are offered, start with a 4-bit option rather than a full-precision file.
- Check the displayed download size before committing.
- Prove chat works before attempting training, agents, image generation or remote access.
A smaller model is not the final destination; it is a diagnostic tool. If it loads and responds, you know the app, backend and basic model path are working. You can move up one step at a time without guessing which part broke.
Step 1: Download the official installer
Use only the official download page or the project’s GitHub Releases page. Avoid mirrors, repackaged installers and download sites that insert their own launcher.
The current release assets include:
- Windows: a
.exeinstaller for Windows 10 and 11. - macOS: a
.dmgpackage for Apple Silicon in the current release. Unsloth’s main product page mentions Intel Macs, but the v0.1.701-beta release workflow does not provide a current Intel build. I would not promise Intel compatibility until a matching asset returns. - Ubuntu/Debian Linux: a
.debpackage. - Other Linux choices: the current GitHub release also lists an experimental x86-64 AppImage. There is no verified Linux Arm64 Desktop package in this release.
At the time I checked, the current release was v0.1.701-beta. Because the project is moving quickly, use the release marked Latest rather than relying on a versioned link copied from an older tutorial.
Step 2: Install Unsloth Desktop
Windows 10 or 11
- Download the Windows
.exefrom the official release. - Open the installer from your Downloads folder.
- Check that the file came from the official
unslothai/unslothGitHub release before approving any Windows security prompt. - Complete the installer and launch Unsloth Desktop from the new shortcut or Start menu entry.
If SmartScreen flags a newly released build, do not reflexively disable Windows security. Re-check the download URL and the release page first. A tutorial should not train you to click through warnings on autopilot.
macOS on Apple Silicon
- Download the current
.dmgfrom the official release. - Open the disk image and move Unsloth Desktop into Applications if the installer asks you to.
- Launch it from Applications.
- If macOS blocks the first launch, verify the official source before using the app-specific option in System Settings → Privacy & Security. Do not turn Gatekeeper off globally.
Ubuntu or Debian Linux
- Download the current Linux
.debfile. - Open it with your distribution’s software installer, or install the downloaded file from a terminal.
cd ~/Downloads
sudo apt install ./filename.debThe filename changes with each release, so adjust the command to match the file you actually downloaded. If your distribution is not Debian-based, use the AppImage or another package listed in the latest official release rather than forcing a .deb into an incompatible system.
Step 3: Load your first local model
- Open Unsloth Desktop.
- Open the built-in model hub or model search.
- Choose a small instruction or chat model with a GGUF download.
- Select a lower-memory quantization for the first run. A 4-bit build is a practical starting point when one is available.
- Check the download size and make sure you have enough free disk space.
- Download and load the model.
- Start a new chat and ask:
Reply with one sentence confirming the local model is responding.
Do not judge the whole product from one tiny model’s intelligence. This test answers a narrower and more useful question: can your computer load a local model and return a response through Unsloth?
If it works, move up gradually. If it fails, step down in model size or quantization before changing ten advanced settings at once.
Step 4: Connect Claude Code or Codex
Unsloth’s current official integration guide documents one-command launchers for both Claude Code and OpenAI Codex. First load a model in Unsloth. Then open a terminal in the project folder you actually want the agent to use.
For Claude Code:
unsloth start claudeFor Codex:
unsloth start codexCodex limitation: Unsloth’s current documentation says Codex requires a GGUF model served through its llama-server backend. If Codex will not connect, confirm that the model and backend meet that requirement before changing unrelated settings.
Those are the exact commands currently published by Unsloth. They assume the target agent is installed and available on your computer. Run them from a small test project first—not your home folder, documents library or an important production repository.
I would keep approval prompts and workspace restrictions enabled. Do not add a “bypass approvals” flag just because an example on the internet promises a smoother demo. A local model can still delete or change local files if the agent gives it that authority.
If you prefer to assemble the pieces yourself, my llama.cpp and MCP setup guide explains a lower-level local-agent approach. For a visual workflow rather than a coding agent, see the ComfyUI MCP guide.
Using the OpenAI-compatible API
Unsloth can serve a loaded local model through OpenAI- and Anthropic-compatible endpoints. Its current repository lists support for /v1/chat/completions, /v1/responses and /v1/messages.
Open the API section in Unsloth and copy the base URL, model name and API key it displays. Do not guess them from an old screenshot: ports and generated credentials can differ. A simple OpenAI Python client pattern looks like this:
from openai import OpenAI
client = OpenAI(
base_url="PASTE_THE_UNSLOTH_BASE_URL_HERE",
api_key="PASTE_THE_UNSLOTH_API_KEY_HERE",
)
model_name = next(iter(client.models.list())).id
response = client.chat.completions.create(
model=model_name,
messages=[
{"role": "user", "content": "Reply with: local API works"}
],
)
print(response.choices[0].message.content)Install the client library with pip install openai if it is not already present. Keep the server on localhost while testing. An API-compatible endpoint is convenient, but compatibility does not guarantee that every model supports every tool, response field or advanced feature equally well.
A safety check before enabling tools or remote access
“Local” describes where the model runs; it is not a magic safety label. Unsloth advertises sandboxed Python and Bash execution, while its repository also warns that server-side tools can run as your user and that anyone with a remotely exposed API key may be able to run code on the machine.
- Use a disposable test folder with no secrets or irreplaceable files.
- Keep agent approvals and filesystem restrictions on.
- Do not put API keys in screenshots, public repositories or copied terminal logs.
- Keep Unsloth bound to localhost until you genuinely need access from another device.
- If you expose the command-line Studio server, Unsloth recommends
--securefor a Cloudflare HTTPS tunnel rather than opening a raw port. - When remote access is enabled, consider launching with
--disable-toolsso a remote client cannot trigger Python, terminal or web-search tools.
The CLI form documented by Unsloth is:
unsloth studio --secure -p 8888 --disable-toolsEven then, use a strong password and protect the API key. A Cloudflare link is reachable from the internet; HTTPS does not make an exposed credential harmless.
Troubleshooting Unsloth Desktop
The download page and app show different versions
Open GitHub Releases and use the release marked Latest. The project is changing quickly, so old direct installer links age badly. Desktop update controls are also available under Settings → General in current releases.
A model downloads but will not load
- Try a smaller model.
- Choose a more compressed GGUF quantization.
- Reduce the context length.
- Close memory-heavy applications.
- Update Unsloth and your GPU driver, then retry.
A CPU fallback can prove the model path works, but it may be far slower. Slow is not the same as broken.
Windows downloads are extremely slow
Update to v0.1.701-beta or later. The release notes specifically say this version fixed severe Windows download throttling. Also check free disk space, VPN/proxy interference and whether security software is scanning a large model file in real time.
The Mac installer asks for command-line tools
Again, update first. Unsloth says v0.1.701-beta fixed a macOS issue that incorrectly asked users to download command-line tools because of a uv bug.
unsloth start codex or unsloth start claude is not found
- Close and reopen the terminal after installing Unsloth.
- Confirm Unsloth Desktop is current and a model is loaded.
- Confirm the target agent is installed.
- Run the command from the project folder, not from an unrelated directory.
- If the shell still cannot find
unsloth, use the Desktop app’s integration instructions or repair/reinstall from the official release.
The API returns 401, 404 or “model not found”
- Copy the current base URL and key from Unsloth instead of retyping them.
- Make sure a model is loaded before calling the API.
- List the available models and use the returned ID.
- Check whether your client expects Chat Completions, Responses or Messages format.
What Unsloth’s performance claims actually mean
Unsloth says supported training workloads can be up to 2× faster and use up to 70% less VRAM. It also claims up to 50% more accurate tool calling from its self-healing process, plus up to 2× faster inference for supported image and video workflows.
Those are Unsloth’s vendor claims, not results from my machine. “Up to” is doing real work in each sentence: outcomes depend on the model, hardware, backend, quantization and task. I would evaluate the app on whether your chosen model runs reliably and produces useful output—not on the best number in a launch announcement.
Frequently asked questions
Is Unsloth Desktop free and open source?
Yes. Unsloth Desktop is open-source software distributed under AGPLv3. Other parts of the Unsloth repository use Apache 2.0, and models downloaded through the app keep their own separate licences and restrictions. Check each applicable licence before redistribution or commercial embedding.
Can Unsloth Desktop run without a GPU?
Yes for supported CPU workflows. Unsloth specifically lists CPU support for chat and Data Recipes. A GPU can make a large difference to speed, and model size still needs to be realistic for the memory available.
Is it completely offline?
The model can run locally after its files are downloaded, but the initial installer and model downloads need a network connection. Web search, cloud model providers and Cloudflare remote access also use external services. “Local-first” is more precise than assuming every feature is offline, and the available Desktop documentation is not clear enough for me to promise zero telemetry.
Can it train models as well as run them?
Yes, for supported models and hardware. Training support varies by model and backend, so verify the model’s official Unsloth page before planning a long run. Get inference working first.
Does unsloth start codex make Codex itself offline?
It routes the agent workflow to the loaded local model through Unsloth’s compatible API. The agent application may still have its own update checks, settings or network behaviour. Review that client’s privacy and telemetry controls separately.
Which model should I download first?
Start with a small instruction-tuned GGUF and a lower-memory quantization. There is no single best starter model for every machine. The first goal is a reliable response, not a benchmark win.
My verdict
Unsloth Desktop is interesting because it tries to join pieces that normally live in separate tools: a model hub, local chat, training, media workflows, API serving and agent connections. That is also why restraint matters. There are a lot of buttons you can press before you have proved the basic model works.
I would install the beta, keep it on localhost, load one small GGUF and use it for an ordinary chat. If that is solid, try the API. Then connect a coding agent inside a disposable folder. Remote access and tool execution come last. It is not the flashiest order, but it gives you a much better chance of knowing what went wrong.
If your real goal is local video generation rather than text or coding, continue with the MiniMax-H3 ComfyUI guide.