DeepSeek Harness(명령줄 도구명 dsh)는 개발자가 AI 에이전트를 만들고 운영할 수 있도록 설계된 오픈소스 에이전트 런타임이다. MIT 라이선스로 공개됐으며 현재는 개발자 프리뷰 단계다. 새로운 기반 모델이나 완성형 에이전트 제품을 내놓은 것이 아니라, 에이전트를 이루는 각 요소를 선택해 조립하는 실행 환경에 가깝다. 제공된 보도와 자료 기준 v0.1 출시는 2026년 9월이 아니라 2026년 8월 13일이다.
1
2
핵심은 ‘특권 코어가 없다’는 설계
Harness의 표어인 ‘everything is a plugin(모든 것은 플러그인)’은 단순한 비유가 아니다. 모델 어댑터, 도구, 스킬, 세션, 샌드박스, 스토리지, 스케줄링, 에이전트 루프, UI까지 모두 설정을 통해 교체하거나 다시 조합할 수 있는 플러그인으로 취급한다. 기존 코어를 직접 수정하는 대신, 기존 구성요소 옆에 새 플러그인을 마운트해 런타임을 확장하는 방식이다.
2
21
이 구조는 특정 모델 제공업체로 바꾸고 싶을 때, 사용 가능한 도구를 최소화할 때, 별도의 승인 정책을 적용할 때, 또는 독립적인 실행 환경을 써야 할 때 유용하다. 장기적으로 유지해야 할 포크를 만들기보다 런타임 구성으로 선택 사항을 표현할 수 있기 때문이다.
기반 프레임워크 Cordis는 무엇을 하나
Harness 아래에는 내장(vendored) 플러그인 프레임워크인 Cordis가 있다. 플러그인은 공유 컨텍스트에 서비스, 타입이 지정된 이벤트, 되돌릴 수 있는 효과를 추가한다. 플러그인이 언로드되면 그 플러그인이 등록한 항목도 함께 되돌릴 수 있다.
21
22
Cordis는 의존성을 인식하는 조합도 지원한다. 필요한 서비스에 연결된 콜백은 필수 서비스가 바뀌면 언로드된 뒤 다시 실행되며, ctx.plugin은 선언된 스키마로 설정값을 검증한 후 플러그인을 불러온다.
19
확장 기능 개발자는 비교적 명확한 접점을 활용할 수 있다. 예를 들어 도구 플러그인은 ctx.tools에 등록할 수 있고, 실행 직전 정책 훅은 타입이 지정된 허용·거부 결정을 반환할 수 있다. 이 같은 훅 지점은 권한 관리, 샌드박스, 계획 모드 정책에 활용될 수 있다.
17
기본 제공되는 4가지 런타임 모드
Harness는 개발 작업에 맞춰 출발점으로 삼을 수 있는 4가지 프리셋을 제공한다.
2
- Standard: 코딩 에이전트용 전체 워크플로와 도구 세트를 제공한다.
- Code: Code Mode SDK를 통해 도구를 노출한다. 모델이 생성한 TypeScript가 여러 단계의 작업을 조율하는 용도다.
- Minimal: 지속형 셸과
str_replace_editor를 제공한다. 제약된 환경이나 벤치마킹에 적합하다.
- Creator: 새 프리셋을 만드는 개발자를 위해 런타임 검사와 메모리 내 플러그인 실험 기능을 더한다.
이 모드들은 고정된 제품 등급이 아니라 초기 구성이다. 요구 사항이 달라지면 플러그인 구조를 통해 기능을 교체하거나 추가하는 것이 전제다.
2
21
설치와 첫 실행: npm CLI 또는 소스 코드
Harness는 @deepseek-ai/dsh npm 패키지와 CLI로 배포된다. 문서에 제시된 빠른 시작 명령은 다음과 같다.
npx @deepseek-ai/dsh web
소스에서 실행하거나 코드베이스를 직접 다루려는 개발자는 저장소를 복제해 사용할 수도 있다.
1
30
웹 UI에서는 먼저 Settings → Models에서 모델 자격 증명을 설정한 뒤, 작업을 구성하기 전에 워크스페이스를 선택한다. dsh 프로세스는 명령을 실행한 디렉터리를 기본 파일시스템 위치로 사용하지만, 새 UI에는 워크스페이스가 자동 선택되어 있지 않으므로 직접 추가해야 한다.
25
관측성은 세션 모델의 일부다
Harness는 모델이 본 내용을 추가 전용(append-only) 세션 로그에 기록한다. 시스템 프롬프트, 추론, 도구 호출과 결과, 하위 에이전트 스케줄링, 컨텍스트 주입이 여기에 포함된다. Trajectory 보기에서는 출처별로 해당 기록을 살펴볼 수 있으며, 재개(resume), 분기(fork), 검색(search), 재생(replay)은 모두 같은 이벤트 스트림을 사용한다.
2
따라서 로그는 단순한 사후 디버깅 자료에 그치지 않는다. 특정 실행을 분석하고, 이전 분기로 돌아가며, 에이전트의 동작에 영향을 준 런타임 이벤트 순서를 재현하는 운영 기록이 된다.
개발자 프리뷰라면 호환성 관리가 필요하다
Harness는 명시적으로 개발자 프리뷰로 분류된다. 따라서 플러그인과 API가 장기적으로 안정적인 호환성을 보장한다고 가정해서는 안 된다.
2
6
실무적으로는 사용 버전을 고정하고, 릴리스 변경 사항을 검토하며, 격리된 프로필 또는 워크스페이스에서 업그레이드를 시험한 뒤 대표 세션을 재생해 보는 접근이 합리적이다. 이는 프리뷰 상태에 따른 위험 관리 권고이며, 모든 업그레이드가 하위 호환되지 않는다는 문서상 보장은 아니다.
플러그인은 두 단계에서 검증하는 편이 좋다.
- 플러그인 자체 검증: 설정 스키마, 필요 서비스, 실패 시 동작, 도구 정책 로직을 확인한다.
- 실제 조합 환경 검증: 실제 모델 어댑터, 도구, 샌드박스, 권한, 세션 저장소 및 함께 동작할 다른 플러그인과 결합해 테스트한다.
Harness 설정은 이 과정을 돕도록 설계됐다. cordis.yml의 각 항목에는 config 블록을 둘 수 있고, 플러그인이 공개한 스키마는 apply 함수가 실행되기 전에 검증된다. 설정이 잘못되면 플러그인이 반쯤 설정된 상태로 시작하는 대신 로드 자체가 실패한다.
27
28 생성되는 설정 카탈로그는 pnpm run verify-config-catalog으로 검증한다.
18
배포 측면에서는 확장을 설치 가능한 번들로 패키징한 후 dsh plugin add로 프로필에 추가하는 방식을 문서가 지원한다. 번들과 설정을 명시적으로 관리하면 조합된 런타임의 재현, 감사, 테스트, 업그레이드가 한층 수월해진다.
24
정리
DeepSeek Harness는 에이전트 개발자를 위한 인프라로 이해하는 것이 가장 정확하다. 모델 연결, 도구, 정책, 실행 환경, 루프, 상태, 인터페이스를 고정된 제품 기능이 아니라 조합 가능한 선택지로 다룬다. Cordis가 플러그인 생명주기를 맡고, 런타임 모드는 바로 쓸 수 있는 기본 구성을 제공하며, 추가 전용 세션 로그는 상세한 실행 기록을 남긴다. 높은 유연성이 장점이지만, 개발자 프리뷰인 만큼 신중한 테스트와 업그레이드 절차가 필수다.
2
21