내 컴퓨터에서 모델을 돌려 Claude Code에 붙이는 Unsloth Desktop
Tools15분 읽기

내 컴퓨터에서 모델을 돌려 Claude Code에 붙이는 Unsloth Desktop

Unsloth Desktop 설치부터 unsloth start claude 첫 실행까지 따라 하고, 파일이 안 고쳐질 때와 느려질 때의 처방, 샌드박스 단계, 포트를 열 때의 위험을 정리했습니다.

로컬 모델을 Claude Code에 붙이려면 지금까지는 손이 많이 갔습니다. 모델 서버를 따로 띄우고, 주소·키·모델 이름 환경 변수를 셸마다 맞추고, 느려지면 설정 파일을 열어 변수 하나를 더하고, 그래도 파일이 안 고쳐지면 서버 옵션을 뒤져야 했습니다. 어디서 막혔는지 알려 주는 메시지도 거의 없어서 대부분 한나절을 쓰고서야 “답은 하는데 아무것도 안 바뀌는” 상태에 도착합니다. Unsloth Desktop은 이 과정을 unsloth start claude 한 줄로 줄여 주는 앱이고, 이 글은 그 한 줄까지 가는 길을 설치부터 실제로 치는 명령 순서대로 따라갑니다. 중간에 막히는 두 곳(파일 수정 안 됨, 속도 저하)의 원인과 처방, 도구에 맡길 권한의 단계, 포트를 열 때의 위험까지 같이 다룹니다. 기준은 2026-10-27 UTC 시점의 공식 문서와 GitHub 릴리스(최신 v0.1.911-beta, 10월 26일)입니다.

설치 전에 확인할 세 가지: 앱 종류, 기기 메모리, 라이선스

이름이 비슷한 것이 세 개 있어서 먼저 구분합니다. Desktop은 Tauri 기반 설치형 앱이고 문서에 베타로 표기된 상태입니다. Studio는 같은 기능을 브라우저에서 쓰는 웹 UI로 unsloth studio로 띄우며 서버·원격 접속용입니다. Core는 코드로 쓰는 파이썬 미세 조정 라이브러리입니다. 이 글의 주인공은 Desktop이고, 에이전트 연결 명령 unsloth start와 서버 명령 unsloth run은 같은 엔진을 쓰는 CLI입니다. GGUF 모델은 llama.cpp 계열로, Mac의 MLX 모델은 MLX로 돌아갑니다.

기기는 NVIDIA·AMD·Intel 그래픽과 Mac이 모두 대상이고, v0.1.909부터는 NVIDIA가 아닌 PC도 Vulkan으로 GGUF를 그래픽 장치에서 돌립니다. 그래픽 장치가 아예 없어도 Studio는 CPU만으로 GGUF 채팅과 데이터셋 만들기를 지원합니다. 학습은 그래픽 장치(또는 Mac의 MLX)가 필요하고, 문서는 오래된 하드웨어가 잘 지원되지 않을 수 있다고 적습니다. 운영체제는 Windows 10·11(64비트), macOS 12 이상, Linux·WSL입니다.

저장소는 별이 약 7만 8천 개, 포크가 7천여 개이고 라이선스가 둘로 갈립니다. 코어 패키지는 Apache-2.0, Studio UI와 일부 선택 구성요소는 AGPL-3.0입니다. 내 컴퓨터에서 쓰는 한 문제될 일이 없지만, UI 부분을 고쳐 네트워크 서비스로 내놓으려면 AGPL의 소스 공개 의무를 먼저 확인해야 합니다. 텔레메트리는 없다고 문서가 밝히고(GPU와 기기 종류는 앱이 돌릴 수 있는 것을 정하려고 감지), 모델을 한 번 받은 뒤에는 오프라인으로 실행됩니다.

앱 설치부터 첫 대화까지

