DSH Desktop 소개
코딩 에이전트를 처음 붙잡을 때 시간이 가장 많이 드는 구간은 에이전트 자체가 아니라 그 앞의 준비 과정입니다. DeepSeek AI가 공개한 DeepSeek Harness (
DeepSeek Harness: 에이전트 루프까지 설정으로 교체하는 플러그인 구조의 코딩 에이전트)는 명령줄과 웹 UI 양쪽에서 모델과 도구, 세션, 워크플로를 자기 런타임으로 조합할 수 있는 에이전트 하네스(harness)지만, 처음 쓰는 사람에게는 Node.js 설치와 프로필(profile) 준비, 의존성 설치, 포트와 프로세스 수명 관리가 그대로 사용 경험의 일부로 남습니다. 에이전트의 성능을 평가해 보려던 사람이 런타임 환경 설정 단계에서 멈추는 일이 그래서 생깁니다.
Anywhere Labs가 공개한 DSH Desktop은 그 준비 과정을 설치 프로그램 하나로 옮긴 macOS·윈도우 데스크톱 앱입니다. 눈에 띄는 선택은 구현 방식 쪽에 있습니다. 이 프로젝트는 업스트림 소스를 포크하거나 고쳐서 전용 셸을 만들지 않고, 창과 트레이, 터미널, 업데이트, 작업 프로필을 담당하는 데스크톱 셸 자체를 하나의 DSH 플러그인으로 만들어 공식 Harness와 같은 런타임에 얹었습니다. 공식 Harness는 고정된 버전 그대로 실행되고, 데스크톱 기능은 공식 플러그인 메커니즘을 통해 그 위에 합성됩니다.
설치 프로그램에는 Electron과 Node 런타임, 고정된 DSH 의존성이 함께 들어갑니다. 앱은 창과 트레이, 단일 인스턴스 잠금, 종료, 로컬 서비스 수명을 직접 관리하고, 사용자는 공식 DSH의 프로필과 플러그인, 세션, 웹 UI를 그대로 씁니다. 에이전트와 모델, 도구, 세션, 웹 클라이언트의 동작은 여전히 업스트림 Harness가 결정합니다.
DSH Desktop과 공식 Harness 직접 실행의 차이
DSH Desktop은 Harness를 대체하는 도구가 아니라 실행 방식을 바꾸는 도구입니다. 두 방식이 어느 지점에서 갈라지는지 정리하면 다음과 같습니다.
| 항목 | 공식 Harness 직접 실행 | DSH Desktop |
|---|---|---|
| 설치 준비물 | Node.js, 의존성 설치, 프로필 준비 | 설치 프로그램 하나 (Electron·Node·고정 의존성 포함) |
| 실행과 종료 | 명령줄에서 프로세스와 포트를 직접 관리 | 앱이 창, 트레이, 단일 인스턴스 잠금, 로컬 서비스 수명을 관리 |
| 프로필 전환 | 명령줄에서 프로필 지정 | 트레이 메뉴에서 선택하고 순차 재시작으로 반영 |
| 에이전트 동작 | 업스트림 Harness | 업스트림 Harness (고정 버전 그대로) |
| 플러그인 | 공식 플러그인 체계 | 같은 공식 플러그인 체계, 데스크톱 셸도 그중 하나 |
| 지원 플랫폼 | 업스트림 기준 | macOS와 윈도우, 리눅스는 호환 모드만 |
포크하지 않기로 한 결정은 문서에도 이유가 적혀 있습니다. 업스트림 동작을 교체 가능한 상태로 두고, 데스크톱 기능은 Electron 내부를 짐작하게 하는 대신 명시적인 Host 서비스로 노출하며, 업스트림과 데스크톱과 서드파티 각각의 책임 경계를 분명히 하기 위해서입니다. 실제로 서드파티 플러그인이 쓸 수 있는 공개 계약은 dsh-plugin-desktop/profile-service 와 dsh-plugin-desktop/pnpm 둘뿐이고, 창이나 트레이, 설치 프로그램 같은 내부 구현은 직접 제어할 수 없습니다.
같은 팀은 플러그인 생태계 선언문에서 이 구조를 생태계 차원의 제안으로도 내놓았습니다. 플러그인이 늘어날수록 서로의 내부를 가정하거나 덮어쓰는 방식은 충돌을 만들기 때문에, 공식 슬롯과 서비스, 패치를 통해 조합하고 의존하는 서비스를 명시적으로 선언하며 업그레이드에서 하위 호환을 지키자는 세 가지 원칙을 제시합니다. 데스크톱 셸을 특권 없는 일반 플러그인으로 만든 것이 그 원칙의 첫 사례라는 것이 이들의 설명입니다.
DSH Desktop은 누구에게 유용한가
DeepSeek Harness를 처음 써보려는 macOS·윈도우 사용자, 그리고 작업용 컴퓨터의 Node.js 환경을 건드리고 싶지 않은 사용자에게 가장 잘 맞습니다. 설치 프로그램이 런타임을 통째로 들고 오고, 터미널용 대체 실행 파일(shim)도 새 터미널 프로세스에만 적용되므로 시스템 PATH나 셸 설정 파일은 그대로 남습니다. 반대로 이미 명령줄에서 Harness를 잘 쓰고 있거나 핵심 기능에 기여할 계획이라면 얻는 것이 크지 않고, 저장소도 그런 경우에는 공식 저장소를 먼저 보라고 안내합니다.
시점 판단도 필요합니다. 이 저장소가 고정해 둔 업스트림은 0.1.0-rc.5 소스와 0.1.0-rc.6 런타임 패키지로, 아직 정식 릴리스 전 단계입니다. 리눅스에서는 호환 모드만 제공되고, 플러그인 마켓플레이스와 모바일 원격 제어, Channels는 계획으로만 표시되어 현재 설치 프로그램에 들어 있지 않습니다. 지금 당장 그 기능들이 필요하다면 기다리는 편이 낫습니다.
DSH Desktop의 아키텍처
DSH Desktop은 얇은 Electron 호스트입니다. Electron 메인 프로세스에서 공식 DSH Host를 띄우고, Host는 평소의 웹 UI를 루프백 HTTP와 WebSocket으로 노출합니다. 렌더러용 IPC 플러그인 체계를 새로 만들지 않고, 페이지에 Electron API를 그대로 열어 주지도 않습니다.
사용자
└─ Electron 메인 프로세스 (창 / 트레이)
└─ 프로필 런처
├─ Host (Cordis 세대)
│ ├─ 루프백 HTTP + WebSocket ──→ 샌드박스 웹 렌더러
│ ├─ 업스트림 DSH 서비스
│ ├─ 데스크톱 소유 플러그인
│ └─ 서드파티 플러그인
└─ desktopProfiles + desktopPnpm 서비스 ──→ 서드파티 플러그인
시작 순서에는 합성 순서가 그대로 드러납니다. Electron이 단일 인스턴스 잠금을 얻고 데스크톱이 관리하는 프로필·모드 상태를 읽은 뒤, 런처가 활성 프로필을 준비합니다. 이때 목록을 보여 주려는 목적만으로 프로필을 수정하지는 않습니다. 이어서 Host의 Cordis 루트가 Loader 항목을 마운트하는데, 데스크톱 서비스가 서드파티 항목보다 먼저 등록되어야 서드파티가 그 서비스를 소비할 수 있습니다. dsh-base 와 dsh-web-app, 선택된 프로필의 서드파티 번들이 웹 캐리어를 구성하고 나면 Host가 루프백 포트를 열고 Electron이 같은 출처의 페이지를 띄웁니다. 트레이는 웹 화면이 실제로 로드된 다음에야 만들어지고, 그 시점에 프로필이 마지막 정상 동작 값으로 확정됩니다.
프로필이나 모드를 바꿀 때마다 현재 세대를 정리한 뒤 다음 세대를 시작하므로, 서비스 참조나 창 객체, 서브프로세스 핸들을 세대 사이에 캐시해 두면 안 됩니다. 프로필 이름과 절대 경로는 desktopProfiles.current 에서만 오고 argv나 설정, URL에서 추론하지 않는다는 규칙도 같은 맥락입니다.
DSH Desktop의 주요 기능
화면은 두 가지 모드로 나뉩니다. 호환 모드는 업스트림 웹 클라이언트와 선택한 프로필의 레이아웃·사이드바·대화 구성을 그대로 사용해 일반 Harness에 가장 가까운 모습을 보여 주고, 고급 모드는 같은 업스트림 웹 캐리어를 유지하면서 데스크톱이 소유한 프레임과 레이아웃, Mica·vibrancy 같은 네이티브 재질, 드래그 영역을 더합니다. 모드를 바꾸면 앱이 재시작하며, 실행 중인 렌더러에서 루트 슬롯이나 네이티브 재질을 즉시 교체하는 방식은 쓰지 않습니다.
프로필은 DSH 번들과 의존성, 패치의 조합을 가리킵니다. 트레이의 프로필 메뉴에는 기존 프로필과 함께 지연 생성되는 desktop·web 기본값이 나열됩니다. 프로필을 고르면 순차 재시작이 일어나고, Host와 창과 브라우저 클라이언트가 모두 정상적으로 시작한 다음에야 그 프로필이 마지막 정상 선택으로 기록됩니다. 시작에 실패하면 직전에 동작하던 선택으로 돌아갑니다. 공식 프로필은 보통 같은 DSH 홈을 쓰기 때문에 세션과 설정, 저장소를 옮길 필요가 없고, 패치로 저장 루트를 일부러 바꾼 경우에만 그 프로필의 설정이 우선합니다.
트레이의 터미널 열기 항목은 macOS에서 Terminal을, 윈도우에서 Windows Terminal을 열고 없으면 PowerShell이나 명령 프롬프트로 넘어갑니다. 열린 터미널의 안내문에는 앱 버전과 활성 프로필, 프로필 디렉토리, DSH 홈이 표시됩니다. 데스크톱은 사용자 데이터 디렉토리에 dsh·pnpm·node 의 전용 대체 실행 파일을 만들고 새 터미널 프로세스에만 그 경로를 앞세우므로, 시스템 PATH나 셸 설정 파일은 수정하지 않습니다.
업데이트는 배포판 macOS·윈도우 앱이 백그라운드에서 https://www.dshdesktop.cn/api/desktop/version 을 확인하는 방식입니다. 시작을 막지 않고, 네트워크 오류나 200이 아닌 응답, 잘못된 버전, 서버 버전이 더 최신이 아닌 경우는 조용히 넘어갑니다. 트레이의 수동 확인은 최신 상태일 때도 결과를 보여 주고, 서버 버전이 로컬보다 확실히 높을 때만 다운로드 확인 창을 띄웁니다. 확인 후에는 macOS가 DMG를 열어 사용자가 응용 프로그램 폴더에서 교체하도록 하고, 윈도우는 NSIS 설치 프로그램을 준비한 뒤 종료와 설치 시작 여부를 묻습니다.
DSH Desktop이 의도적으로 하지 않는 것
무엇을 하지 않기로 했는지가 이 프로젝트의 경계를 더 잘 보여 줍니다. 저장소는 다음을 명시적으로 배제합니다.
- 업스트림 웹 UI 재구현: Electron 네이티브 페이지로 다시 만들지 않습니다.
- 호환 모드에서의 레이아웃 개입: 업스트림 레이아웃과 사이드바, 대화 구성을 덮어쓰지 않습니다.
- 별도 데이터베이스: 기록을 따로 복사하지 않고, 공식 프로필은 기본적으로 세션과 설정을 DSH 홈에서 공유합니다.
- 비공개 Electron API 개방: 서드파티 플러그인에 정의되지 않은 사설 API를 주지 않습니다.
- 로드맵의 기성품화: 플러그인 마켓플레이스와 모바일 원격 제어, Channels를 이미 출시된 기능처럼 표시하지 않습니다.
DSH Desktop 설치 및 사용법
일반 사용자는 공식 다운로드 페이지에서 macOS 또는 윈도우 설치 프로그램을 받으면 됩니다. Node.js나 pnpm을 따로 설치할 필요는 없습니다. 첫 실행에서 앱이 기본 프로필을 준비하고 공식 DSH 웹 화면을 로컬에 띄웁니다. 창을 닫으면 숨겨지기만 하므로, 앱과 Host 프로세스를 실제로 멈추려면 트레이의 종료를 써야 합니다.
플러그인은 공식 Harness와 같은 체계를 쓰기 때문에 업스트림 CLI 문법이 그대로 통합니다.
dsh plugin --profile desktop add <plugin>
dsh plugin --profile desktop remove <plugin>
dsh plugin --profile desktop update
트레이에서 연 터미널 안에서는 --profile 없이 쓴 명령이 활성 프로필을 기본값으로 삼습니다. 명시한 --profile <name> 이 있으면 언제나 그쪽이 우선합니다.
dsh plugin add <plugin>
dsh plugin remove <plugin>
dsh plugin update
플러그인을 바꾼 뒤에는 새 번들이 Loader 합성에 들어가도록 앱을 재시작해야 합니다. 프로필을 전환한다고 해서 이전 프로필의 플러그인이 조용히 복사되지는 않으므로, 다른 프로필을 준비할 때는 터미널에서 프로필을 명시하거나 전환 후에 기본 명령을 쓰는 편이 안전합니다.
소스에서 직접 빌드하려면 바깥 저장소는 Yarn을, 고정된 deepseek-harness/ 서브모듈은 자체 pnpm 워크스페이스를 쓴다는 점을 기억해야 합니다. 데스크톱 소스는 dsh-plugin-desktop/ 아래에 있습니다.
git submodule update --init --recursive
corepack yarn install --immutable
corepack yarn dev
헤드리스 검사는 corepack yarn check 로 돌립니다.
DSH Desktop의 라이선스
DSH Desktop은 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 저장소는 이 프로젝트가 DeepSeek Harness 위에 만든 커뮤니티 데스크톱 에디션이며 DeepSeek의 공식 제품이 아니라는 점, DeepSeek이 DeepSeek AI의 상표라는 점을 별도로 밝히고 있습니다.
DSH Desktop 공식 홈페이지
DSH Desktop 문서 색인
DSH Desktop 프로젝트 GitHub 저장소
더 읽어보기
-
Paseo: Claude Code, Codex 등 코딩 에이전트를 휴대폰과 데스크톱에서 쓰는 셀프 호스팅 도구
-
OpenHarness: Claude Code보다 44배 가벼운 Python 기반 오픈소스 AI 에이전트 하네스 프레임워크 (feat. HKUDS)
이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. 
이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임
회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 