dsh를 전역으로 설치해야 하나요?

아니요. npx 빠른 시작은 필요할 때 패키지를 내려받아 실행하고, 소스 방식은 클론한 저장소 안에서 pnpm으로 CLI를 실행합니다. 프리뷰가 호환성을 깨는 변경을 배포하므로, 설치해 놓고 잊어버리는 전역 바이너리보다 프로젝트별로 고정한 버전이 더 오래갑니다.

DeepSeek Harness는 무료인가요?

하네스 자체는 MIT 라이선스 오픈소스이므로 비용 없이 실행, 수정, 재배포할 수 있습니다. 연결하는 모델은 별개의 문제이며, 그 제공자가 얼마를 청구하든 하네스 라이선스가 다루는 범위가 아닙니다.

웹 UI는 왜 네트워크 주소가 아니라 127.0.0.1에서 대기하나요?

그 주소는 루프백이라, 인터페이스가 자신을 시작한 기기에서만 응답한다는 뜻입니다. 앞단에 프록시나 터널을 의도적으로 두지 않는 한 로컬 네트워크의 어떤 기기도 http://127.0.0.1:3080 에 도달할 수 없습니다. 여러분의 기기에서 명령을 실행할 수 있는 도구에게는 합리적인 기본값입니다.

지금 dsh를 실제 업무에 쓸 수 있나요?

안전하지 않습니다. DeepSeek Harness는 2026년 8월 13일 공개된 개발자 프리뷰이며, README가 대문자로 호환성을 깨는 변경이 있을 것이라고 경고합니다. 온콜 로테이션에 올릴 인프라가 아니라, 실험하고 플러그인을 만들어 보는 대상으로 다루세요.

cordis.yml이 정확히 뭔가요?

하네스가 어떤 플러그인으로 시작하고 각각을 어떻게 설정할지 결정하는 로더 설정입니다. dsh는 모델, 도구, 스킬, 세션, 샌드박스는 물론 UI까지 플러그인으로 다루기 때문에, cordis.yml은 사실상 '여러분의 설치본이 무엇을 할 수 있는가'의 정의 그 자체입니다.

DeepSeek Harness(dsh) 설치하기

DeepSeek Harness — 명령줄에서는 dsh — 는 DeepSeek AI가 2026년 8월 13일 MIT 라이선스로 공개한 에이전트 하네스입니다. 이 가이드는 실행하는 방법, 설치본이 실제로 무엇을 할 수 있는지를 결정하는 단 하나의 설정 파일, 그리고 저희가 수록한 7900개 저장소에서 플러그인을 가져오는 방법을 다룹니다.

먼저 읽어 주세요

dsh는 개발자 프리뷰입니다. README는 대문자로 호환성을 깨는 변경이 있을 것이라고 경고합니다. 아래 내용은 모두 2026년 8월 14일 시점의 프리뷰를 설명한 것입니다. 중요한 스크립트에 명령을 붙여 넣기 전에 저장소를 확인하세요.

사전 요구사항

Node.js가 필요합니다. 저장소는 engines 범위를 ^22.19 || >=24로 선언하고 있어, 더 오래된 런타임에서는 설치가 거부되거나 나중에 하네스의 버그처럼 보이는 방식으로 실패합니다. 시작하기 전에 버전을 확인하세요:

node -v

npx 방식이라면 요구사항은 이것이 전부입니다. 소스에서 빌드하려면 git과 pnpm도 필요합니다(저장소가 pnpm 기준으로 구성되어 있습니다). 이 페이지 어디에서도 dsh를 시스템 전역에 설치하라고 하지 않습니다. 프리뷰가 이렇게 빠르게 움직이는 동안에는, 설치해 놓고 잊어버리는 전역 바이너리보다 프로젝트에 고정한 버전이 훨씬 다루기 쉽습니다.

npx로 빠르게 시작하기

명령 하나면 웹 인터페이스가 딸린 하네스가 실행됩니다:

npx @deepseek-ai/dsh web

npm이 패키지를 가져오고, 하네스는 http://127.0.0.1:3080에서 웹 UI를 제공합니다. 이 주소는 루프백이라 여러분의 기기에서만 응답하며 다른 곳에서는 접근할 수 없습니다. 파일을 읽고 명령을 실행할 수 있는 도구에게는 이것이 올바른 기본값입니다.