여기서는 Claude Code가 이미 설치돼 있다고 가정합니다. 문서가 안내하는 공식 설치 스크립트는 curl -fsSL https://claude.ai/install.sh | bash(Windows는 PowerShell의 irm https://claude.ai/install.ps1 | iex)이고, 이미 쓰고 있다면 건드릴 것이 없습니다. macOS 기준으로 Desktop 설치는 다음 순서입니다.

  1. unsloth.ai의 내려받기 페이지(또는 GitHub 릴리스)에서 Mac용 .dmg를 받아 열고, Unsloth를 Applications로 끌어다 놓습니다. Windows는 .exe, Linux는 .deb·ARM64용 .deb·AppImage가 같은 곳에 있습니다.
  2. 앱을 켜고 설치가 끝나기를 기다립니다. v0.1.910부터는 채팅만 쓰는 사람을 위한 작은 설치 빌드가 따로 있고, 학습 도구는 나중에 설정에서 더하면 됩니다.
  3. "Select model" 목록이나 Model hub 탭에서 Hugging Face의 모델을 고르고, 내 메모리에 맞는 양자화 변형을 받습니다.
  4. 내려받기가 끝나면 메시지를 입력해 대화가 되는지 먼저 확인합니다. 여기서 안 되면 에이전트를 붙여도 안 됩니다.

Homebrew 명령 brew install --cask unsloth는 Desktop이 아니라 Studio를 설치하는 경로라고 Mac 설치 문서가 구분합니다. 같은 문서에서 앱을 지울 때는 Finder의 Applications에서 Unsloth를 휴지통으로 옮기면 됩니다.

설치 파일과 관련해 하나 더 있습니다. v0.1.910 릴리스 노트에는 설치 프로그램이 eMudhra가 발급한 문제 인증서를 거부하게 됐다는 항목이 있습니다. 앱은 공식 내려받기 페이지나 GitHub 릴리스에서만 받고 서명 경고가 뜨면 설치를 멈추는 것이 안전합니다.

내 기기 메모리에 올려 본 10월의 모델들

모델 선택 창에서 가장 먼저 부딪히는 것은 이름 뒤의 꼬리표입니다. UD-Q4_K_XL에서 Q4는 4비트 양자화, 곧 모델의 숫자를 더 적은 비트로 줄여 메모리를 아끼는 방식이고 줄일수록 가벼워지는 대신 품질 손실이 생깁니다. 앞의 UD는 Unsloth Dynamic으로, 모든 층에 같은 비트를 쓰지 않고 층마다 배분한 GGUF라고 Unsloth 문서가 설명합니다. 저장소 이름 뒤에 콜론으로 붙이면(unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL) 그 변형을 고르는 뜻입니다. Llama나 Gemma처럼 접근이 막힌 게이트 모델은 Hugging Face 토큰이 있어야 받아지고, 입력하면 바로 검증됩니다.

그러면 내 기기에는 어느 크기까지 올라갈까요. 릴리스 노트와 문서에 메모리가 적힌 모델만 모아 놓으면 선이 어디에 걸리는지 보입니다. 비트 수가 행마다 다르므로 같은 조건의 비교는 아니고, 문서가 말한 값 그대로입니다.

10월에 추가되거나 문서에 메모리가 적힌 모델 7개의 필요 메모리를 24GB, 64GB 기준선과 함께 보여 주는 가로 막대 차트 그림 1. 24GB 선 안에 들어오는 것은 4비트 Qwen3.5-35B-A3B(약 23GB, 24GB 그래픽 장치 예)와 3비트 Flint(짧은 컨텍스트 기준)뿐이다

24GB 선을 넘는 순간 다른 종류의 이야기가 됩니다. Nemotron 3.5 Bolt(74B, 활성 9B)는 1~2비트에서 약 32GB, Nemotron 3.5 Super VL(120B, 활성 12B)은 1비트에서 약 64GB입니다. DeepSeek-V4.1-Flash-1017은 1비트에서 약 125GB로, Engram 표를 SSD에 두는 조건이 붙습니다. MiniMax-M3.1-Flash는 1비트에서 램과 그래픽 메모리를 합쳐 130GB 이상, Muse Spark Open은 2비트에서 약 256GB입니다. 같은 기기에 더 큰 모델을 올리는 길도 있습니다. v0.1.910에는 Mac에서 메모리보다 큰 MoE 모델의 전문가를 SSD에 두는 방식이 들어가서, 32GB Mac에서 Qwen3.8-Flash-Next를 돌리는 예가 릴리스 노트에 올라 있습니다.

