TLDR DeepSeek Harness (dsh)는 DeepSeek AI의 오픈 소스 에이전트 런타임으로, 2026년 8월 13일 전후 개발자 프리뷰로 MIT 라이선스 하에 공개되었습니다. 이는 “Model + Harness = Agent” 원칙을 따르며, 모든 기능(모델, 도구, 세션, 샌드박스, 루프, UI)이 교체 가능한 Cordis 플러그인으로 구현되어 있습니다.
로컬에서 가장 빠르게 실행하는 방법은 npx @deepseek-ai/dsh web(Node.js ^22.19 또는 ≥24 필요)이며, http://127.0.0.1:3080. 에서 Web UI가 시작됩니다. DeepSeek(또는 OpenAI 호환) API 키와 워크스페이스를 제공하면 됩니다. 소스 빌드, 데스크톱 앱, Docker, Python SDK, 그리고 Ollama 통합도 제공됩니다. 프로덕션급 멀티 모델 접근, 신뢰성, 비용 제어를 위해 하니스 사용 시 CometAPI의 통합 OpenAI 호환 엔드포인트로 요청을 라우팅하는 것을 권장합니다.
Key Takeaways
- DeepSeek Harness는 모델이 아닙니다—파일, 셸, 도구, 세션에 대해 모델이 동작하도록 하는 로컬 런타임/오케스트레이터입니다.
- 공식 원라이너:
npx @deepseek-ai/dsh web→ 포트 3080에서 로컬 웹 UI를 엽니다. - Node.js 요구 사항은 엄격합니다: ^22.19.0 또는 ≥24.x.
- DeepSeek 공식 모델(deepseek-v4-flash, deepseek-v4-pro), 사용자 정의 OpenAI 호환 게이트웨이, 플러그인/Ollama를 통한 로컬 모델을 지원합니다.
- 아키텍처는 완전한 플러그인 기반(Cordis 커널)입니다; 모드에는 Standard, Minimal, Code, Creator가 포함됩니다.
- 빠른 채택: 출시 후 며칠 만에 수만에서 10만+ 이상의 GitHub 스타를 기록.
- 파워 유저 권장: CometAPI(https://www.cometapi.com/)를 커스텀 프로바이더로 페어링하여 500+ 모델 접근, 20–40% 비용 절감, 단일 API 키 사용.
- 항상 격리된 워크스페이스를 사용하세요; 에이전트는 파일을 수정하고 명령을 실행할 수 있습니다.
- 개발자 프리뷰 상태이므로 파괴적 변경이 예상됩니다—프로덕션 유사 실험에는 버전을 고정하세요.
What Is DeepSeek Harness and Why It Matters in 2026
DeepSeek Harness(dsh)는 DeepSeek AI가 개발한 오픈 소스 에이전트 런타임입니다. MIT 라이선스의 개발자 프리뷰로 공개되었으며, 구성 가능성에 중점을 둡니다: 모델 어댑터, 도구, 스킬, 세션, 샌드박스, 스토리지, 에이전트 루프, 스케줄링, UI 등 모든 기능이 구성으로 마운트/언마운트/교체/재구성 가능한 Cordis 플러그인으로 존재합니다. 사실상 패치가 필요한 특권 코어가 없습니다.
핵심 설계 원칙은 다음과 같습니다:
- Agent = Model + Harness.
- 재개, 분기, 검색, 재생을 지원하는 추적 가능한 이벤트 스트림.
- 다중 런타임 모드(표준 풀 툴셋, 코드/오케스트레이션 모드, 벤치마크용 최소 모드, 크리에이터/실험 모드).
- 인터랙티브 사용을 위한 로컬 우선 Web UI와 자동화를 위한 헤드리스/SDK 옵션.
공식 리소스:
- GitHub: https://github.com/deepseek-ai/deepseek-harness
- 제품/랜딩: https://www.deepseek.com/harness/en/ (중국어 버전 포함)
- 설치 가이드 페이지와 커뮤니티 미러가 동일한 핵심 명령을 안내합니다.
중요 용어 주의: “로컬 배포”는 두 가지 의미를 가질 수 있습니다. 본 가이드에서 다루는 DeepSeek Harness는 컴퓨터에서 로컬로 실행되지만, 표준
deepseek-harness프로젝트는 DeepSeek V4-Pro 또는 V4-Flash에 API를 통해 연결합니다. 즉, 하니스, 구성, 세션, 검증, 클라이언트 로직은 로컬일 수 있지만, 모델 추론은 일반적으로 DeepSeek의 API에서 수행됩니다. 모델 가중치를 보유한 자체 GPU로 진정한 오프라인 추론이 필요하다면, 이는 다른 배포 아키텍처입니다.
Prerequisites and System Requirements
설치 전에 다음을 확인하세요:
- 운영 체제: Windows 10+, macOS 10.15+, 주류 Linux(x64 또는 arm64). Python SDK에는 추가 제약( Linux x64/arm64 또는 macOS 14+ arm64)이 있습니다.
- Node.js: 메인 Web UI 경로에 필요. 대상 범위는 ^22.19.0 || ≥24.0.0. node --version으로 확인하세요. 이 범위를 벗어난 홀수 중간 버전은 지원되지 않습니다.
- 패키지 관리자: npm/npx(Node에 포함). 소스 빌드는 pnpm이 필요합니다(npm install -g pnpm으로 설치).
- Git: 소스 클로닝에 필요.
- Python(선택): 공식 Python SDK용 3.10+.
- API 키/엔드포인트: platform.deepseek.com의 DeepSeek API 키, 또는 OpenAI 호환 엔드포인트 + 키 + 모델 이름.
- 하드웨어: 하니스 자체에는 GPU가 필요하지 않습니다—모델 추론은 원격(또는 구성한 로컬 프로바이더)에서 수행됩니다. Web UI 및 오케스트레이션에는 일반 노트북 리소스로 충분합니다.
- 네트워크: 첫 실행 시 패키지 가져오기에 필요; 이후에는 모델 API 호출만 있으면 UI가 동작합니다.
- 워크스페이스: 격리된 디렉터리를 준비하세요. 에이전트는 구성된 워크스페이스 내에서 읽기/쓰기/명령 실행이 가능합니다—안전장치 없이 프로덕션 또는 개인 데이터에 지정하지 마세요.
요구 사항 출처: 공식 README와 출시 직후 게시된 여러 독립 설치 가이드.
Method 1: Official One-Liner with npx (Recommended for Most Users)
가장 빠르고 공식적으로 권장되는 경로입니다.
- Node.js가 버전 요구 사항을 충족하는지 확인합니다.
- 터미널에서 다음을 실행합니다:
Bash
npx @deepseek-ai/dsh web
- 패키지가 다운로드(또는 캐시 사용)되고 Web UI 프로파일이 시작되며, 기본적으로 http://127.0.0.1:3080. 의 리스닝 주소가 출력됩니다.
- 브라우저에서 해당 URL을 엽니다. 개발자 프리뷰 공지가 표시되면 승인합니다.
- 첫 사용 시 모델 프로바이더(Settings → Models)를 구성하여 API 키를 붙여넣고 deepseek-v4-flash 또는 deepseek-v4-pro 같은 모델을 선택합니다.
- 워크스페이스 디렉터리를 선택하거나 생성합니다.
- 작업을 시작합니다.
다른 포트를 사용하려면:
Bash
npx @deepseek-ai/dsh web --port 8080
커뮤니티 사이트에서 Node 존재까지 보장하는 Platform-specific one-liners 도 제공됩니다(Windows의 PowerShell 및 winget, macOS의 Homebrew, Debian/Ubuntu의 NodeSource 등).
장점: npm 캐시 외에 영구 설치 발자국 없음; 항상 최신 게시 버전을 가져옴; 온보딩이 가장 간단. 단점: 초기 패키지에 네트워크 의존; 심층 소스 점검 또는 커스텀 빌드에는 덜 편리.
Method 2: Install and Run from Source
Cordis 플러그인을 읽고, 커밋 고정, 커스텀 프리셋 개발, 기여가 필요한 경우 사용하세요.
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
동일한 Web UI가 기본 포트에서 표시됩니다. 개발자 프리뷰 빌드는 커밋 간 깨질 수 있으므로 실험적 경로로 취급하세요.
Method 3: Desktop Applications (Zero Node Setup)
커뮤니티 및 서드파티 데스크톱 래퍼는 사용자가 Node/pnpm 설치 없이도 런타임을 사용할 수 있도록 패키징합니다:
- Tauri 기반 경량 클라이언트는 번들 Node 런타임을 부트스트랩하고 실행 시 최신 업스트림 하니스를 동기화합니다. 127.0.0.1:3080에서 실행되며 데이터는 로컬에 유지되고 dsh 명령을 등록합니다.
- Electron 기반 패키징은 종속성을 고정하여 포함합니다.
각 GitHub Releases 페이지에서 인스톨러를 다운로드하세요(“deepseek-harness-desktop” 검색). 첫 실행 시 코어 컴포넌트(수백 MB)를 다운로드합니다. 비개발자에게 편리하지만 공식 DeepSeek 제품이 아니므로 저장소와 SHA 체크섬을 검토하세요.
Method 4: Docker / Container Deployment
Web UI를 컨테이너 내에서 실행하기 위한 커뮤니티 Docker 이미지와 compose 파일이 있으며, nginx를 통한 HTTPS 종료 및 임의의 OpenAI 호환 게이트웨이 지원을 제공하는 경우가 많습니다. 일반적인 흐름:
Bash
git clone <docker-repo>
cd <docker-repo>
cp .env.example .env # set API key / public host
docker compose up -d --build
LAN 접근, 서버, 호스트에 Node를 두고 싶지 않은 환경에 유용합니다. 일부 설정은 비-DeepSeek 프로바이더용 settings.yaml 커스텀을 지원합니다.
Method 5: Python SDK for Programmatic / Headless Use
무인 에이전트나 Python 파이프라인 통합용:
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk
환경 변수를 설정:
Bash
export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash
그런 다음 체크인된 예제를 실행하거나, 격리된 워크스페이스 및 세션 디렉터리를 대상으로 DeepSeekHarness 클래스를 사용해 자체 코드를 작성하세요. SDK는 자체 런타임을 번들하며 시스템 Node.js를 요구하지 않습니다.
Method 6: Ollama Integration
Ollama는 편의 런처를 제공합니다:
Bash
ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud
Ollama는 필요 시 패키지를 설치할 수 있으며, 실행 설정을 별도로 저장합니다. 웹 검색과 도구 지원은 선택한 모델과 Ollama 클라우드 접근성에 따라 달라집니다.
Configuring Models and Providers (Including CometAPI)
Web UI에서 Settings → Models로 이동합니다.
- 공식 DeepSeek용: platform.deepseek.com에서 키를 붙여넣습니다. 일반 모델은 deepseek-v4-flash와 deepseek-v4-pro입니다.
- 카탈로그 프로바이더(Anthropic, OpenAI 등)용: “Add provider” 플로우를 사용합니다.
- 커스텀/자가 호스팅/집계 엔드포인트용: “Add a custom provider”를 선택합니다. 영구 Provider ID, base URL, 프로토콜(일반적으로 openai-completions), API 키 환경 참조 또는 값, 최소 하나의 모델 ID를 제공합니다.
CometAPI recommendation(많은 프로덕션 유사 워크플로에 강력 권장) CometAPI는 단일 OpenAI 호환 엔드포인트( https://api.cometapi.com/v1. )를 통해 500+ 모델(DeepSeek 변형, GPT, Claude, Gemini, Grok 등 다수)을 제공하는 통합 AI 인프라 플랫폼입니다.
DeepSeek Harness와 함께 사용할 때의 이점:
- 여러 프로바이더 자격 증명 대신 단 하나의 API 키.
- 경쟁력 있는 가격(많은 모델에서 벤더 직결 대비 20–40% 절감 보고).
- 높은 가용성(99.9% SLA 목표), 낮은 중앙값 지연, 사용량 기반 과금.
- 모델 ID만 변경하여 하니스 구성 변경 없이 A/B 테스트나 비용 최적화를 위한 손쉬운 모델 전환.
- 드롭인 호환성: base_url과 키만 변경하면 기존 OpenAI SDK 패턴이 동작.
하니스의 커스텀 프로바이더 폼에서:
- Base URL:
https://api.cometapi.com/v1 - Protocol: openai-completions(또는 동등 지원 옵션)
- API key: CometAPI 키
- Model ID: CometAPI 모델 카탈로그의 지원 모델 문자열
이 조합은 강력한 로컬 에이전트 런타임을 유지하면서 유연하고 비용 효율적인 멀티 벤더 모델 접근을 제공합니다. 신규 사용자는 일반적으로 무료 테스트 크레딧을 받습니다. 문서: https://apidoc.cometapi.com/.
키는 쓰기 전용으로 저장됩니다(예: $DSH_HOME/.credentials.yaml); UI에는 마스킹된 설명만 표시됩니다.
Troubleshooting DeepSeek Harness
DEEPSEEK_API_KEY not found
다음을 확인하세요:
echo $DEEPSEEK_API_KEY
Windows:
echo $env:DEEPSEEK_API_KEY
비었다면 다시 구성하세요.
400 reasoning_content 오류
이는 대체로 추론 라이프사이클 처리의 오류를 가리킵니다.
애플리케이션이 다중 턴 thinking/tool-call 요청에서 관련 어시스턴트 추론 정보를 유지하는지 확인하세요.
이것은 하니스가 특히 처리하도록 설계된 핵심 이슈 중 하나입니다.
Context-length 오류
다음을 확인하세요:
input tokens + max_tokens
문서화된 하드 상한은:
1,048,576 tokens
입력 컨텍스트 또는 요청된 완료 길이 중 하나를 줄이세요.
스트리밍 중 도구 호출이 손상됨
스트림 청크가 도구 순서로 도착한다고 가정하지 마세요.
하니스 계약에서 권장하듯 tool_call.index로 도구 호출 델타를 집계하세요.
요청 비용이 예상보다 높음
다음을 확인하세요:
- thinking mode
- output length
- cache-hit rate
- prompt prefix stability
- model choice
- current API pricing
간단한 개선은 자주 사용하는 작업을 Pro에서 Flash로 이동하는 것입니다.
Comparison of Installation and Deployment Methods
| Method | Ease of Use | Node Required | Best For | Persistence / Control | Typical Port / Access | Notes |
|---|---|---|---|---|---|---|
| npx one-liner | Highest | Yes | Quick trials, most users | Ephemeral (cache only) | 3080 (configurable) | Official recommended |
| Source (pnpm) | Medium | Yes | Development, plugins, pinning | Full source control | 3080 | Needs pnpm + build |
| Desktop (Tauri/Electron) | High | No (bundled) | Non-technical users | Local profiles & auto-update | 3080 (internal) | Community packages |
| Docker | Medium | No (container) | Servers, LAN, HTTPS | Container volumes | Custom / 443 | Community images |
| Python SDK | Medium | No (bundled) | Headless, automation, pipelines | Programmatic sessions | N/A (no UI by default) | Official SDK |
| Ollama launch | High | Optional | Local-model experiments | Ollama settings | 3080 | Integrates with Ollama |
데이터는 공식 문서와 출시 직후 가이드(2026년 8월)에서 종합되었습니다.
Conclusion and Next Steps
DeepSeek Harness는 npx 원라이너를 통해 거의 마찰 없이 로컬 머신에 깔끔하게 설계된 완전 플러그인 기반 에이전트 런타임을 제공합니다. 통합 플랫폼인 CometAPI를 통한 유연한 모델 라우팅과 결합하면, 최신 에이전틱 코딩 워크플로의 강력함과 비용, 모델 선택, 데이터 로컬리티에 대한 실용적 제어를 동시에 얻을 수 있습니다.
지금 시작하세요:
npx @deepseek-ai/dsh web
DeepSeek 또는 CometAPI 키를 구성하고, 안전한 워크스페이스를 지정한 뒤 Standard 모드를 탐색하세요. 그런 다음 벤치마크용 Minimal 모드, 비용 최적화를 위한 커스텀 프로바이더, 자동화를 위한 Python SDK를 실험해 보세요.
최신 공식 지침은 항상 GitHub 저장소와 문서를 우선하세요. 하니스를 실행하면서 멀티 모델 신뢰성과 가격 이점을 얻으려면 CometAPI와 https://apidoc.cometapi.com/. 문서를 확인하세요.