CLI는 --profile 플래그도 받습니다(dsh --profile <profile>). 시작할 때 로드할 플러그인 묶음을 고르는 옵션입니다. 기본 제공 프로파일에는 headless가 있습니다. 출시 다음 날 작성된 목록을 믿기보다, 여러분이 쓰는 버전에 대해 직접 dsh --help를 실행해 보세요. 사용 가능한 프로파일과 번들은 프리뷰가 릴리스마다 재배치하기 딱 좋은 종류의 것입니다.

소스에서 실행하기

플러그인을 만들 계획이라면 저장소에서 빌드하는 데 몇 분 더 쓸 가치가 있습니다. README에서 추론하는 대신 실제 패키지 API를 직접 읽을 수 있기 때문입니다:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

첫 pnpm dsh web 전에 빌드를 실행하세요. 문서에 적힌 순서가 그렇습니다. 마찬가지로 3080 포트의 웹 UI에 도달하지만 이번에는 작업 트리를 기준으로 동작하므로, 패키지를 고치고 다시 빌드해 결과를 바로 확인할 수 있습니다. 어떤 릴리스에서 실제로 무엇이 바뀌었는지 알아내는 가장 빠른 방법이기도 합니다. 이렇게 빠르게 움직이는 프리뷰는 자기 문서를 앞질러 가기 마련이니까요.

cordis.yml의 위치

dsh를 관통하는 발상은 모든 것이 플러그인이라는 것입니다. 모델, 도구, 스킬, 세션, 샌드박스, 파일 시스템, 에이전트 루프, 오케스트레이션, 사용자 인터페이스까지 모두 하나의 공유 런타임에 로드되는 플러그인입니다. 그 런타임이 바로 하네스가 올라타 있는 메타 프레임워크 Cordis이며, @deepseek-ai/cordis는 모든 하네스 패키지의 peer dependency입니다.

어떤 플러그인을 어떤 옵션으로 로드할지는 cordis.yml 로더 설정이 결정합니다:

# cordis.yml
plugins:
  dsh-example-plugin:

plugins: 아래의 각 키가 플러그인을 가리키고, 그 아래 블록이 해당 플러그인의 설정입니다(기본값으로 충분하다면 비워 두어도 됩니다). 공식 패키지는 @deepseek-ai/dsh-<name> 형태로 배포되며, 로더 키는 보통 npm 스코프를 뗀 패키지 이름입니다. 다만 플러그인 작성자가 다른 키를 고르기도 하므로, 추가하려는 플러그인의 README가 어떤 경험칙보다 — 이 문장을 포함해서 — 우선합니다.

커뮤니티 플러그인 추가하기

플러그인 추가는 두 단계입니다. 패키지를 설치하고, 로더 설정에 등록하면 됩니다.

npm install dsh-example-plugin

# cordis.yml
plugins:
  dsh-example-plugin:

하네스를 재시작하면 그 플러그인도 나머지와 함께 로드됩니다. 설치할 만한 것을 찾으려면 수록된 7900개 저장소를 둘러보거나 카테고리로 좁혀 보세요. 그중 3942개가 검증됨 상태입니다 — 저장소에서 Cordis 런타임 의존성이나 cordis.yml을 확인했다는 뜻이며, 실제로 로드된다는 의미입니다. 나머지는 뒤에 아무 연결도 없이 dsh-plugin GitHub 토픽만 달고 있습니다. 이 점이 중요한 이유는 그 토픽이 곧 발견 경로이기도 하기 때문입니다. 플러그인을 공개한다면 토픽을 다는 것이 생태계가 여러분을 찾는 방법입니다.

문제 해결

설치가 engine 오류나 구문 오류로 실패합니다

거의 항상 Node.js가 오래된 것이 원인입니다. 저장소는 ^22.19 || >=24를 요구합니다. 그보다 낮으면 설치 단계에서 실패하거나 의존성 깊숙한 곳에서 파싱 오류를 던집니다. 패키지가 망가진 것처럼 보이지만 그렇지 않습니다. node -v를 확인하고 업그레이드하세요. 같은 기기의 다른 프로젝트가 옛 런타임을 필요로 한다면 nvm이나 fnm 같은 버전 관리자가 가장 영향이 적습니다.