참고로 학습까지 할 생각이라면 요구가 더 큽니다. 문서의 최소 VRAM 표(절대 하한)로 QLoRA는 8B가 6GB, 27B가 22GB, 70B가 41GB이고, 같은 70B를 16비트 LoRA로 하면 164GB로 뜁니다. 메모리가 모자라면 배치 크기를 1~3으로 낮추라고 문서가 안내합니다. 이 글은 에이전트 연결이 중심이라 학습은 여기까지만 다룹니다.

unsloth start claude를 처음 실행하면

모델이 떠 있는 앱을 켜 두고 프로젝트 폴더로 이동해 unsloth start claude를 치면 됩니다. 이 명령이 하는 일은 이번 실행에만 쓰는 임시 설정을 만들어 Claude Code에 건네는 것이고, 엔드포인트·API 키·모델·컨텍스트 길이가 거기 들어갑니다. 평소 쓰는 Claude Code 설정 파일에는 Unsloth가 추가되지 않는다고 문서가 설명합니다. 앱이 꺼져 있다면 --model로 모델을 지정하면 임시 서버가 뜨고, 에이전트가 끝날 때 함께 종료됩니다. 앱이 이미 떠 있으면 그대로 연결하고 서버는 켜 둔 채로 둡니다.

dry run, 앱에 연결, 모델 지정 실행, 이어가기 네 가지 명령을 순서대로 보여 주는 터미널 화면 그림 2. 네 줄이 하루치 사용법이다. 문서가 실제 출력 예를 싣지 않아 명령과 주석만 담았다

처음이라면 네 줄 중 첫 번째 --no-launch부터 눌러 보는 편이 좋습니다. 실행하지 않고 만들어질 환경 변수와 명령만 출력하므로 무엇이 설정되는지 볼 수 있습니다. 다만 출력에 접속 자격 증명이 들어갈 수 있다고 문서가 경고하니 로그나 스크린샷에 올리면 안 됩니다. 옵션을 하나도 주지 않으면 Unsloth가 모델에 맞는 컨텍스트 길이와 샘플링 값을 고릅니다. 직접 고르려면 아래 옵션을 씁니다.

옵션 하는 일
--model, -m 모델 지정. 생략하면 Unsloth가 알려 주는 첫 모델
--gguf-variant GGUF 양자화 변형 선택
--context-length 모델을 불러올 때 요청하는 컨텍스트 길이
--reasoning, --reasoning-effort 생각 모드 켬·끔·자동, 수준 지정(수준은 모델마다 다름)
--serve / --no-serve 임시 서버를 자동으로 띄울지
--persist Unsloth가 만든 에이전트 홈을 유지(Claude Code는 불필요)
--yolo 에이전트의 무확인 모드. 명령을 묻지 않고 실행하므로 잃어도 되는 폴더에서만

Unsloth 옵션이 아닌 인자는 에이전트에 그대로 전달되어 --continue로 마지막 세션을 이어 갈 수 있습니다. 첫 질문은 읽기만 하는 것으로 고르세요. “이 저장소의 구조를 요약해 줘” 정도면 연결과 속도를 한 번에 확인하고, 파일을 고치게 하는 요청은 그다음입니다.

답은 하는데 파일이 그대로일 때

읽기 질문은 잘 되는데 “README 오타를 고쳐 줘”에는 어떻게 고치면 된다는 설명만 나오고 파일은 그대로라면, 모델 문제가 아니라 도구 호출이 가는 길의 문제입니다. Unsloth 서버는 자체 도구(코드 실행, 웹 검색, 터미널)를 갖고 있고, 로컬 주소(127.0.0.1)에서는 기본으로 켜져 있습니다. Claude Code에 모델을 수동으로 연결하는 문서는 서버를 --disable-tools로 띄우는 것이 코딩 에이전트에 필수라고 못 박으며 이유를 이렇게 설명합니다. 서버 도구가 모델이 낸 도구 호출을 먼저 가로채기 때문에 Claude Code는 답은 받지만 파일을 고치라는 요청은 자기에게 도착하지 않습니다.

