DeepSeek Harness VPS 설치 및 SSH 터널링 보안 설정
DeepSeek Harness를 Linux VPS에 설치하고 3080 포트를 안전하게 사용하는 방법을 안내합니다. npm 버전 고정 방법과 플러그인 구조를 이해하고, SSH 터널을 통해 외부 노출 없이 웹 UI에 접속하여 에이전트를 안전하게 운영하는 구체적인 절차를 확인하십시오.
DeepSeek Harness란 무엇인가
DeepSeek Harness(dsh)는 VPS(가상 사설 서버)에서 실행할 수 있는 Node.js 에이전트 런타임입니다. 이를 안전하게 실행하는 방법은 127.0.0.1에 바인딩하고 SSH(secure shell) 터널을 통해 브라우저로 접속하는 것입니다. 이 도구는 터미널에서 실행되는 대신 3080 포트에서 웹 UI(사용자 인터페이스)를 제공합니다. 이 가이드에서 고정한 0.1.0-rc.6 릴리스의 웹 서버는 자체 비밀번호를 요구하지 않습니다. 따라서 3080 포트를 외부에 공개하면 누구나 사용자의 파일에 접근하고 Linux 사용자의 권한으로 명령을 실행할 수 있는 에이전트에 접속할 수 있게 됩니다. 0.2.0-rc.2부터 2026년 11월 11일의 0.2.2-rc.2(2026년 11월 12일 GitHub에 게시된 최신 릴리스)까지의 최신 릴리스는 프로세스에 대한 새로운 토큰이 포함된 시작 URL을 출력하고 이를 세션 쿠키로 교체하지만, 기본적으로 루프백 인터페이스에서만 수신 대기하며 모든 인터페이스에 바인딩하는 것을 여전히 거부합니다.
DeepSeek는 이를 MIT 라이선스 하에 npm 패키지 @deepseek-ai/dsh로 배포합니다. 이 프로젝트는 스스로를 개발자 프리뷰라고 설명하며 호환성을 깨뜨리는 변경 사항이 발생할 수 있다고 명시합니다. 아래에 고정된 버전은 2026년 8월 릴리스입니다. 2026년 11월 12일 기준으로 npm의 latest 태그는 0.2.2-rc.1를 가리킵니다. GitHub에는 2026년 11월 11일에 릴리스된 dsh-v0.2.2-rc.2 태그의 최신 프리릴리스 0.2.2-rc.2가 나열되어 있습니다. 중요한 서버에 설치하기 전에 저장소를 확인하십시오.
이 설계 전체를 관통하는 핵심 개념은 모든 것이 플러그인이라는 점입니다. 모델 어댑터, 도구 레지스트리, 세션 로그, 샌드박스, 스케줄러, 그리고 에이전트 루프 자체가 하나의 공유 컨텍스트에 로드되는 플러그인이며, 이 중 무엇이든 교체할 수 있습니다. 플러그인이 단순히 장식하는 특권 코어는 존재하지 않습니다. 이것이 바로 이 Harness를 시도해 볼 가치가 있게 만드는 이유이자, 유일한 실질적인 위험이 존재하는 지점이기도 합니다. 이러한 절충안이 적절한지는 무엇을 기준으로 평가하느냐에 달려 있으며, Claude Code 및 Omnigent와의 비교 섹션에서는 모델 결합, 라이선스, 각 도구가 요구하는 VPS 사양 측면에서 이 '모든 것이 플러그인'인 설계를 다른 두 가지 대안과 비교합니다.
하네스는 모델이 아닙니다
하네스는 에이전트 루프를 실행합니다. 추론은 다른 곳에 있는 모델에서 수행되므로, API(application programming interface) 키나 직접 호스팅하는 모델 엔드포인트 주소를 제공하기 전까지는 아무것도 작동하지 않습니다. 이 게시물의 모든 내용은 모델 동작이 아닌 하네스 설정에 관한 것이며, 두 항목 사이의 경계를 명확히 이해해야 문제의 원인이 어디에 있는지 디버깅하며 오후 시간을 낭비하는 일을 방지할 수 있습니다.
이 설정은 UI의 Settings 내 Models 항목에서 수행합니다. DeepSeek는 자체 카드를 가지고 있으며, 현재 릴리스에서는 그 아래에 있는 "Add model provider" 버튼을 통해 두 가지 모드를 선택할 수 있습니다. "Third-party model provider"는 OpenAI나 Anthropic처럼 하네스에서 카탈로그를 제공하는 공급자를 다룹니다. 여기서는 키를 붙여넣기만 하면 카탈로그가 엔드포인트와 모델 목록을 제공합니다. "Custom model API"는 흥미로운 옵션입니다. 소문자 공급자 ID, 표시 이름, 기본 URL, API 프로토콜, 자격 증명, 그리고 최소 하나 이상의 모델을 입력해야 합니다. 프로토콜 선택기에서는 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini API를 지원하므로, 이 중 하나를 사용하는 게이트웨이나 로컬 서버를 설정할 수 있습니다. 요청 형식이 다른 엔드포인트는 호환성 설정이 필요합니다. 사용자 지정 공급자는 OpenAI 호환 GET /models 엔드포인트를 쿼리하여 모델 목록을 자동으로 채울 수도 있습니다.
이 방법으로 하네스를 동일한 VPS의 모델에 연결할 수 있습니다. Ollama는 http://127.0.0.1:11434/v1/에서 OpenAI 호환 API를 노출하며, API 키 필드에는 임의의 문자열을 입력하면 됩니다. 관례적으로 ollama를 사용하는데, 이는 OpenAI 스타일 클라이언트가 값을 요구하지만 Ollama는 이를 무시하기 때문입니다. Ollama 자체 문서에서도 ollama launch dsh을 설명하고 있습니다. 이는 @deepseek-ai/dsh이 누락된 경우 이를 설치하고 Ollama 모델을 대상으로 실행하므로, 아래의 핀(pin)에 의존하기 전에 어떤 버전을 설치하는지 확인하십시오. VPS에 들어갈 만큼 작은 모델이 에이전트를 구동하기에 충분한지는 더 어려운 문제이며, 로컬 모델 서버로서의 Ollama와 vLLM의 차이에 따라 RAM 사용량이 결정됩니다.
UI에 입력한 키는 쓰기 전용입니다. 하네스는 이를 $DSH_HOME/.credentials.yaml에 저장하며, 설정에는 자격 증명 참조값만 유지됩니다. 현재 릴리스는 이를 활성 프로필의 패치 파일인 $DSH_HOME/profiles/<profile>/cordis.patch.yml에 기록합니다(프로필은 dsh web의 경우 web입니다). $DSH_HOME의 기본값은 ~/.dsh입니다. 자격 증명 파일은 비밀번호 파일과 다름없으므로 그에 준하여 관리하십시오. 이 파일을 읽을 수 있는 사람은 누구나 사용자의 API 예산을 사용할 수 있습니다. Settings를 클릭하는 대신 파일을 직접 편집하려면, dsh 설정 파일, 키 및 모델 엔드포인트 가이드를 통해 각 키의 역할과 각 모드에서 외부로 나가는 데이터가 무엇인지 확인하십시오.
설치 전 준비 사항
- SSH 접근이 가능한 Ubuntu 24.04 또는 최신 Linux가 설치된 VPS
- Node.js 24.9 이상. 프로젝트의 메인 브랜치와
0.2.2-alpha.2에서>=24.9.0를 명시하고 있으며, CI 테스트는 Node 24.9 및 Node 26과의 호환성 검사를 포함하여 Node 24 환경에서 수행됩니다. Node 22 작업은 더 이상 존재하지 않습니다.0.2.1-rc.4을 통해 배포된 릴리스는 Node 22.19를 허용 범위로 명시했으나, 현재 프로젝트 빌드 기준은 그보다 높습니다. root이 아닌 일반 사용자 계정. 에이전트는 프로세스를 시작한 사용자의 권한으로 셸 명령을 실행합니다.- 플러그인 설치 계획이 있다면 PATH에
pnpm가 포함되어 있어야 합니다. 플러그인 명령이 해당 도구를 호출하기 때문입니다. - 방화벽 및 제공업체의 외부 네트워크 방화벽에서 3080 포트가 닫혀 있어야 합니다.
Ubuntu 24.04의 기본 nodejs 패키지는 프로젝트가 요구하는 버전보다 낮습니다. 따라서 해당 릴리스에서는 apt install nodejs를 사용하는 대신 NodeSource나 nvm을 통해 Node를 설치하십시오. Ubuntu 26.10의 공식 저장소는 Node 24.19.0을 제공하며, 이는 최소 요구 사항인 Node 24.9를 충족합니다. VPS를 새로 설정하는 경우, 가장 먼저 SSH 보안을 강화하는 데 10분을 투자하십시오. 앞으로 사용할 터널의 안정성은 기반이 되는 SSH 서버의 보안 수준에 달려 있기 때문입니다.
VPS에 DeepSeek Harness 설치 및 특정 버전 고정
node --version
npx @deepseek-ai/dsh@0.1.0-rc.6 webnpx는 패키지를 다운로드하고 dsh 바이너리를 실행합니다. web은 --profile web의 별칭이며, 브라우저 애플리케이션을 구동하고 프로세스가 수신 대기 중인 주소를 출력합니다. 기본값은 http://127.0.0.1:3080입니다. 이 숫자는 단순히 보기 좋으라고 정한 기본값이 아니라 바인딩 결정 사항입니다. dsh가 루프백 주소를 출력하는 이유에서 노트북으로 접속하기 전에 하네스가 무엇에 응답하고 무엇에 응답하지 않는지 다룹니다.
버전을 고정하십시오. npx @deepseek-ai/dsh web은 실행하는 순간 latest 태그가 가리키는 버전을 확인합니다. 단, 실행하는 프로젝트에 이미 설치된 복사본이 있다면 npx는 조용히 해당 복사본을 사용합니다. 어느 경우든 사용자가 직접 버전을 선택하는 것이 아니며, 해당 프로젝트는 이미 여러 릴리스 후보를 배포했고 주요 변경 사항이 있을 것이라고 예고했습니다. 0.1.0-rc.6는 여기에 고정된 2026년 8월 버전입니다. 2026년 11월 12일 기준으로 latest은 토큰화된 시작 URL을 출력하는 릴리스인 0.2.2-rc.1를 가리킵니다. GitHub에는 더 최신인 프리릴리스 0.2.2-rc.2가 나열되어 있으므로, 다른 버전으로 이동하는 것은 저장소를 읽어본 뒤 의도적으로 수행해야 하는 업그레이드입니다. 버전을 고정하면 오늘 설정한 서버가 다음 달에도 동일하게 동작하므로, 업그레이드는 우연히 발견하는 사고가 아니라 사용자가 내리는 결정이 됩니다. 고정된 명령으로도 잘못된 빌드가 시작되거나 설치가 거부된다면 일반적인 dsh 설치 및 버전 오류를 참조하여 npx 캐시를 삭제하고 Node가 어떤 npm을 사용하는지 확인하십시오.
매일 사용하려면 실행할 때마다 다시 확인하지 말고 한 번만 설치하십시오.
npm install -g @deepseek-ai/dsh@0.1.0-rc.6
dsh --profile web --help두 번째 줄은 실행할 가치가 있습니다. 런처와 웹 앱이 서로 다른 플래그 세트를 사용하기 때문입니다. dsh --help은 런처 자체의 옵션을 보여줍니다. dsh --profile web --help은 웹 애플리케이션이 허용하는 플래그를 보여주며, --port, --host 및 반복 가능한 --trusted-host이 여기에 포함됩니다.
이제 수신 대기 중인 주소를 확인하십시오.
ss -tlnp | grep 3080로컬 주소 열은 127.0.0.1:3080로 표시되어야 합니다. 만약 0.0.0.0:3080로 표시된다면 UI가 모든 인터페이스에서 수신 대기 중인 상태입니다. 이 경우 방화벽만이 인터넷과 서비스 사이를 가로막고 있는 것이므로, 다른 작업을 수행하기 전에 즉시 프로세스를 중단하십시오.
포트 3080을 절대 공개해서는 안 되는 이유
0.1.0-rc.6의 웹 서버에는 인증 계층이 없습니다. 설정 파일에 리슨 호스트와 리슨 포트를 지정하는 것이 전부이며, 이것이 노출 범위의 전부입니다. 루프백이 아닌 환경에서의 접근 제어는 별도의 신뢰 호스트 설정으로 처리하지만, 이는 로그인 화면이 아닙니다.
최신 릴리스에는 인증 기능이 추가되었습니다. 0.2.0-rc.2 버전부터는 시작 시 해당 프로세스 전용의 새로운 토큰이 포함된 URL이 출력됩니다. 이 URL을 브라우저로 열면 서명된 세션 쿠키를 발급받고, 토큰이 제거된 동일한 주소로 리다이렉트됩니다. /api 앞단에 위치한 Host/Origin 방화벽은 루프백 주소, 리스너의 자체 바인드 주소, 그리고 --trusted-host에 명시한 권한 주체로부터의 요청만 허용합니다. 이는 실제 자격 증명이지만, 프로젝트 공식 문서에서는 출력된 URL을 의도한 사용자에게만 공유해야 하며, 일반 HTTP 환경에서는 암호화 없이 전송된다고 경고합니다. 0.2.1-alpha.2 버전부터는 웹 앱이 특정 로컬 주소에 바인딩하여 --tls-cert 및 --tls-key를 통해 직접 HTTPS를 제공할 수 있습니다. 이는 평문 전송 문제를 해결할 뿐, 포트 노출 문제를 해결하지는 않습니다. 노출된 포트를 악용하기 어렵게 만들 뿐, 포트를 공개해도 된다는 의미는 아닙니다.
이제 해당 포트 뒤에서 무엇이 실행되는지 살펴보겠습니다. 에이전트는 작업 공간의 파일을 수정하고 셸 명령을 실행하며, 공급자 자격 증명이 디스크상에 함께 저장되어 있습니다. 따라서 고정된 릴리스에서 포트 3080을 열어두는 것은, API 키가 포함된 상태로 서비스를 실행한 사용자의 권한을 가진 원격 셸을 채팅 인터페이스와 함께 노출하는 것과 같습니다. 이를 위해 별도의 익스플로잇은 필요하지 않습니다. 공격자는 단지 포트 번호만 알면 됩니다. 시작 토큰이 있는 릴리스의 경우 토큰도 필요하지만, 터미널이나 서비스 로그를 읽을 수 있거나 암호화되지 않은 트래픽을 가로챌 수 있는 사람이라면 누구나 토큰을 획득할 수 있습니다.
CLI(명령줄 인터페이스)도 이러한 정책을 따릅니다. 0.1.0-rc.6 버전부터는 의도적으로 --host 0.0.0.0을 지원하지 않으며, 시작 대신 사용법 오류를 출력하고 종료됩니다. 더 최신 버전인 0.2.2-alpha.2 역시 시작 시 이를 거부합니다. 이러한 거부 동작은 기능의 일부이므로, 이를 제거하는 패치를 찾으려 하지 마십시오.
터널링이 적합하지 않은 경우, 두 가지 다른 배포 방식이 합리적입니다. 첫째, 자체 호스팅 Headscale 제어 서버를 사용하여 본인의 장치만 라우팅할 수 있는 사설 오버레이 네트워크에 서버를 배치하십시오. 둘째, 포트 3080에 도달하기 전에 요청을 인증하는 리버스 프록시를 앞단에 두십시오. 예를 들어, Authentik 싱글 사인온 서버를 사용하여 포워드 인증을 수행할 수 있습니다. 인증 기능이 없는 리버스 프록시는 보안 제어 수단이 아닙니다. 단지 URL을 길게 늘릴 뿐입니다.
SSH 터널을 통해 웹 UI에 접속하기
이 작업은 서버가 아닌 로컬 노트북에서 실행하십시오.
ssh -N -L 3080:127.0.0.1:3080 you@your-server-L는 노트북의 3080 포트를 열고, 해당 포트로 들어오는 모든 연결을 암호화된 SSH 세션을 통해 전달합니다. 127.0.0.1:3080 부분은 서버 측에서 해석되므로, 연결은 마치 사용자가 서버 앞에 직접 앉아 있는 것처럼 루프백(loopback)을 통해 하네스(harness)에 도달합니다. -N는 원격 셸을 시작하지 않도록 지시하는데, 이는 포트 포워딩 외에 다른 작업이 필요하지 않기 때문입니다.
그런 다음 로컬 브라우저에서 http://127.0.0.1:3080를 엽니다. 시작 토큰이 포함된 릴리스를 사용하는 경우, 서버가 출력한 전체 시작 URL(토큰 포함)을 대신 여십시오. SSH를 통해 하네스를 시작하면 시작 라인은 출력되지만 브라우저를 자동으로 열지는 않습니다. 노트북에서 3080 포트를 이미 사용 중이라면 왼쪽 숫자를 변경하십시오. 예를 들어 ssh -N -L 3180:127.0.0.1:3080 you@your-server으로 설정한 뒤 http://127.0.0.1:3180로 접속하고, 토큰이 포함된 URL에서도 동일하게 포트 번호를 변경하십시오. 왼쪽 숫자는 로컬 포트이고 오른쪽 숫자는 서버 포트이므로, 왼쪽 숫자만 변경해야 합니다.
이 명령을 ~/.ssh/config에 저장하여 매번 입력하는 번거로움을 줄이십시오.
Host dsh
HostName 203.0.113.10
User deploy
IdentityFile ~/.ssh/id_ed25519
LocalForward 3080 127.0.0.1:3080그 후 ssh -N dsh를 실행하면 터널이 시작됩니다. 브라우저에서 연결 거부 오류가 발생한다면, SSH는 하네스 실행 여부와 관계없이 포트를 포워딩하므로 터널은 정상이나 서버 측에서 아무것도 수신 대기 중이지 않을 가능성이 큽니다. 위에서 언급한 ss 명령으로 서버 상태를 확인하십시오.
로그아웃 후에도 하네스를 계속 실행하기
npx 명령어는 셸이 종료되면 함께 종료됩니다. systemd 사용자 서비스는 셸 종료 후에도 유지되며, 충돌이나 재부팅이 발생해도 하네스를 다시 실행합니다. 여기에 제시된 유닛은 의도적으로 최소한의 설정만 포함하고 있습니다. 만약 하네스를 별도의 제한된 계정으로 실행하고, 유닛 내에 버전을 고정하며, 검색 가능한 로그를 남기고 싶다면 the headless systemd setup for dsh에서 전체 내용을 확인할 수 있습니다.
loginctl enable-linger $USER
mkdir -p ~/.config/systemd/user
command -v dshenable-linger 설정은 중요합니다. 사용자 서비스는 일반적으로 마지막 세션이 종료될 때 함께 중단되기 때문에, 이 설정이 없으면 터널을 닫는 즉시 하네스가 종료됩니다. command -v dsh 명령어로 출력된 절대 경로를 유닛 파일에 입력하십시오. systemd는 로그인 셸이 구성하는 PATH를 참조하지 않기 때문입니다.
[Unit]
Description=DeepSeek Harness web UI
After=network-online.target
[Service]
Type=simple
WorkingDirectory=%h/projects/site
ExecStart=/usr/local/bin/dsh web
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.targetWorkingDirectory 설정은 단순한 장식이 아닙니다. dsh 프로세스는 호출된 디렉터리를 기본 파일 시스템 위치로 사용하므로, 잘못된 위치에서 서비스를 시작하면 에이전트가 엉뚱한 폴더를 참조하게 됩니다. 하지만 해당 디렉터리는 기본값일 뿐입니다. 새로운 웹 UI는 'Choose workspace'에서 작업 공간을 추가하기 전까지는 선택된 작업 공간이 없으며, 프로젝트 가이드는 dsh을 시작한 디렉터리를 추가하라고 안내합니다. 해당 가이드에는 버전 표시가 없으며, 동일한 문구가 0.1.0-rc.7에도 포함되어 있으므로 고정된 릴리스에서도 동일하게 적용될 것으로 예상하십시오. 유닛의 디렉터리를 프로젝트 경로로 설정한 뒤, UI에서 해당 작업 공간을 선택하십시오.
systemctl --user daemon-reload
systemctl --user enable --now dsh
systemctl --user status dsh유닛이 시작되지 않는다면 거의 대부분 ExecStart 경로가 잘못되었거나 바이너리가 거부하는 Node 버전 때문이며, journalctl --user -u dsh -n 50에서 그 원인을 확인할 수 있습니다. 시작 토큰이 포함된 릴리스의 경우, 저널(journal)에 토큰화된 시작 URL이 기록되며 재시작할 때마다 새로운 URL이 출력됩니다. 이와 동일한 패턴이 keeping any coding agent alive on a VPS에도 적용되며, 실패 유형 또한 동일합니다.
플러그인의 허용 범위
플러그인은 공유 컨텍스트에 서비스, 타입이 지정된 이벤트, 가역적 효과를 제공하는 모듈입니다. 확장 지점은 주의 깊게 읽어볼 필요가 있습니다.
ctx.llm에 모델 공급자 등록ctx.tools에 모델용 도구 추가ctx.shell를 통해 셸 백엔드 제공ctx.fs을 통해 파일 시스템 접근 또는 정책 제공ctx.commands에 사용자 명령 등록ctx.jobs를 통해 백그라운드 작업 실행ctx.sandbox백엔드로 생성된 프로세스 래핑agent/*및tools/*이벤트를 통해 요청 및 도구 호출 가로채기- 지속 가능한 세션 상태 확장
ctx.agents을 통해 UI 구동
이 목록을 공격자의 관점에서 읽어보십시오. 플러그인은 파일 시스템 계층과 셸 계층을 제공할 수 있으며, 모델이 수행하는 모든 도구 호출의 중간에 위치할 수 있습니다. 플러그인은 다른 모든 것과 동일한 프로세스에 로드되는 일반적인 Node 코드이므로, 플러그인과 이러한 연결 지점 사이에 권한 확인 대화 상자는 존재하지 않습니다. 플러그인을 설치하는 것은 에이전트의 권한으로 낯선 사람의 코드를 실행하는 것과 같으며, 에이전트의 권한은 곧 사용자의 Unix 계정 권한과 같습니다.
이는 VPS에서 에이전트에 MCP 서버를 연결할 때 내리는 신뢰 결정과 동일합니다. 여기서 MCP는 모델 컨텍스트 프로토콜(Model Context Protocol)을 의미합니다. 또한 VPS에서 코딩 에이전트를 안전하게 실행하는 것이 모델이 아닌 실행 계정부터 시작해야 하는 이유이며, npm 공급망 공격이 서버에 치명적인 이유이기도 합니다. 설치 단계 자체가 곧 침해이며, 그 과정에서 어떠한 경고도 표시되지 않기 때문입니다.
플러그인의 출처
플러그인은 프로필 내에 존재합니다. 프로필은 $DSH_HOME 아래에 저장되는 명명된 구성이며, 기본값은 ~/.dsh입니다. 각 프로필 디렉터리는 설치된 외부 플러그인을 보관합니다. CLI는 프로필 디렉터리를 작업 디렉터리로 사용하여 인수를 pnpm로 직접 전달함으로써 이를 관리합니다.
dsh plugin --profile web add github:deepseek-harness/turtle-ui
dsh plugin --profile web remove turtle-ui인수는 변경되지 않은 상태로 pnpm에 도달하므로, add, remove, update 및 why는 모든 pnpm 프로젝트에서와 동일하게 동작하며, 플러그인은 npm 패키지나 GitHub 참조가 될 수 있습니다. pnpm은 먼저 PATH에 존재해야 합니다. Node 24에서는 corepack enable pnpm이 이를 수행합니다. Node 25부터는 Corepack 배포가 중단되었으므로, Node 25 이상에서는 대신 npm install -g pnpm를 사용하여 설치하십시오.
검색은 GitHub 토픽을 통해 이루어집니다. 플러그인 작성자는 자신의 저장소에 dsh-plugin 토픽을 추가하며, 해당 토픽을 탐색하여 존재하는 플러그인을 찾을 수 있습니다. 토픽은 작성자가 자신의 저장소에 적용하는 레이블입니다. 아무도 이를 검토하거나 서명하지 않으며, 토픽 페이지는 안전성이 아닌 인기도를 측정하는 별점 순으로 정렬됩니다.
현재 릴리스에는 실험적인 사용자 지정 플러그인 인덱스 번들도 포함되어 있습니다. 플러그인 설정에서 이를 활성화하면 검색 탭을 통해 인덱스를 추가할 수 있으며, 이는 사용자가 제공한 URL에서 가져온 JSON 파일입니다. 하네스는 자체 인덱스를 제공하지 않으며, 파일 형식은 확인하지만 마켓에서 주장하는 제목, 작성자 또는 출처는 확인하지 않습니다. 네트워크 경로상에 있는 누구라도 일반 http:를 통해 제공되는 인덱스를 재작성할 수 있습니다. 마켓은 다른 사람이 작성한 카탈로그일 뿐, 검토 결과가 아닙니다.
이를 관리하기 위한 네 가지 습관이 있습니다. 대부분의 플러그인은 10분 안에 읽을 수 있을 만큼 작으므로 설치하기 전에 소스 코드를 읽으십시오. 브랜드를 추적하는 대신 정확한 버전이나 커밋을 고정하십시오. 하네스는 다른 데이터가 없는 사용자 계정으로, 언제든 재구축할 의향이 있는 VPS에서 실행하십시오. 에이전트에는 프로덕션 서비스에서 사용하는 키와 분리된, 자체 지출 한도가 설정된 전용 API 키를 부여하십시오. 플러그인을 읽다가 어떤 파일이 위험을 초래하는지 알고 싶다면, dsh 플러그인 검증 가이드를 통해 매니페스트, 진입점 및 플러그인이 등록하는 확장 지점을 확인하십시오.
하나를 선택하기 전에 설계를 비교하고 싶다면, Omnigent 멀티 에이전트 하네스가 다른 구조로 동일한 문제를 해결하며, 플러그인을 사용하기 시작하면 그 장단점이 명확해집니다. 하나를 선택하는 대신 두세 개의 하네스를 같은 서버에 유지하게 된다면, 모든 하네스를 하나의 자체 호스팅 API 뒤에 배치하여 포트당 터널을 생성하는 수고를 덜 수 있습니다. 단, 첫날부터 루프백에 바인딩하고 실제 비밀번호를 설정해야 하는 서비스가 하나 더 추가되는 비용이 발생합니다.
가장 먼저 발생하는 문제
Node 버전이 너무 낮습니다. 프로젝트의 메인 브랜치와 0.2.2-alpha.2는 Node 24.9 이상을 요구합니다. CI는 Node 24에서 테스트를 수행하며 Node 24.9와 Node 26에 대한 호환성 검사를 진행하지만, Node 22는 지원하지 않습니다. 0.2.1-rc.4까지의 이전 태그 버전들은 Node 22.19를 허용했으나, 현재 프로젝트는 해당 버전에서 빌드되지 않습니다. 이전 런타임은 코드에서 사용하는 문법과 API를 지원하지 않아 시작 단계에서 실패합니다. 다른 작업을 수행하기 전에 node --version을 실행하십시오.
3080 포트가 이미 사용 중입니다. 두 번째 하니스(harness), 좀비 프로세스, 또는 3080 포트를 사용하는 다른 애플리케이션이 원인일 수 있습니다. ss -tlnp | grep 3080로 해당 프로세스를 찾아 중단하거나, dsh web --port 3180을 사용하여 다른 포트에서 하니스를 시작하십시오. --port는 웹 앱에 할당되므로 web 이후에 실행되어야 합니다.
브라우저가 터널을 통해 연결하지 못합니다. 포트 포워딩은 로컬 노트북에서만 유효하므로, 서버의 공인 IP 주소가 아닌 127.0.0.1으로 접속했는지 확인하십시오. 또한 SSH는 원격지에서 응답 여부와 관계없이 포워딩을 설정하므로, 하니스가 서버에서 정상적으로 리스닝 중인지 확인해야 합니다.
dsh plugin이 즉시 실패합니다. 이 명령어는 pnpm을 래핑한 것이므로, pnpm 바이너리가 없으면 플러그인 작업이 시작되기도 전에 중단됩니다. Node 25 이상에서는 Corepack이 기본적으로 포함되지 않으므로 이러한 현상이 기본 상태입니다.
에이전트가 프로젝트를 인식하지 못합니다. 새로 설치된 웹 UI는 워크스페이스를 추가하기 전까지는 선택된 항목이 없으며, 세션 컴포저도 사용할 수 없습니다. 프로세스는 시작된 디렉터리를 기본 파일 시스템 위치로 사용하므로, WorkingDirectory이 홈 디렉터리로 설정된 유닛은 에이전트가 홈 디렉터리를 가리키게 만듭니다. UI에서 워크스페이스를 선택하거나, 유닛 설정을 수정한 뒤 다시 로드하십시오.
FAQ
DeepSeek Harness 웹 UI를 3080 포트로 노출해도 안전합니까?
아니요, 안전하지 않습니다. 고정된 0.1.0-rc.6에서 웹 서버 자체에는 로그인 기능이 없으며, 배후의 에이전트는 프로세스를 실행한 사용자의 권한으로 파일을 수정하고 셸 명령을 실행합니다. 이때 공급자의 API 키도 동일한 디스크에 저장됩니다. 0.2.0-rc.2부터 0.2.2-rc.1을 포함하여 2026년 11월 12일에 배포된 npm의 latest 릴리스, 그리고 더 최신인 0.2.2-rc.2 프리릴리스까지, 출력되는 시작 URL에는 브라우저가 세션 쿠키로 교환하는 실행 토큰이 포함되어 있습니다. 하지만 해당 URL은 자격 증명 역할을 하며 일반 HTTP는 이를 암호화하지 않고 전송하므로, 이 권고 사항은 변함이 없습니다. 리스너를 127.0.0.1에 유지하고 SSH 터널을 통해 접근하십시오. 사설 오버레이 네트워크를 사용하거나, 포트에 도달하기 전에 모든 요청을 인증하는 리버스 프록시를 사용하는 방법도 유효합니다. 버전 0.1.0-rc.6부터 CLI는 --host 0.0.0.0을 거부하고 사용법 오류와 함께 종료되며, 0.2.2-alpha.2 또한 이를 거부합니다. 이는 개발자들이 이 방식을 어떻게 생각하는지 보여줍니다.
DeepSeek API 키가 필요한가요, 아니면 로컬 모델을 사용할 수 있나요?
둘 다 가능합니다. 이 하네스는 모델이 아니라 런타임이기 때문입니다. 설정(Settings)의 모델(Models) 메뉴에서 DeepSeek 카드나 카탈로그 공급자에 키를 붙여넣거나, "Add model provider"를 선택한 뒤 "Custom model API"를 통해 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 또는 Gemini API를 지원하는 베이스 URL을 입력할 수 있습니다. 로컬 Ollama 서버는 http://127.0.0.1:11434/v1/에서 응답하며 API 키 필드에 어떤 문자열을 입력해도 허용합니다. 키는 $DSH_HOME/.credentials.yaml에 저장되며, 기본 경로는 ~/.dsh/.credentials.yaml입니다.
DeepSeek Harness 플러그인을 설치하면 플러그인에 어떤 권한이 부여됩니까?
하네스를 실행하는 계정의 권한이 그대로 부여됩니다. 플러그인은 동일한 프로세스 내에서 로드되는 Node 코드이며, 확장 지점에는 셸 백엔드, 파일 시스템 계층, 도구 레지스트리, 모든 도구 호출을 감싸는 이벤트가 포함됩니다. 플러그인이 자체적으로 샌드박스를 제공하지 않는 한, 이러한 영역으로부터 플러그인을 격리할 방법은 없습니다. 설치하기 전에 소스 코드를 검토하고, 중요하지 않은 데이터를 소유한 사용자 계정으로 하네스를 실행하십시오.
어떤 버전을 설치해야 하며, 계속 작동할까요?
예를 들어 npx @deepseek-ai/dsh@0.1.0-rc.6 web과 같이 특정 버전을 지정하여 설치하십시오. 이는 여기에 고정된 2026년 8월 버전입니다. 2026년 11월 12일 기준으로 npm의 latest 태그는 0.2.2-rc.1을 가리키고 있으며, GitHub에는 11월 11일에 릴리스된 더 최신 프리릴리스인 0.2.2-rc.2가 올라와 있습니다. 현재 CLI는 Node 24.9 이상을 요구합니다. 이 프로젝트는 스스로를 개발자 프리뷰라고 지칭하며 호환성을 깨뜨리는 변경 사항이 발생할 수 있다고 명시하고 있으므로, 버전을 고정하지 않은 명령은 하루가 다르게 동작이 바뀔 수 있습니다. 업그레이드하기 전에 저장소를 확인하십시오. 버전이 0으로 시작하는 동안에는 설정 키나 플러그인 인터페이스가 변경될 수 있음을 인지해야 합니다.