Skip to content

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.

Studio: keep skills created in Docker on the unsloth-studio volume (#13912)

Nilaycf0b66c83ae6
diff --git a/docker/DOCKERHUB-ROCM.md b/docker/DOCKERHUB-ROCM.md
index 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, acce
Not 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:
```bash
docker 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.md
index 9ab6de458c1..fada7854eb6 100644
--- a/docker/DOCKERHUB.md
+++ b/docker/DOCKERHUB.md
@@ -63,7 +63,7 @@ docker rm -f unsloth # stop and delete the container
docker 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.studio
index cd53b84b356..67a779b97be 100644
--- a/docker/Dockerfile.studio
+++ b/docker/Dockerfile.studio
@@ -64,6 +64,7 @@ USER root
ENV 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-rocm
index a5dd1656872..0595181e1bd 100644
--- a/docker/Dockerfile.studio-rocm
+++ b/docker/Dockerfile.studio-rocm
@@ -86,6 +86,7 @@ ARG UNSLOTH_NOTEBOOKS_REF=main
ENV 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.sh
index 42f2b5768e5..57a11bfea85 100755
--- a/docker/studio_home.sh
+++ b/docker/studio_home.sh
@@ -184,6 +184,23 @@ if [ -s "$APP/.src-update.rollback" ]; then
fi
fi
+# 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 ]; then
size="$(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.py
index 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, None
if is_owner_context():
+ override = _owner_skills_dir()
+ if override is not None:
+ return override.parent, Path(override.name)
return _owner_home(), None
return 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.py
index 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.py
index af6cd60ceeb..3dcdf8e6d01 100644
--- a/studio/backend/tests/test_skills.py
+++ b/studio/backend/tests/test_skills.py
@@ -4,6 +4,7 @@
import codecs
import json
import os
+import re
import sys
import threading
from 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_as
diff --git a/tests/python/test_docker_studio_home_volume.py b/tests/python/test_docker_studio_home_volume.py
index 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")