서버 도구가 켜진 경우에는 모델의 도구 호출을 서버 도구가 가로채 Claude Code에는 텍스트만 가고, 끈 경우에는 호출이 Claude Code로 돌아가 Edit 도구가 README를 고치는 두 경로의 비교 그래프 그림 3. 같은 도구 호출을 서버가 실행하면 파일이 그대로이고, 에이전트에게 돌려보내면 고쳐진다

처방은 서버 쪽 옵션이고 에이전트 설정이 아닙니다. 서버를 직접 띄우는 명령은 이렇습니다.

unsloth run \
  --model unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL \
  --disable-tools \
  --reasoning off \
  -p 8888

unsloth run은 서버를 시작하고 UI를 불러오며 엔드포인트 주소와 API 키를 출력합니다. --disable-tools와 --enable-tools는 서버 전체에 적용되는 설정이고 요청이 enable_tools=true를 보내 바꿀 수는 없습니다. 이 옵션을 바꿨다면 서버를 재시작하고 같은 요청을 다시 시험합니다. 서버 도구(웹 검색·코드 실행)를 함께 쓰고 싶다면 이 서버는 에이전트 전용으로 두고, 도구가 켜진 서버는 다른 포트에 따로 띄우는 식으로 나누면 두 용도가 섞이지 않습니다.

대화가 한 턴마다 굼뜨게 느려질 때

두 번째 함정은 속도입니다. 로컬 모델은 요청의 앞부분이 이전과 같으면 이미 계산한 값(KV 캐시)을 재활용해서 빨라집니다. 그런데 최근 Claude Code는 시스템 프롬프트 맨 앞에 요청마다 값이 달라지는 attribution(출처 표기) 줄을 붙이고, 앞줄이 바뀌면 캐시가 매번 무효가 됩니다. Unsloth 문서는 이 때문에 추론이 약 90% 느려질 수 있다고 설명합니다. 환경 변수 CLAUDE_CODE_ATTRIBUTION_HEADER를 0으로 두면 해결되며 LM Studio의 Claude Code 안내도 같은 변수를 적고 있습니다. 적용은 세 가지 방법이 있습니다.

# A. 실행할 때만(설정 파일을 건드리지 않음, 가장 확실)
claude --settings '{"env":{"CLAUDE_CODE_ATTRIBUTION_HEADER":"0","CLAUDE_CODE_ENABLE_TELEMETRY":"0"}}' \
  --model unsloth/gemma-4-26B-A4B-it-GGUF

# B. 셸 변수(최근 Claude Code는 인식, 구버전은 무시)
export CLAUDE_CODE_ATTRIBUTION_HEADER=0

세 번째는 ~/.claude/settings.json의 env에 같은 값을 넣는 것입니다. 구버전은 셸 변수를 무시하므로 A나 이 방법을 권한다고 문서가 말합니다. 파일에 이미 내용이 있다면 통째로 덮어쓰지 말고 env 안에 항목 하나만 더합니다.

속도를 더 줄이고 싶다면 문서가 권하는 실행 옵션이 있습니다. --bare --exclude-dynamic-system-prompt-sections를 붙이면 자동으로 찾는 훅·스킬·플러그인·MCP 서버·CLAUDE.md를 건너뛰고 기기마다 달라지는 부분이 프롬프트 앞에서 빠져 캐시 재활용이 늘어납니다. Bash와 파일 읽기·수정은 그대로 쓸 수 있습니다. 대신 CLAUDE.md의 규칙도 읽지 않으니 규칙에 의존하는 작업에서는 빼야 합니다.

앞에서 본 릴리스 노트를 보면 속도는 Unsloth 쪽에서도 계속 만지는 부분입니다. v0.1.907은 추론이 최대 5배 빨라지고 캐시 적중이 95%에 이른다고 적었고, v0.1.908은 로컬 GGUF 모델의 프롬프트 캐싱을 개선해 두 번째 턴부터 다시 읽는 양을 줄였다고 합니다.

같은 한 줄로 다른 에이전트 붙이기

