DeepSeek Harness (dsh) 설치 방법: npx 원라이너, 소스 빌드, 헤드리스 및 플러그인

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

Deep​Seek Harness가 무엇인지 — 그리고 무엇이 아닌지

수석 연구원 Chen Deli가 확인한 Deep​Seek의 내부 공식은 모델 + 하네스 = 에이전트입니다. 모델은 두뇌이며, 하네스는 그것을 실제로 작업을 수행하는 무언가로 만들어 주는 모든 것입니다: 컨텍스트 및 메모리 관리, 도구 호출, 작업 계획, 파일 읽기와 쓰기, 터미널 실행, 오류 피드백, 그리고 작업 완료 시점 판단까지. Deep​Seek Harness는 바로 그 계층이며, DeepSeek V4 Pro 0813 빌드가 Deep​Seek API에 출시된 바로 그날인 2026년 8월 13일에 MIT 라이선스로 오픈소스 공개되었습니다.

설치 경험을 결정짓는 두 가지 사실이 있습니다. 첫째, 아키텍처는 '모든 것이 플러그인'이라는 원칙에 따라, TypeScript 플러그인 컨테이너인 Cordis를 기반으로 구축됩니다. 따라서 설치하는 것은 작은 코어와 모델 어댑터, 도구, 세션, UI를 제공하는 플러그인 세트입니다. 둘째, 현재 npm에 게시된 버전은 0.1.0-rc.6인데, 이는 프로젝트 자체가 개발자 프리뷰로 표시한 릴리스 후보입니다. README는 대문자로 이렇게 경고합니다: 호환성을 깨뜨리는 변경이 곧 옵니다. 인기는 실재합니다 — 첫 12시간 만에 GitHub 스타 50,000개, 약 42시간 만에 100,000개, 그리고 중국 기술 언론에 따르면 8월 16일까지 120,000개를 돌파했습니다 — 하지만 스타 수는 관심의 척도일 뿐 안정성의 척도는 아닙니다. 설치 계획도 프리뷰를 계획하듯 세우세요: 시도하기는 빠르게, 버리기는 부담 없이.

시작하기 전에: 실제 시스템 요구 사항

유일한 필수 요구 사항은 Node.js입니다. 프로젝트의 대상 엔진 범위는 ^22.19.0 || >=24.0.0 — 즉, Node 22.19 이상 또는 Node 24.x 버전입니다. 자신의 버전은 node --version으로 확인하세요. 이전 버전의 Node를 사용 중이라면 npx 설치가 실패하거나 오작동하며, 문제를 원활하게 처리하지 못합니다.

다른 모든 것은 모델 우선 집단이 가정하는 것보다 가볍다:

• 모델 API 키.dsh는 실제 모델을 실행합니다. Deep​Seek API 또는 설정한 Open​AI 호환 제공업체의 키가 필요합니다. 첫 실행 후 웹 UI에서 추가할 수 있습니다.

• pnpm — 소스에서 빌드할 때만 필요합니다. 다음 명령어로 한 번 설치하세요: npm install -g pnpm.

• ~1GB의 여유 디스크는npm 패키지, 작업 공간, 세션 로그, 그리고 로컬 모델이 필요로 하는 모든 것(dsh 자체는 가중치를 실행하지 않음)을 위한 것입니다.

• OS: npm 방식은 Windows, macOS, Linux에서 작동합니다. Python SDK는 지원 범위가 더 좁습니다(Linux x64/arm64, macOS 14+ arm64 — 네이티브 Windows 지원 없음). 아래에서 자세히 다룹니다.

당신은 전혀 GPU를 필요로 하지 않습니다. 하네스는 단지 조정만 할 뿐이며, 모델은 API를 통해 원격으로 실행됩니다.

방법 1 — npx 원라이너 (거의 모든 사용자에게 권장됨)

공식 퀵 스타트는 명령어 하나이며, 정말로 명령어 하나입니다:

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

최초 실행에는 정확히 두 가지 설정 단계가 있습니다:

• 모델 키를 추가하세요. 설정 → 모델 → API 키를 입력하세요. 이 키는 $DSH_HOME/.credentials.yaml에 저장되며 이후 평문으로 표시되지 않습니다. 기본 설치에서 DSH_HOME의 기본값은 ~/.dsh입니다.

