Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: keep skills created in Docker on the unsloth-studio volume (#13912)
Nilaycf0b66c83ae6
diff --git a/docker/DOCKERHUB-ROCM.md b/docker/DOCKERHUB-ROCM.mdindex dcdfe8d43cd..f04abddb94a 100644--- a/docker/DOCKERHUB-ROCM.md+++ b/docker/DOCKERHUB-ROCM.md@@ -113,7 +113,7 @@ Included: PyTorch with ROCm, Unsloth, unsloth-zoo, transformers, TRL, PEFT, acceNot included in `latest`, unlike `unsloth/unsloth`: Unsloth Studio and its web UI, JupyterLab, prebuilt llama.cpp and whisper.cpp, vLLM and xformers. `latest` is a training image.-The `studio` tag adds Unsloth Studio, JupyterLab with the Unsloth notebooks (the `AMD-*` set first) and a Vulkan llama.cpp for GGUF chat, still without whisper.cpp, vLLM or xformers. Training, the notebooks, the UI and GGUF chat all use the GPU. GGUF chat reaches the card through Vulkan (Mesa's RADV driver) on `/dev/dri`, which covers RDNA cards without pinning the image to one architecture; on CDNA (which RADV does not drive) or on the WSL2 bridge, it runs on the CPU instead. Vulkan does not read `HIP_VISIBLE_DEVICES`: on a host with several AMD GPUs, pick the chat GPU in Studio or pass only that card's `/dev/dri/renderD*` node. Studio's data (accounts, chats, project folders, outputs) lives at `/opt/unsloth-studio`, so mount a volume there to keep it, and one on `/workspace` for the notebooks, your edits and what they save (projects created by an image from before project folders moved to the volume keep their folder under `/root/Documents` inside the container, so copy their files out before `docker rm`), with `GPU_FLAGS` set as in the quick start:+The `studio` tag adds Unsloth Studio, JupyterLab with the Unsloth notebooks (the `AMD-*` set first) and a Vulkan llama.cpp for GGUF chat, still without whisper.cpp, vLLM or xformers. Training, the notebooks, the UI and GGUF chat all use the GPU. GGUF chat reaches the card through Vulkan (Mesa's RADV driver) on `/dev/dri`, which covers RDNA cards without pinning the image to one architecture; on CDNA (which RADV does not drive) or on the WSL2 bridge, it runs on the CPU instead. Vulkan does not read `HIP_VISIBLE_DEVICES`: on a host with several AMD GPUs, pick the chat GPU in Studio or pass only that card's `/dev/dri/renderD*` node. Studio's data (accounts, chats, project folders, the skills made in it, outputs) lives at `/opt/unsloth-studio`, so mount a volume there to keep it, and one on `/workspace` for the notebooks, your edits and what they save (projects and skills created by an image from before they moved to the volume stay under `/root/Documents` and `/root/.agents/skills` inside the container, so copy them out before `docker rm`; skills go in `/opt/unsloth-studio/skills`), with `GPU_FLAGS` set as in the quick start:```bashdocker run --rm $GPU_FLAGS --ipc=host -p 127.0.0.1:8000:8000 -p 127.0.0.1:8888:8888 \diff --git a/docker/DOCKERHUB.md b/docker/DOCKERHUB.mdindex 9ab6de458c1..fada7854eb6 100644--- a/docker/DOCKERHUB.md+++ b/docker/DOCKERHUB.md@@ -63,7 +63,7 @@ docker rm -f unsloth # stop and delete the containerdocker ps -a # find it again, running or not```-`docker rm -f` deletes the container, not your work: models stay in the Hugging Face cache, your files in the directory you mounted, the notebooks with your edits and what they save on the `unsloth-workspace` volume, and Unsloth Studio's accounts, chats and project folders on the `unsloth-studio` volume, so the next container with the same `-v unsloth-studio:/opt/unsloth-studio` resumes where this one left off, password included. Only what was written inside the container is lost, which includes the folders of projects created by an image from before project folders moved to the volume: those keep their old place under `/root/Documents`, so copy their files out before removing the container. `docker volume rm unsloth-studio` discards the Unsloth Studio data too, and cannot be undone.+`docker rm -f` deletes the container, not your work: models stay in the Hugging Face cache, your files in the directory you mounted, the notebooks with your edits and what they save on the `unsloth-workspace` volume, and Unsloth Studio's accounts, chats, project folders and the skills made in it on the `unsloth-studio` volume, so the next container with the same `-v unsloth-studio:/opt/unsloth-studio` resumes where this one left off, password included. Only what was written inside the container is lost, which includes the folders of projects created by an image from before project folders moved to the volume, and the skills it created: those keep their old place under `/root/Documents` and `/root/.agents/skills`, so copy them out before removing the container (skills go in `/opt/unsloth-studio/skills`). `docker volume rm unsloth-studio` discards the Unsloth Studio data too, and cannot be undone.These take a container, not an image, so `docker stop unsloth/unsloth` fails with "No such container". Use the `NAMES` or `CONTAINER ID` column of `docker ps -a`; without `--name`, Docker assigns a random one.@@ -152,7 +152,7 @@ The working directory is `/workspace`. Mount what you want to keep:| `/workspace` | The notebooks, your edits to them and what they save (`lora_model/`, `outputs/`). Use a named volume: without one, `docker rm` loses them. Files the image puts there, such as `smoke_test.py`, keep the first image's copy. || `/workspace/host` | Your files. Mount your project directory here. || `/workspace/.cache/huggingface` | Model downloads. Mount your host HF cache to reuse it. |-| `/opt/unsloth-studio` | Unsloth Studio's accounts, chats, project folders, outputs, exports and runs (`latest`). Use a named volume: without one, `docker rm` loses them. |+| `/opt/unsloth-studio` | Unsloth Studio's accounts, chats, project folders, the skills made in it, outputs, exports and runs (`latest`). Use a named volume: without one, `docker rm` loses them. || `/workspace/.cache/triton` | Compiled kernels. Optional, speeds up restarts. || `/workspace/unsloth-notebooks` | The synced notebooks. Your edits are kept across refreshes. || `/workspace/Unsloth Notebooks` | The same notebooks grouped by topic, rebuilt on each start. |diff --git a/docker/Dockerfile.studio b/docker/Dockerfile.studioindex cd53b84b356..67a779b97be 100644--- a/docker/Dockerfile.studio+++ b/docker/Dockerfile.studio@@ -64,6 +64,7 @@ USER rootENV UNSLOTH_STUDIO_HOME=/opt/unsloth-studio \UNSLOTH_STUDIO_APP=/opt/unsloth-studio-app \UNSLOTH_STUDIO_DOCUMENTS_HOME=/opt/unsloth-studio/documents \+ UNSLOTH_STUDIO_SKILLS_HOME=/opt/unsloth-studio/skills \UV_CACHE_DIR=/opt/unsloth-studio-app/uv-cache \UNSLOTH_IMAGE_ALLOW_CPU=1 \JUPYTER_PORT=8888 \diff --git a/docker/Dockerfile.studio-rocm b/docker/Dockerfile.studio-rocmindex a5dd1656872..0595181e1bd 100644--- a/docker/Dockerfile.studio-rocm+++ b/docker/Dockerfile.studio-rocm@@ -86,6 +86,7 @@ ARG UNSLOTH_NOTEBOOKS_REF=mainENV UNSLOTH_STUDIO_HOME=/opt/unsloth-studio \UNSLOTH_STUDIO_APP=/opt/unsloth-studio-app \UNSLOTH_STUDIO_DOCUMENTS_HOME=/opt/unsloth-studio/documents \+ UNSLOTH_STUDIO_SKILLS_HOME=/opt/unsloth-studio/skills \UV_CACHE_DIR=/opt/unsloth-studio-app/uv-cache \JUPYTER_PORT=8888 \UNSLOTH_STUDIO_PORT=8000 \diff --git a/docker/studio_home.sh b/docker/studio_home.shindex 42f2b5768e5..57a11bfea85 100755--- a/docker/studio_home.sh+++ b/docker/studio_home.sh@@ -184,6 +184,23 @@ if [ -s "$APP/.src-update.rollback" ]; thenfifi+# Studio keeps the owner's skills on the volume; ~/.agents/skills, which the Skills dialog and+# other agents in the container use, points there.+skills="${UNSLOTH_STUDIO_SKILLS_HOME:-}"+if [ -n "$skills" ]; then+ (umask 077 && mkdir -p -- "$skills") || log "WARNING: cannot create $skills"+ agents="${HOME:-/root}/.agents/skills"+ current="$(readlink -- "$agents" || true)"+ if [ "$current" = "$skills" ]; then+ :+ elif { [ ! -e "$agents" ] && [ ! -L "$agents" ]; } || [ "$current" = "$HOME_DIR/skills" ]; then+ { (umask 077 && mkdir -p -- "${agents%/*}") && ln -sfnT -- "$skills" "$agents"; } \+ || log "WARNING: cannot link $agents to $skills"+ else+ log "WARNING: Unsloth Studio lists and saves skills in $skills, not in $agents"+ fi+fi+if [ "${#moved[@]}" -gt 0 ]; thensize="$(du -sh -- "$legacy" 2>/dev/null | cut -f1)"log "kept aside in $legacy (${size:-?}): ${moved[*]}"diff --git a/studio/backend/core/inference/skills.py b/studio/backend/core/inference/skills.pyindex c1136aeb744..fd43a73c305 100644--- a/studio/backend/core/inference/skills.py+++ b/studio/backend/core/inference/skills.py@@ -109,6 +109,9 @@ def _agents_base(home: Optional[Path]) -> tuple[Path, Optional[Path]]:if home is not None:return home, Noneif is_owner_context():+ override = _owner_skills_dir()+ if override is not None:+ return override.parent, Path(override.name)return _owner_home(), Nonereturn workspace_root(), Path(_MANAGED_SKILLS_DIR)@@ -402,6 +405,17 @@ def _owner_home() -> Path:return Path.home()+def _owner_skills_dir() -> Optional[Path]:+ override = (os.environ.get("UNSLOTH_STUDIO_SKILLS_HOME") or "").strip()+ return Path(override).expanduser() if override else None+++def _agents_display() -> str:+ if not is_owner_context():+ return _MANAGED_SKILLS_DIR+ return str(_owner_skills_dir() or "~/.agents/skills")++def _skill_roots(home: Optional[Path] = None) -> tuple[tuple[str, Path], ...]:if home is not None:base = home@@ -411,7 +425,7 @@ def _skill_roots(home: Optional[Path] = None) -> tuple[tuple[str, Path], ...]:return (("agents", workspace_root() / _MANAGED_SKILLS_DIR), _BUNDLED_ROOT)base = _owner_home()return (- ("agents", base / ".agents" / "skills"),+ ("agents", _owner_skills_dir() or base / ".agents" / "skills"),("claude", base / ".claude" / "skills"),_BUNDLED_ROOT,)@@ -706,7 +720,7 @@ def create_skill(raise# The path as the user would name it, not the resolved host path.- display = "~/.agents/skills" if root is None else f"{_MANAGED_SKILLS_DIR}"+ display = "~/.agents/skills" if home is not None else _agents_display()return {**metadata,"source": "agents",@@ -775,7 +789,7 @@ def read_skill_manifest(name: str, *, home: Optional[Path] = None) -> dict:)_, body = _split_skill_markdown(raw)display = {- "agents": "~/.agents/skills" if is_owner_context() else _MANAGED_SKILLS_DIR,+ "agents": _agents_display(),"claude": "~/.claude/skills",}.get(record["source"])return {diff --git a/studio/backend/tests/conftest.py b/studio/backend/tests/conftest.pyindex 222c1159a37..5febdc7f7a0 100644--- a/studio/backend/tests/conftest.py+++ b/studio/backend/tests/conftest.py@@ -181,6 +181,7 @@ def _isolate_agent_skills(_skills_home_root, monkeypatch):home = _skills_home_root / f"h{next(_skills_home_counter)}"home.mkdir()# Owner home under tmp, bundled root empty; managed-account roots stay for the account matrix.+ monkeypatch.delenv("UNSLOTH_STUDIO_SKILLS_HOME", raising = False)monkeypatch.setattr(_skills, "_owner_home", lambda: home)monkeypatch.setattr(_skills, "_BUNDLED_ROOT", ("bundled", home / "bundled-absent"))try:diff --git a/studio/backend/tests/test_skills.py b/studio/backend/tests/test_skills.pyindex af6cd60ceeb..3dcdf8e6d01 100644--- a/studio/backend/tests/test_skills.py+++ b/studio/backend/tests/test_skills.py@@ -4,6 +4,7 @@import codecsimport jsonimport os+import reimport sysimport threadingfrom pathlib import Path@@ -659,6 +660,30 @@ def _account_skill(studio: Path, account_id: str, name: str, description: str) -)[email protected]("dockerfile", ["Dockerfile.studio", "Dockerfile.studio-rocm"])+def test_skills_created_in_the_studio_images_outlive_the_container(+ dockerfile, tmp_path, monkeypatch+):+ text = (Path(__file__).resolve().parents[3] / "docker" / dockerfile).read_text(encoding = "utf-8")+ block = text[text.index("ENV UNSLOTH_STUDIO_HOME=") :]+ image_env = dict(re.findall(r"(\w+)=(\S+)", block[: block.index("\n\n")]))+ volume = tmp_path / "volume"+ for name, value in image_env.items():+ monkeypatch.setenv(name, value.replace(image_env["UNSLOTH_STUDIO_HOME"], str(volume)))+ monkeypatch.setattr(skills, "studio_root", lambda: volume)+ monkeypatch.setattr(skills, "_owner_home", lambda: tmp_path / "first-container")++ record = skills.create_skill("release-notes", "Draft release notes.", "Summarize the diff.")+ assert record["path"] == f"{volume / 'skills'}/release-notes/SKILL.md"++ monkeypatch.setattr(skills, "_owner_home", lambda: tmp_path / "second-container")+ assert [r["name"] for r in skills.list_skills()] == ["release-notes"]+ skills.update_skill("release-notes", "Edited.", "Summarize the diff again.")+ assert skills.read_skill_manifest("release-notes")["description"] == "Edited."+ skills.delete_skill("release-notes")+ assert skills.list_skills() == []++def test_managed_account_never_sees_the_owners_home_skills(managed_accounts):from utils.account_context import run_asdiff --git a/tests/python/test_docker_studio_home_volume.py b/tests/python/test_docker_studio_home_volume.pyindex fcf11b5f258..65e294763c3 100644--- a/tests/python/test_docker_studio_home_volume.py+++ b/tests/python/test_docker_studio_home_volume.py@@ -575,6 +575,70 @@ def test_the_uv_cache_goes_with_the_code_and_cache_stays_data():), "the build must prove the uv cache did not land in the home"+def test_agents_skills_in_the_container_point_at_the_skills_on_the_volume(tmp_path):+ app, home, root = _app(tmp_path), tmp_path / "home", tmp_path / "root"+ env = {"UNSLOTH_STUDIO_SKILLS_HOME": str(home / "skills"), "HOME": str(root)}+ for _ in range(2):+ res = _link(app, home, env = env)+ assert res.returncode == 0, res.stderr+ assert (home / "skills").is_dir() and not (home / "skills").is_symlink()+ assert os.readlink(root / ".agents" / "skills") == str(home / "skills")++ (home / "skills" / "notes").mkdir()+ assert (root / ".agents" / "skills" / "notes").is_dir()+++def test_a_skills_home_set_at_run_time_retargets_the_baked_link(tmp_path):+ app, home, root = _app(tmp_path), tmp_path / "home", tmp_path / "root"+ (root / ".agents").mkdir(parents = True)+ (root / ".agents" / "skills").symlink_to(home / "skills")+ res = _link(+ app, home, env = {"UNSLOTH_STUDIO_SKILLS_HOME": str(tmp_path / "mine"), "HOME": str(root)}+ )+ assert res.returncode == 0, res.stderr+ assert os.readlink(root / ".agents" / "skills") == str(tmp_path / "mine")+ assert (tmp_path / "mine").is_dir()+++def test_a_users_own_agents_skills_link_is_left_alone(tmp_path):+ app, home, root = _app(tmp_path), tmp_path / "home", tmp_path / "root"+ (root / ".agents").mkdir(parents = True)+ (root / ".agents" / "skills").symlink_to(tmp_path / "dotfiles")+ res = _link(+ app, home, env = {"UNSLOTH_STUDIO_SKILLS_HOME": str(home / "skills"), "HOME": str(root)}+ )+ assert res.returncode == 0, res.stderr+ assert os.readlink(root / ".agents" / "skills") == str(tmp_path / "dotfiles")+ assert str(home / "skills") in res.stderr+++def test_a_mounted_agents_skills_folder_is_left_alone_and_named(tmp_path):+ app, home, root = _app(tmp_path), tmp_path / "home", tmp_path / "root"+ (root / ".agents" / "skills" / "mine").mkdir(parents = True)+ res = _link(+ app, home, env = {"UNSLOTH_STUDIO_SKILLS_HOME": str(home / "skills"), "HOME": str(root)}+ )+ assert res.returncode == 0, res.stderr+ assert (root / ".agents" / "skills" / "mine").is_dir()+ assert not (root / ".agents" / "skills").is_symlink()+ assert str(home / "skills") in res.stderr+++def test_without_a_skills_home_the_agents_folder_is_not_touched(tmp_path):+ app, home, root = _app(tmp_path), tmp_path / "home", tmp_path / "root"+ env = dict(os.environ, HOME = str(root))+ env.pop("UNSLOTH_STUDIO_SKILLS_HOME", None)+ res = subprocess.run(+ ["bash", str(LINKER)],+ env = dict(env, UNSLOTH_STUDIO_APP = str(app), UNSLOTH_STUDIO_HOME = str(home)),+ capture_output = True,+ text = True,+ timeout = 60,+ )+ assert res.returncode == 0, res.stderr+ assert not (root / ".agents").exists() and not (home / "skills").exists()++def test_the_entrypoint_relinks_before_it_touches_the_studio_venv_and_stops_on_failure():"""A half-linked home must not reach Studio: the hook exits instead of warning."""body = ENTRYPOINT.read_text(encoding = "utf-8")