claude 자리에 다른 이름을 넣으면 같은 모델에 다른 에이전트가 붙습니다. 문서의 지원 목록은 여덟 개이고 README에는 Mistral Vibe(vibe)가 더 있습니다. 조건과 세션 이어가기 규칙이 에이전트마다 다릅니다.

에이전트 명령 조건 세션 이어가기
Claude Code unsloth start claude 없음 --continue, --persist 불필요
OpenAI Codex unsloth start codex llama-server로 서빙한 GGUF 모델만 --persist 필요, resume --last
VS Code unsloth start vscode Copilot Chat 확장(요금제는 불필요), Agent 모드는 도구 호출과 32K 이상 컨텍스트 모델을 바꾸면 명령을 다시 실행
OpenCode unsloth start opencode 없음 --persist 불필요
Hermes unsloth start hermes 없음 --persist를 첫 실행부터
OpenClaw unsloth start openclaw 없음 --persist와 같은 세션 ID
Pi unsloth start pi 없음 --persist를 첫 실행부터
DeepSeek Harness unsloth start dsh 없음 문서에 따로 적힌 규칙 없음

Codex·OpenClaw·Hermes·Pi는 임시 홈을 쓰기 때문에 --persist를 첫 실행부터 붙이고, 돌아올 때도 다시 붙인 뒤 에이전트 고유의 이어가기 옵션을 넘겨야 합니다. --persist는 보존 공간만 유지하고 대화를 스스로 이어 주지 않습니다. 반대 방향의 연결도 생겼습니다. v0.1.909의 unsloth mcp add는 Claude Code·Codex·Cursor가 Unsloth를 MCP 서버로 쓰게 연결하는 명령이고, v0.1.907부터는 계정 API 키로 MCP에 접근합니다. 원격 서버를 쓰려면 UNSLOTH_STUDIO_URL과 UNSLOTH_API_KEY를 환경 변수로 주고 같은 명령을 실행하면 됩니다.

환경 변수로 직접 연결하는 길과 막히는 메시지

unsloth start 없이 연결하는 이유는 보통 서버가 다른 컴퓨터에 있거나 설정을 고정해 두고 싶어서입니다. 한 포트에서 Anthropic 방식(/v1/messages)과 OpenAI 방식(/v1/chat/completions, /v1/responses)이 모두 열립니다. 키는 앱의 Settings에서 API 탭으로 가 이름과 만료일을 정해 만들고, sk-unsloth-로 시작하며 Unsloth가 해시만 저장하므로 만든 순간에 복사해야 합니다. 폐기한 키와 틀린 키는 401을 받습니다.

export ANTHROPIC_BASE_URL="http://localhost:8888"
export ANTHROPIC_AUTH_TOKEN="sk-unsloth-여기에-키"
export ANTHROPIC_API_KEY=""
claude --model unsloth/gemma-4-26B-A4B-it-GGUF

모델 이름은 서버가 알려 주는 ID와 한 글자도 다르면 안 됩니다. GET http://localhost:8888/v1/models가 돌려주는 id를 그대로 --model에 넣습니다. 막힐 때는 증상으로 찾습니다.

증상 원인과 처방
Unable to connect to API (ConnectionRefused) 예전 세션의 주소 변수가 남았을 수 있어 unset ANTHROPIC_BASE_URL 후 다시 연결
No Unsloth server was found 앱을 켜고 모델을 불러 두거나, --model을 지정해 임시 서버를 띄움
답은 하는데 파일이 안 고쳐짐 서버를 --disable-tools로 재시작(앞의 그림 3)
한 턴마다 느림 CLAUDE_CODE_ATTRIBUTION_HEADER=0 적용
모델을 찾을 수 없음 /v1/models의 ID를 그대로 사용
Codex가 연결되지 않음 llama-server에서 도는 GGUF 모델인지 확인
세션이 복원되지 않음 Codex·OpenClaw·Hermes·Pi는 첫 실행부터 --persist

모델과 설정이 디스크 어디에 남나