3080 포트가 이미 사용 중입니다

다른 무언가가 포트를 잡고 있습니다. 흔한 경우는 종료되지 않은 이전 dsh 실행입니다. macOS나 Linux에서는 다음으로 찾을 수 있습니다:

lsof -i :3080

해당 프로세스를 멈추고 다시 시작하세요. 다른 서비스 대신 하네스를 옮기고 싶다면, 플래그 이름을 짐작하지 말고 dsh --help와 cordis.yml에 있는 web 플러그인의 옵션을 확인하세요. 프리뷰의 옵션 표면은 아직 변하고 있어서, 지난주 블로그 글에서 되던 플래그가 여러분의 빌드에는 없을 수 있습니다.

지난주에는 됐는데 지금은 안 됩니다

이는 수수께끼가 아니라 개발자 프리뷰에서 예상되는 고장 방식입니다. README가 호환성을 깨는 변경이 온다고 분명히 밝히고 있으며, 옛 로더 형식에 맞춰 만든 플러그인은 하네스 업그레이드 후 조용히 로드되지 않을 수 있습니다. 두 가지 습관이 도움이 됩니다. 검증한 버전을 고정하는 것, 그리고 자기 설정을 탓하기 전에 그 플러그인이 마지막으로 푸시된 시점을 확인하는 것입니다. 저희 목록은 모든 플러그인 페이지에 그 날짜를 표시합니다.

npx @deepseek-ai/dsh@<version> web

이름만 바뀐 게 아니라 정말로 망가진 경우라면, 프로젝트가 GitHub Discussions와 Discord를 운영하고 있으며 이런 주간에는 어떤 서드파티 가이드보다도 최신 정보를 담고 있습니다.

자주 묻는 질문

dsh를 전역으로 설치해야 하나요?: 아니요. npx 빠른 시작은 필요할 때 패키지를 내려받아 실행하고, 소스 방식은 클론한 저장소 안에서 pnpm으로 CLI를 실행합니다. 프리뷰가 호환성을 깨는 변경을 배포하므로, 설치해 놓고 잊어버리는 전역 바이너리보다 프로젝트별로 고정한 버전이 더 오래갑니다.
DeepSeek Harness는 무료인가요?: 하네스 자체는 MIT 라이선스 오픈소스이므로 비용 없이 실행, 수정, 재배포할 수 있습니다. 연결하는 모델은 별개의 문제이며, 그 제공자가 얼마를 청구하든 하네스 라이선스가 다루는 범위가 아닙니다.
웹 UI는 왜 네트워크 주소가 아니라 127.0.0.1에서 대기하나요?: 그 주소는 루프백이라, 인터페이스가 자신을 시작한 기기에서만 응답한다는 뜻입니다. 앞단에 프록시나 터널을 의도적으로 두지 않는 한 로컬 네트워크의 어떤 기기도 http://127.0.0.1:3080 에 도달할 수 없습니다. 여러분의 기기에서 명령을 실행할 수 있는 도구에게는 합리적인 기본값입니다.
지금 dsh를 실제 업무에 쓸 수 있나요?: 안전하지 않습니다. DeepSeek Harness는 2026년 8월 13일 공개된 개발자 프리뷰이며, README가 대문자로 호환성을 깨는 변경이 있을 것이라고 경고합니다. 온콜 로테이션에 올릴 인프라가 아니라, 실험하고 플러그인을 만들어 보는 대상으로 다루세요.
cordis.yml이 정확히 뭔가요?: 하네스가 어떤 플러그인으로 시작하고 각각을 어떻게 설정할지 결정하는 로더 설정입니다. dsh는 모델, 도구, 스킬, 세션, 샌드박스는 물론 UI까지 플러그인으로 다루기 때문에, cordis.yml은 사실상 '여러분의 설치본이 무엇을 할 수 있는가'의 정의 그 자체입니다.

다음에 볼 것

플러그인 모델 자체가 처음이라면 에이전트 하네스가 무엇인지부터 시작하세요. dsh가 왜 그렇게 많은 것을 로더 설정 뒤에 두는지 설명합니다. 이미 쓰는 도구와 dsh를 저울질하고 있다면 Claude Code와의 비교를 보세요. dsh가 아직 명백히 준비되지 않은 부분도 함께 다룹니다.