• 작업 공간을 선택하세요. dsh가 작업할 수 있는 프로젝트 디렉터리를 추가하세요. 두 단계가 모두 완료될 때까지 입력은 잠긴 상태로 유지됩니다.

그런 다음 첫 번째 작업을 보내세요. 좋은 스모크 테스트는 "이 저장소를 요약하고 주요 패키지를 식별하세요."입니다. 요약이 돌아오고 실행 추적에 도구 호출이 표시되면 설치가 제대로 작동하는 것입니다.

방법 2 — 소스에서 빌드

저장소에서 실행하는 것을 선호하시나요? 공식 경로는 다음과 같습니다:

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh 웹

이 작업에는 pnpm이 필요합니다 (기여자들은 pnpm 11.7.0을 고정합니다). 최신 main을 출시된 릴리스 후보 대신 실행하려는 경우, 하네스를 읽거나 수정할 계획이 있거나, 저장소의 apps/cli/config/agent-presets/ 디렉터리에서 사용자 정의 프리셋을 빌드하려는 경우에는 소스 빌드를 선택하세요. 다른 모든 사람들에게는 npx 방식이 절차가 더 간단한 동일한 소프트웨어입니다 — 소스 빌드가 npm 패키지에 없는 기능을 제공하지 않습니다.

세 가지 프로필: web, headless, tui

dsh는 세 가지 실행 프로필로 제공되며, 어떤 프로필을 사용할지는 작업이 이루어지는 위치에 따라 달라집니다:

• web (기본값) — 포트 3080에서의 전체 브라우저 UI입니다. 이것은 npx @deepseek-ai/dsh web이 시작하는 것이며, 대부분의 사람들이 가장 먼저 설치하는 프로필입니다.

• headless — 한 가지 작업만 수행하고 종료합니다. dsh --profile headless "run the test suite and report failures" 명령은 세션을 시작하고, 작업을 실행하며, 결과를 기록한 후 종료합니다. headless 런타임은 명시적으로 단일 작업 프로세스입니다. 실행 도중에 후속 작업을 주입할 수 없으며, 수정은 동일한 작업 공간에서의 새 실행으로 이루어집니다. 이것이 스크립트와 CI에 연결할 프로파일입니다.

• tui — 키보드 기반 세션을 위한 터미널 UI: dsh --profile tui.

세 가지 모두 동일한 설정을 공유합니다 (~/.dsh/profiles/<name>/) 그리고 동일한 플러그인 시스템을 사용하므로, 웹 UI에서 헤드리스로 작업을 옮기는 것은 재설치가 아니라 명령어 교체입니다.

플러그인 추가

플러그인 관리는 일급 CLI 명령어로서, 제자리에서 편집하는 방식이 아닙니다:

npx @deepseek-ai/dsh plugin --profile web add <source>

소스는 npm 패키지 이름, GitHub 저장소(github:user/repo), tarball 또는 로컬 폴더일 수 있습니다. 가장 유용한 첫 설치는 플러그인 탐색을 UI로 바꿔 주는 공식 플러그인 마켓입니다:

npx @deepseek-ai/dsh 플러그인 --프로필 웹 dshmarket 추가

그런 다음 웹 서비스를 다시 시작하고 설정 → 플러그인 마켓을 열어 카탈로그에서 찾아보고 원클릭으로 설치하세요. 사람들이 자주 헷갈리는 두 가지 규칙이 있습니다: 플러그인 번들은 프로필 시작 시 마운트되므로, 새로 추가된 플러그인은 dsh web의 재시작이 필요합니다. 그리고 그냥 npm install은 프로필에 플러그인을 등록하지 않습니다 — 반드시 dsh plugin을 사용해야 합니다. 생태계는 아직 젊지만 비어 있지 않습니다: 커뮤니티에서 유지 관리하는 awesome-dsh-plugin 목록에는 이미 UI, 스킬, 도구, 공급자, 알림과 같은 카테고리의 수백 개 플러그인이 등록되어 있습니다.

MCP, 네 가지 프리셋, 그리고 궤적 재생

기본 설치를 넘어서면 세 가지 기능이 중요합니다:

MCP.dsh는 내장된 @deepseek-ai/dsh-mcp-client 플러그인을 통해 Model Context Protocol을 사용합니다. 현재는 UI가 아닌 파일에서 설정합니다: 편집할 파일은 ~/.dsh/profiles/web/cordis.patch.yml (또는 프로젝트 로컬 패치)이며, 각 서버의 전송 방식을 선언합니다 — stdio는 로컬 명령용(예: npx @playwright/mcp@latest)이고, streamable-http는 원격 URL용입니다. 작동은 하지만, 미리보기에서 가장 덜 다듬어진 부분입니다. 가끔 불안정할 수 있고 서버를 켜고 끄는 GUI도 없습니다.

프리셋. dsh는 세션마다 네 가지 에이전트 프리셋 중 하나를 로드하며, 각각은 서로 다른 트레이드오프를 제공합니다:

• Standard — 전체 도구 세트: 파일 편집, 셸, 파일 및 웹 검색, 스킬, 계획 수립, 하위 에이전트, 워크플로우. 일상의 기본.

• PTC (Programmatic Tool Calling) — Standard에 모델이 TypeScript 프로그램을 작성하여 다중 라운드 도구 호출을 조율할 수 있게 해주는 Code Mode SDK가 추가된 형태입니다. 더 강력하며 부작용도 더 많습니다.

• 최소 — 오직 bash와 파일 편집기만, 그 외에는 아무것도 없음. 모델 벤치마킹과 최소 재현을 위해 제작되었으며; DeepSeek V4 Flash API 문서가 자체 에이전트 점수를 공개하면서 언급한 모드는 "Deep​Seek Harness minimal mode"에서 실행되었다.

• Creation — 런타임 플레이그라운드: Cordis 플러그인을 메모리에서 검사하고 로드하며, 실험하고, 작동하는 조합을 새 프리셋으로 확정하세요.

궤적 재생.모든 실행은 추가 전용 세션 로그를 기록합니다. 시스템 프롬프트, 추론, 도구 호출 및 그 결과, 하위 에이전트 스케줄링이 포함됩니다. 궤적 뷰에서는 실행을 소스별로 검사하고, 재개하고, 분기하고, 검색하고, 재생할 수 있습니다. 이것이 에이전트 작업을 위한 디버거입니다. 작업이 실패하면 다시 실행하며 기대하는 대신, 실패한 궤적을 재생하고, 잘못된 단계에서 분기하여 원본을 버리지 않고 수정 사항을 테스트합니다.

Python SDK 옵션

브라우저 대신 Python에서 하네스를 구동하고 싶다면 공식 SDK가 있습니다: pip install deepseek-harness-sdk. 이 SDK는 dsh 런타임을 포함하며(pip wheel이 Node 런타임을 포함하므로 별도의 Node 설치가 필요 없습니다), 사용법은 컨텍스트 매니저입니다: Deep​SeekHarness 인스턴스를 만들고 run("task")를 호출합니다. 표준 환경 변수(예: DEEPSEEK_API_KEY 및 DEEPSEEK_BASE_URL)를 상속하므로 공급자 변경은 설정 변경입니다. 단점: Python 3.10+이며 Linux x64/arm64 및 macOS 14+ arm64만 지원합니다 — Windows용 네이티브 휠이 없어 Windows를 호스트로 사용한다면 정말 큰 단점입니다. Windows에서는 npm 경로를 사용하세요.

유료 모델에 dsh를 지정하기

dsh는 모델 API 키가 필요하며, 의도적으로 공급자 중립적입니다: 설정 → 모델은 Open​AI 호환 base URL을 가진 사용자 지정 공급자를 허용합니다 (settings.yaml에서 api: openai-completions, baseURL, 그리고 models 목록입니다). 기본값은 Deep​Seek 자체 API입니다. 사용자 지정 공급자는 라우팅 게이트웨이가 유용해지는 곳입니다.

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

경계를 분명히 하자면: OrcaRouter는 모델의 dsh 호출을 호스팅합니다. dsh 자체는 호스팅하지 않습니다. dsh는 로컬 에이전트 런타임이며, 여러분은 이를 직접 자신의 머신에서 실행합니다.

이 가이드가 당신에게 맞지 않는 경우 — 프리뷰의 솔직한 문제점

입력할 내용만 알려주는 설치 튜토리얼은 일을 절반만 하는 셈입니다. 오늘 미리보기에서 무엇이 잘못되었는지 여기에 정리했습니다. 새벽 2시에 그걸 발견하지 않도록 말이죠:

• 파괴적 변경은 경고가 아니라 약속입니다. 현재 0.1.0-rc.6 버전입니다. 구성 키, 플러그인 API, 프리셋 형식은 모두 공지 없이 변경될 수 있습니다. 다음을 취급하십시오: ~/.dsh를 버려도 되는 상태로 — 나쁜 업데이트의 대가는 재설치이며, 설치가 한 줄 명령이기 때문에 이 단계에서는 그 정도는 감수할 수 있습니다.

• Deep​Seek 모델을 에이전트로 사용하는 데 dsh가 필요하지 않습니다. 만약 오늘 에이전트 안에서 DeepSeek V4 Flash 또는 DeepSeek V4 Pro를 사용하는 것이 유일한 목표라면, Deep​Seek의 Anthro​pic 호환 엔드포인트는 이미 Claude Code 및 기타 에이전트 도구에서 새 소프트웨어 없이 작동합니다. dsh는 자사 옵션일 뿐 필수 조건이 아닙니다. 자체 하네스를 특별히 원할 때까지 이 설치를 건너뛰세요.

• MCP는 파일 기반으로 구성되어 있으며 때때로 불안정합니다. GUI도 없고, 서버별 시작/중지 토글도 없으며, 실사용 보고서에는 간헐적 장애가 언급됩니다. 워크플로가 MCP 서버에 의존한다면 YAML 디버깅에 시간을 할애하세요.

• 플러그인 신뢰는 보안 결정입니다. 서드파티 플러그인은 하네스의 핵심 프로세스 내에서 실행되며, 설치 시 서명이나 소스 검증이 없습니다. 직접 읽어본 플러그인이나 신뢰하는 출처의 플러그인만 설치하고, 실제 작업에 적용하기 전에 일회용 작업 공간에서 테스트하세요. danger-full-access 샌드박스 프로필은 보이는 모든 파일을 수정할 수 있으므로, 임시 체크아웃에만 사용하세요.

• 미리보기에는 알려진 버그가 있습니다. 중단된 bash 루프는 문서화된 실패 모드이며(중단 후 재시도), 장기 실행 세션의 동작은 아직 안정화 중입니다.

• 비공식 데스크톱 빌드는 함정입니다. 여러 커뮤니티 래퍼가 dsh를 번들된 Node 런타임과 함께 클릭 한 번으로 설치되는 데스크톱 앱으로 패키징합니다. 작동은 하지만, 서명되지 않았고 Deep​Seek가 유지 관리하지 않습니다. 그중 하나를 사용한다면, 파일 시스템 권한을 보유한 도구를 제3자에게 맡기는 셈입니다.

• 프로덕션 안정성이 필요하다면, RC가 아닌 릴리스를 기다리세요. 이 하네스는 강력하지만 아직 검증되지 않았습니다. 프로덕션 에이전트 스택을 위해서는, dsh가 안정적인 태그에 도달할 때까지 성숙하고 실전 검증된 하네스 — 또는 Anthro​pic 호환 엔드포인트 경로 — 가 타당한 선택입니다.

결론

Deep​Seek Harness 설치는 Node 22.19+가 있는 모든 머신에서 정말로 한 줄 명령으로 끝나는 작업입니다: npx @deepseek-ai/dsh web, 모델 키와 워크스페이스를 추가하고 테스트 작업을 보내세요. 소스 빌드는 수정 또는 추적 대상이main일 때만 선택하세요; 스크립트에는 headless를 사용하고, 플러그인 마켓을 일찍 추가하며, MCP는 작업 진행 중인 것으로 취급하세요. 솔직한 경고는 프로젝트가 자체 README에 명시한 것과 동일합니다: 이것은 0.1.0-rc 프리뷰이며 안정 버전으로 가는 중에 무언가를 깨뜨릴 것입니다. Deep​Seek가 에이전트 레이어를 어디로 이끌고 있는지 보고 싶다면 그것은 올바른 절충입니다 — 그리고 그것이 실행하는 모델인 DeepSeek V4 Flash와 DeepSeek V4 Pro는 현재 OrcaRouter를 통해 정가로 이용 가능하며, 설치가 끝난 뒤 하네스에 동력을 공급할 준비가 되어 있습니다.