써 보다가 그만두거나 용량이 모자랄 때 필요한 지도입니다. 모델은 Hugging Face 캐시(~/.cache/huggingface/hub/, 또는 HF_HUB_CACHE·HF_HOME이 가리키는 곳)에 쌓이고, 앱에서 직접 받은 것은 ~/.unsloth/studio/models에도 보입니다. 이미 받아 둔 모델은 앱이 자동으로 찾고 사용자 폴더도 추가할 수 있습니다.

Hugging Face 캐시, Unsloth Studio 폴더, Claude 설정, VS Code 설정, 프로젝트 폴더 가운데 무엇이 쓰이고 무엇이 그대로인지 보여 주는 파일 트리 그림 4. 모델 캐시와 Studio 폴더는 커지고, Claude 쪽 설정 파일은 직접 고치지 않는 한 그대로다

~/.claude가 그대로라는 점이 임시 설정 방식의 이점입니다. 예외는 VS Code입니다. 이 경우는 사용자 설정을 백업하고 모델 항목을 넣으며, 모델을 바꾸면 unsloth start vscode를 다시 실행해 항목을 갱신해야 합니다. SSH나 컨테이너 안처럼 VS Code 사용자 폴더가 없는 환경에서는 로컬에 넣을 설정과 포트 포워딩 안내만 출력하고, 원격 작업 공간의 모델 목록에 안 보이면 로컬 창을 쓰라고 문서가 안내합니다.

받은 모델은 모델 검색 창의 휴지통 아이콘이나 캐시 폴더 삭제로 지웁니다. Studio 폴더(~/.unsloth/studio)를 지우면 채팅 기록, 체크포인트, 내보내기 결과가 함께 사라지고 되돌릴 수 없다고 문서가 못 박으니 지우기 전에 내보낼 것은 내보냅니다.

도구 호출을 어디까지 허용할지: 샌드박스 단계

모델이 파일을 읽고 명령을 실행하게 두면 “어디까지 허용하느냐”가 곧 보안입니다. Unsloth는 서버 도구의 실행을 세 단계로 나눕니다. 낮음은 문자열·구문·정규식으로 위험한 호출을 거르는 소프트웨어 검사입니다. rm, dd, sudo, chmod, curl, wget, ssh, kill, eval, source 같은 명령과 파이썬의 os.system, subprocess, requests, 원시 소켓, /etc/passwd 같은 민감한 읽기를 막습니다. 높음은 진짜 운영체제 격리로, Linux는 bubblewrap, macOS는 Seatbelt, Windows는 MXC(Windows 11 24H2 이상에 기본 설치)를 씁니다. Full Access는 이 모두를 끕니다. 낮음과 높음 공통으로 비밀 환경 변수가 제거되고 Studio의 자격 파일은 거부되며, 파일 100MB·메모리 8GB·CPU 시간 600초·프로세스 수·호출 시간 제한이 걸립니다.

높음이 공짜가 아니라는 점은 호출당 지연이 보여 줍니다.

Windows, macOS, Linux에서 샌드박스 낮음과 높음의 호출당 지연을 밀리초로 비교한 묶음 막대 차트 그림 5. 높음 단계는 호출마다 Linux 50ms, macOS 110ms, Windows 164ms가 든다

낮음은 세 운영체제 모두 한 자리 밀리초이고, 높음은 Linux가 50ms로 가장 짧으며 Windows가 164ms로 가장 깁니다. 에이전트가 한 작업에서 도구를 수십 번 부르면 이 차이가 쌓이지만, 검사가 문자열 매칭이라 운영체제 격리보다 약한 보조 장치라는 사실이 더 무겁습니다. 낮음은 우회될 수 있는 방어이고 높음이 실제 벽입니다.

v0.1.911(10월 26일)에는 이 구조를 더 단단하게 하는 변경이 들어갔습니다. API 키로 접속한 앱이 샌드박스 밖에서 도는 파이썬·터미널 호출을 스스로 승인할 수 없게 됐고, 프록시가 전달한 클라이언트 IP도 기본으로는 믿지 않습니다. 키가 새도 키만으로는 샌드박스를 풀 수 없게 한 것입니다. 다만 Full Access로 두면 이 보호도 의미가 없어지므로, 에이전트를 붙인 서버에서 서버 도구를 쓰지 않을 거라면 앞서 본 --disable-tools가 가장 확실한 선택입니다.

집 컴퓨터를 밖에서 쓰려고 포트를 열 때

집의 그래픽 장치 컴퓨터를 노트북에서 쓰려면 서버를 다른 기기에 열어야 합니다. 어떻게 시작하느냐에 따라 닿는 범위가 달라집니다.

실행 닿는 곳
unsloth studio 이 컴퓨터만
unsloth studio -H 0.0.0.0 -p 8888 같은 네트워크
unsloth studio -H 0.0.0.0 --cloudflare 같은 네트워크 + 공개 Cloudflare 주소
unsloth studio --secure 공개 Cloudflare 주소만(LAN은 닫힘)

실행 중인 앱에서는 Settings의 API 탭 Remote & LAN 카드에서 LAN access를 Start하고 상태가 Online이 될 때까지 기다리는 방법도 있고, Start automatically 토글을 켜면 앱을 켤 때마다 LAN이 열립니다. 접속 주소는 CLI 출력의 첫 줄에 나옵니다(예: http://192.168.1.42:8888). 여기까지가 편한 쪽이고, 위험은 세 가지입니다.

첫째, LAN 통신은 암호화되지 않은 HTTP라서 같은 네트워크 구간의 누구나 읽을 수 있습니다. 내가 통제하지 않는 네트워크라면 HTTPS인 Cloudflare 주소를 쓰라는 것이 문서의 권고입니다. 둘째, 서버 도구는 내 사용자 권한으로 실행되므로 키를 가진 사람은 내 컴퓨터에서 코드를 돌릴 수 있습니다. 노출할 때는 --disable-tools를 직접 적어 두면 기본값이 어느 쪽이든 결과가 같고, 키는 비밀번호처럼 다뤄야 합니다. 셋째, --cloudflare와 -H 0.0.0.0를 함께 쓰면 내부 포트와 공개 주소가 동시에 열려 문서가 가장 덜 사적인 모드라고 부릅니다. --secure는 열 때 새 관리자 비밀번호를 터미널에서 묻고, 취소하면 자동 생성 비밀번호로 열리지 않고 실행이 중단됩니다.

넓은 주소(0.0.0.0)로 열면 Unsloth가 인터넷에서 그 포트가 닿는지 점검하려고 외부 점검 사이트인 ifconfig.me와 check-host.net에 접속합니다. 이 접속도 싫다면 환경 변수 UNSLOTH_STUDIO_DISABLE_PUBLIC_CHECK=1로 끌 수 있습니다. 직접 구성한 리버스 프록시 뒤에서 실제 클라이언트 IP가 필요할 때만 UNSLOTH_STUDIO_TRUST_FORWARDED=1로 X-Forwarded-For를 신뢰하게 합니다.

접속이 안 될 때의 점검 순서는 이렇습니다. 두 기기가 같은 네트워크인지 보고, 손님용 Wi-Fi·AP 격리·VPN이 접속을 막는 경우가 흔하니 이를 의심하고, 컴퓨터 방화벽이 그 포트의 들어오는 연결을 허용하는지 확인합니다. 공유기가 주는 LAN 주소는 바뀔 수 있으므로 고정 IP나 DHCP 예약을 잡아 두면 주소가 흔들리지 않습니다. 앱 안의 Start 버튼이 회색이면 카드 아래 메시지가 막힌 이유를 알려 줍니다. Unsloth Studio is already running on port 8888 메시지가 나오면 unsloth studio stop으로 멈추거나 --port를 바꿉니다. 다 쓰고 나면 LAN access 카드에서 Stop을 누르거나 unsloth studio stop으로 멈춥니다. 다만 Stop은 자동 시작 설정을 바꾸지 않으므로, 다음 실행 때 다시 열리지 않게 하려면 Start automatically 토글을 따로 꺼야 합니다. LAN 설정을 바꾸는 HTTP 엔드포인트 네 개(상태 조회, 시작, 정지, 자동 시작)는 UI 세션만 받고 API 키는 거부하므로, 키만 가진 쪽이 포트를 열 수는 없습니다.

#Unsloth#로컬 LLM#미세 조정#Claude Code#GGUF#오픈소스