SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

dsh web: http://127.0.0.1:3080 접속 해결 방법

dsh 실행 시 출력되는 http://127.0.0.1:3080 주소는 웹 UI가 로컬호스트에만 바인딩되어 외부 접근이 차단된 상태임을 의미합니다. 보안상 위험한 전체 인터페이스 노출 대신 SSH 터널링을 사용하여 안전하게 접속하는 방법을 상세히 안내합니다.

dsh web: http://127.0.0.1:3080의 의미

VPS에서 DeepSeek Harness 웹 프로필을 시작하면 다음과 같은 줄이 출력되고 대기 상태가 됩니다.

dsh web: http://127.0.0.1:3080/?token=...

127.0.0.1은 루프백 주소입니다. 이는 기기가 자기 자신과 통신할 때 사용하는 주소입니다. 127.0.0.1에 바인딩된 소켓은 동일한 기기 내의 프로세스로부터 오는 연결만 허용하며, 외부에서는 접근할 수 없습니다. 따라서 해당 줄은 웹 UI가 수신 대기 중인 위치와 접근 권한이 있는 대상을 동시에 알려줍니다. 오직 dsh가 실행 중인 기기에서만 접근할 수 있습니다. 끝에 붙은 ?token= 부분은 프로세스가 시작될 때마다 새로 생성되는 무작위 인증 정보입니다. 이에 대해서는 아래에서 자세히 설명합니다.

이 때문에 노트북의 브라우저에 해당 URL을 붙여넣어도 아무런 반응이 없는 것입니다. 노트북의 127.0.0.1는 노트북 자신을 가리킵니다. Harness는 VPS의 127.0.0.1에서 수신 대기 중이며, 이는 서로 다른 루프백 스택을 가진 별개의 기기입니다. 오류가 발생한 것이 아닙니다. 연결을 외부에서 접근할 수 있도록 전달해야 합니다.

공식 README에는 기본 설정이 명확하게 명시되어 있습니다. "이 명령은 기본적으로 http://127.0.0.1:3080에서 웹 UI를 시작하며, 로컬 실행 시 기본 브라우저를 엽니다." SSH 환경에서는 열 수 있는 브라우저가 없으므로 URL을 직접 사용해야 합니다. 바인딩 주소는 웹 서버 호스트 플러그인인 @deepseek-ai/dsh-host-webserver에서 결정됩니다. 이 가이드에서 사용하는 0.2.0-rc.2 릴리스의 host 키는 "수신 호스트; 지원되는 두 가지 값은 loopback과 all-interfaces입니다"라고 설명되어 있습니다. 설정을 변경하지 않으면 기본적으로 loopback이 적용됩니다. 포트 개념이 생소하다면 Linux의 포트 작동 방식에서 이 모든 것의 기반이 되는 주소와 포트 모델을 확인할 수 있습니다.

웹 UI가 localhost에만 바인딩되는 이유

dsh는 에이전트 하네스로, 모델을 감싸고 있는 프로그램입니다. 이 프로그램은 루프, 도구 호출, 그리고 해당 호출이 실행되는 권한을 제어합니다. 브라우저 탭은 셸 명령을 실행하고, 선택한 작업 디렉터리에서 파일을 읽고 쓰며, 사용자의 모델 API 키를 사용하는 프로세스의 제어 화면입니다. 해당 페이지를 로드할 수 있는 사람은 누구나 dsh을 실행 중인 사용자의 권한으로 이 모든 작업을 수행할 수 있습니다. 네트워크만이 이러한 접근 경로인 것은 아닙니다. 설치한 플러그인 역시 동일한 프로세스 내에서 동일한 권한으로 실행되므로, dsh 플러그인을 설치하기 전에 검증하는 것은 서버가 어떤 포트에서 대기할지 결정하는 것만큼 주의를 기울여야 합니다.

따라서 3080 포트는 읽기 전용 대시보드가 아닙니다. 해당 페이지를 로드하면 서버에서 명령을 실행할 수 있게 됩니다.

출력된 URL을 열면 바로 세션 목록으로 이동합니다. 로그인 화면이나 사용자 계정은 존재하지 않습니다. 페이지 접근을 제어하는 것은 URL 끝에 붙은 토큰입니다. 루트 페이지는 이 토큰을 서명된 세션 쿠키로 교환하고 깔끔한 주소로 리다이렉트합니다. 그 이후부터는 유효한 쿠키 없이 UI가 수행하는 모든 RPC 호출과 WebSocket 스트림은 401 Unauthorized을 반환합니다. 하지만 해당 포트의 모든 항목이 보호되는 것은 아닙니다. Connection 플러그인 문서에 따르면 정적 자산은 공개 상태로 유지되며, 웹 서버 자체에는 서버 전체에 적용되는 인증이나 오리진 정책이 없습니다. 따라서 경로를 소유한 각 플러그인이 자체 규칙을 적용합니다. 이러한 보호된 경로에서 Connection 플러그인은 Host 헤더가 루프백이 아니거나 명시적으로 신뢰한 호스트가 아닐 경우 403를 반환하기도 합니다. 루프백 환경에서 이는 운영 체제가 로컬 프로세스만 통과시키는 실제 접근 제어 뒤의 합리적인 2차 방어선일 뿐, 포트를 공개해야 할 이유가 되지는 않습니다. 토큰은 터미널 스크롤백과 시작 출력을 캡처한 모든 로그에 남아 있습니다. 프로젝트의 리버스 프록시 가이드에서도 호스트 확인이나 광고된 URL이 대기 중인 포트 자체를 보호하지는 않는다고 명시합니다. 웹 서버 문서는 루프백이 아닌 주소에 바인딩하는 것이 "여전히 보호되지 않은 경로와 정적 자산을 해당 네트워크에 노출한다"고 경고합니다. 또한 0.2.0-rc.2 버전의 웹 서버 플러그인은 자체 TLS를 지원하지 않습니다. 자동화된 스캐너가 비표준 포트를 지속적으로 탐색하므로, 3080 포트를 공개하는 즉시 발견된다고 간주해야 합니다.

방화벽에서 3080 포트를 열지 마십시오. 또한 공용 VPS에서 웹 서버 host을 0.0.0.0나 공용 IP로 설정하지 마십시오. 이러한 설정은 서버에 연결하는 누구에게나 유출된 URL 하나만으로 서버 명령 실행 권한을 넘겨주는 결과를 초래합니다.

현재 릴리스는 이미 이러한 방식을 권장하고 있습니다. 웹 애플리케이션의 --host 플래그는 모든 인터페이스에 바인딩하는 것을 거부합니다. 그러나 0.2.0-rc.2 버전에서 웹 서버 플러그인의 host 설정 키는 여전히 0.0.0.0를 허용하므로, 설정을 수정하면 여전히 노출될 수 있습니다. 프로젝트 기본 브랜치의 웹 서버 문서와 npm의 latest 태그가 가리키는 0.2.1-rc.5 릴리스에서는 한 걸음 더 나아가, 로드 시 주소가 지정되지 않으면 거부하고 선택적인 tls 설정을 추가했습니다. 여전히 로컬 인터페이스의 구체적인 주소 하나는 허용하므로, host을 VPS의 공용 IP로 지정하면 UI가 그대로 노출됩니다.

동일한 논리가 서버에 설치하는 모든 에이전트 런타임에 적용됩니다. 이것이 바로 VPS에서 코딩 에이전트를 안전하게 실행하는 방법이 동일한 규칙에서 시작되는 이유입니다. 에이전트의 제어 포트는 비공개로 유지해야 하며, 신뢰할 수 있는 수단을 통해서만 접근해야 합니다.

노트북에서 dsh 웹 UI를 어떻게 여나요?

세 가지 정석적인 방법이 있으며, 각 방법 모두 하네스를 루프백(loopback)에 바인딩된 상태로 유지합니다.

  • SSH 터널을 사용합니다. 공개 인터페이스에서 새로 수신 대기하는 포트가 없으며, 이미 자격 증명을 보유하고 있습니다. 이 방법을 권장합니다.
  • 사설 오버레이 네트워크를 구성합니다. 그러면 UI는 본인의 기기에서만 접근할 수 있고 외부에는 보이지 않게 됩니다.
  • TLS(전송 계층 보안)를 종료하고 비밀번호를 요구한 뒤 요청을 전달하는 리버스 프록시를 사용합니다.

이 방법들의 차이점은 브라우저를 루프백으로 연결하는 방식에 있습니다. 어떤 경우에도 하네스를 루프백에서 이동시켜서는 안 됩니다.

SSH 터널로 접속하기

VPS가 아닌 노트북에서 다음 명령을 실행합니다.

ssh -N -L 3080:127.0.0.1:3080 you@your-vps

명령을 계속 실행해 둔 상태에서, 출력된 전체 URL인 dsh을 토큰이 포함된 http://127.0.0.1:3080/?token=... 형태로 로컬 브라우저에 입력합니다. 웹 UI가 로드되면서 토큰을 세션 쿠키로 교환하고 주소창에서 토큰을 제거합니다. 브라우저가 127.0.0.1:3080을 Host로 전송하는데, 이는 루프백 주소이므로 별도의 설정 없이도 터널이 Host 검사를 통과합니다.

-L 인자는 콜론으로 구분된 세 개의 필드를 가집니다. 첫 번째는 노트북에서 열 포트 번호입니다. 두 번째와 세 번째는 각 연결을 전달할 주소와 포트입니다. 여기서 중요한 점은 중간 필드의 127.0.0.1가 트래픽이 이미 도착한 이후 VPS의 SSH 서버에 의해 해석된다는 것입니다. 즉, 사용자의 루프백이 아니라 VPS의 루프백을 의미합니다. 이것이 바로 dsh이 출력하는 주소이며, 직접 브라우저로 연결할 때는 작동하지 않던 터널이 이 방식으로는 작동하는 이유입니다.

-N은 SSH에게 원격 명령을 실행하지 말라고 지시하므로, 셸 없이 포트 포워딩 기능만 얻게 됩니다. 조용히 실패하지 않고 오류를 명확히 알리는 백그라운드 터널을 만들려면 다음을 사용합니다.

ssh -N -f -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -L 3080:127.0.0.1:3080 you@your-vps

-f은 인증 후 프로세스를 백그라운드로 보냅니다. ExitOnForwardFailure=yes는 생각보다 중요합니다. 이 옵션이 없으면 포워딩 설정에 실패해도 SSH 연결은 성공한 것으로 간주되어, 경고 없이 작동하지 않는 터널과 세션만 남게 됩니다. ServerAliveInterval=30은 30초마다 keepalive 패킷을 보내 카페나 호텔 라우터의 NAT(네트워크 주소 변환) 타임아웃 상황에서도 유휴 터널이 끊기지 않게 합니다.

확인해야 할 사항

VPS에서 실제로 어떤 포트가 리스닝 중인지 확인합니다.

ss -ltnp | grep 3080

정상적인 결과는 루프백 주소를 가리킵니다.

LISTEN 0  511  127.0.0.1:3080  0.0.0.0:*  users:(("node",pid=1042,fd=21))

로컬 주소 열에 0.0.0.0:3080이 표시된다면, 웹 UI가 퍼블릭 인터페이스를 포함한 모든 인터페이스에서 열려 있다는 뜻입니다. 해당 열에 VPS의 공인 IP가 표시되어도 마찬가지로 노출된 상태입니다. 즉시 중단하고 바인딩 설정을 수정하십시오. ss가 소켓은 출력하지만 users: 필드가 비어 있다면, 다른 사용자가 소유한 소켓의 프로세스 이름은 숨겨지므로 sudo를 사용하여 실행하십시오.

터널 시작이 거부될 때

SSH가 다음을 출력하고 종료되는 경우:

bind [127.0.0.1]:3080: Address already in use
channel_setup_fwd_listener_tcpip: cannot listen to port: 3080

이는 서버가 아닌 노트북의 문제입니다. 로컬의 특정 포트 3080을 이미 다른 프로세스(보통 이전에 잊고 둔 터널)가 점유하고 있습니다. 사용 가능한 다른 로컬 포트를 선택하십시오.

ssh -N -L 3081:127.0.0.1:3080 you@your-vps

첫 번째 필드만 변경되었으므로, 이제 http://127.0.0.1:3081/?token=...로 접속합니다. 토큰은 동일하게 사용하며, 하네스는 여전히 3080 포트에서 리스닝 중입니다. 두 포트 번호가 일치할 필요는 없습니다. 세션 쿠키는 주소창의 호스트와 포트에 종속되므로, 로컬 포트가 바뀌면 토큰이 포함된 URL을 다시 입력해야 합니다.

터널은 올라왔지만 브라우저에서 연결 거부나 빈 응답이 발생한다면, 트래픽은 VPS까지 도달했으나 목적지에서 아무것도 찾지 못한 것입니다. dsh이 종료되었거나 다른 포트에 바인딩되었을 가능성이 큽니다. 서버에서 ss -ltnp | grep 3080로 확인하십시오. 만약 페이지가 401 Unauthorized이라는 응답을 보낸다면 터널은 정상이며, 브라우저에 해당 주소에 대한 유효한 쿠키가 없는 상태입니다. 토큰이 포함된 URL을 다시 여십시오. 프로세스가 재시작될 때마다 새로운 토큰이 생성되므로, 새로 출력된 URL을 사용해야 합니다.

한 가지 더 주의할 점이 있습니다. 포그라운드에서 실행 중인 npx @deepseek-ai/dsh web는 셸이 닫히면 함께 종료되므로, 로그아웃하는 순간 하네스도 멈춥니다. tmux 내부에서 실행하거나 systemd 사용자 서비스로 등록하십시오. 이는 VPS에서 코딩 에이전트 계속 실행하기에서 다루는 문제와 동일합니다. systemd를 사용하면 dsh web: 라인과 토큰 정보가 서비스 로그에 기록되므로 거기서 확인하면 됩니다. SSH 설정을 다루는 김에 VPS의 SSH 보안 강화하기를 먼저 수행하는 것을 권장합니다. 터널을 사용하면 SSH 로그인이 에이전트로 향하는 유일한 통로가 되기 때문입니다.

사설 오버레이 네트워크를 통한 접근

오버레이 네트워크를 사용하면 VPS와 노트북에 본인의 기기만 참여할 수 있는 사설 네트워크 주소를 부여할 수 있습니다. Tailscale이 일반적으로 사용되는 선택지이며, serve 명령어가 이 경우에 정확히 부합합니다. tailscaled은 VPS에서 실행되어 localhost:3080 자체에 연결되므로, 하네스는 루프백 인터페이스에서 유지됩니다.

tailscale serve --bg localhost:3080
tailscale serve status

이제 공개 인터페이스에 포트를 열지 않고도 HTTPS를 통해 tailnet 내 기기 이름으로 UI에 접근할 수 있습니다. 이를 위해서는 tailnet에 대한 HTTPS 인증서가 활성화되어 있어야 하며, 그렇지 않으면 serve가 제시할 인증서가 없습니다. 브라우저가 이제 해당 tailnet 이름을 Host로 전송하므로, 이름을 신뢰하도록 하네스를 시작해야 합니다. 그렇지 않으면 API 호출 시 403 오류가 발생합니다. 포트 번호가 없는 항목은 모든 포트와 일치합니다.

npx @deepseek-ai/dsh@0.2.0-rc.2 web --trusted-host your-vps.your-tailnet.ts.net

그런 다음 출력된 줄에서 토큰을 가져와 https://your-vps.your-tailnet.ts.net/?token=...을 엽니다. 다시 종료하려면 off 옵션을 사용하여 명령어를 반복하십시오.

tailscale serve --https=443 off

serve를 사용하고, funnel은 절대 사용하지 마십시오. Funnel은 동일한 대상을 공용 인터넷에 게시하며, 이는 URL 토큰 외에는 아무런 보호 장치 없이 열린 포트에 에이전트 런타임을 노출하는 결과를 초래합니다. 두 명령어는 매우 비슷해 보이지만 정반대의 작업을 수행하므로, 명령어를 입력하기 전에 Tailscale Serve와 Funnel의 차이점을 읽어보시기 바랍니다. 사설 네트워크로서의 Tailscale에서 설정 방법 전반을 다룹니다.

비밀번호 인증을 거치는 리버스 프록시로 접근하기

이 방식은 포트를 인터넷에 실제로 공개하므로, 서버의 명령 실행 권한을 외부인으로부터 보호하는 유일한 수단은 인증뿐입니다. 여러 사람이 UI를 사용해야 하고 각자 터널을 연결하기 어려운 경우에 이 방식을 선택하십시오.

harness는 127.0.0.1:3080에서 실행됩니다. nginx가 같은 서버에서 동작하므로 루프백 주소로 접근할 수 있으며, 인증서와 비밀번호 파일을 사용하여 443 포트에서 대기합니다.

server {
    listen 443 ssl;
    server_name dsh.example.com;

    ssl_certificate     /etc/letsencrypt/live/dsh.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dsh.example.com/privkey.pem;

    auth_basic           "dsh";
    auth_basic_user_file /etc/nginx/dsh.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:3080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

비밀번호 파일을 생성하고 설정을 다시 불러옵니다:

sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/dsh.htpasswd you
sudo nginx -t && sudo systemctl reload nginx

nginx -t 명령은 syntax is ok에 이어 test is successful를 출력해야 합니다. 파일에 오류가 있는 상태에서 설정을 다시 불러오면 실패하며 기존 설정이 유지되므로, 무작정 재시작하기보다 오류 메시지를 먼저 확인하십시오.

프록시 설정의 세 줄은 단순한 장식이 아닙니다. Upgrade 및 Connection 헤더는 WebSocket 핸드셰이크를 허용하며, 이 설정이 없으면 페이지는 로드되지만 업데이트되지 않습니다. proxy_read_timeout 3600s는 nginx의 비활성 타임아웃을 60초에서 1시간으로 늘려주며, 에이전트 실행의 전체 길이를 제한하지는 않습니다. 고정된 0.2.0-rc.2 버전은 기본적으로 2초마다 WebSocket 핑을 보내므로 긴 에이전트 작업 중에도 연결이 유지됩니다. proxy_buffering off은 프록시된 HTTP 응답의 버퍼링을 비활성화하며, WebSocket 프레임은 제어하지 않습니다. nginx 리버스 프록시 설정 줄별 설명에서 나머지 내용을 확인할 수 있으며, nginx, Caddy, Traefik 선택하기에서는 자동 인증서를 사용하는 동일한 설정을 다룹니다.

harness 역시 프록시 정보를 알고 있어야 합니다. dsh을 시작할 때 proxy_set_header Host $host을 사용하여 브라우저가 인식하는 도메인 이름을 그대로 전달해야 합니다. 프로젝트의 프록시 가이드에서 요구하는 방식이며, 그렇지 않으면 403 오류가 발생합니다:

npx @deepseek-ai/dsh@0.2.0-rc.2 web --trusted-host dsh.example.com

각 사용자는 dsh web: 줄에 있는 토큰을 사용하여 https://dsh.example.com/?token=...에 한 번 접속하며, 이후 브라우저가 세션 쿠키를 유지합니다. 백엔드는 Secure 플래그 없이 쿠키를 설정하며, 프록시 가이드에서는 HTTPS 환경에서 프록시가 해당 플래그를 추가하도록 권장합니다. nginx 1.19.3 이상 버전에서는 location 블록 내의 proxy_cookie_flags ~ secure; 설정으로 이를 수행할 수 있습니다.

어떤 프록시를 선택하든 3080 포트는 방화벽에서 닫아두어, 인증된 경로로만 접근할 수 있도록 하십시오. ufw 방화벽 기초에서 관련 규칙을 다룹니다. TLS를 통한 기본 인증은 최소한의 보안 조치일 뿐 완벽한 보안 모델은 아닙니다. 비밀번호와 토큰 URL을 가진 사람은 누구나 서버의 셸 권한을 얻을 수 있습니다. 가능하다면 터널 방식을 우선적으로 사용하십시오.

dsh web이 수신하는 포트는 어떻게 변경합니까?

--port는 런처가 아닌 웹 애플리케이션에 속합니다. CLI 문서에서 직접 예시를 확인할 수 있습니다.

dsh --profile web --port 8080

dsh web은 --profile web의 별칭이므로 dsh web --port 8080는 동일한 명령어입니다. 런처는 자신의 플래그만 파싱하고 그 뒤에 오는 모든 내용을 부팅된 프로필로 전달합니다. 따라서 런처 플래그가 먼저 와야 하며, 런처가 인식하지 못하는 첫 번째 토큰부터 애플리케이션 인자로 간주합니다. --port은 반드시 프로필 뒤에 배치하십시오.

서버가 실제로 바인딩한 주소와 필요한 토큰을 출력하는 줄을 확인하십시오. 추측하지 말고 명령어가 출력하는 URL을 읽어야 합니다. 그런 다음 터널의 마지막 필드를 그에 맞게 업데이트하십시오.

ssh -N -L 3080:127.0.0.1:8080 you@your-vps

영구적으로 변경하려면 명령줄 대신 프로필 설정에서 포트를 지정해야 합니다. web 및 headless 프로필은 처음 사용할 때 ~/.dsh 아래의 기본 템플릿에서 자동으로 초기화됩니다. 이 디렉터리에는 API 키와 모델 엔드포인트 설정도 포함되어 있으므로, 파일을 수정하는 김에 dsh 키, 모델 및 엔드포인트 설정하기를 함께 읽어보는 것이 좋습니다. 모든 계층이 구성된 후 실제로 적용된 설정을 확인하려면 다음 명령어를 사용하십시오.

dsh --dump-config

수신 주소는 웹 서버 플러그인의 host 및 port이라는 두 키에서 결정됩니다. 0.2.0-rc.2 버전에서 다른 키들은 응답 압축을 조정하는 역할만 하며, 0.2.1-rc.2 버전과 기본 브랜치에는 선택 사항인 tls 키가 추가되었습니다. port을 0로 설정하면 운영 체제에 사용 가능한 포트를 요청하게 되며, 이는 "0은 OS가 할당한 포트를 요청함"으로 문서화되어 있습니다. 이 방식은 포트 충돌을 방지할 수 있지만, 재시작할 때마다 번호가 바뀌므로 터널 설정에는 적합하지 않습니다.

왜 dsh가 address already in use 오류를 발생시키나요?

다른 프로세스가 이미 해당 주소와 포트를 점유하고 있어 커널이 두 번째 bind 요청을 거부하기 때문입니다. 노드에서는 다음과 같이 보고합니다.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3080

설정을 변경하기 전에 점유 중인 프로세스를 찾으십시오.

sudo ss -ltnp | grep 3080

users:(("node",pid=1042,fd=21)) 필드는 프로세스 이름과 PID를 나타냅니다. 보통은 종료되었다고 생각한 이전 dsh가 여전히 분리된 tmux 창에서 실행 중인 경우가 많습니다. kill 1042을 사용하여 해당 프로세스를 중지하거나, 새로운 인스턴스를 다른 포트에서 시작하십시오. 127.0.0.1:3080와 0.0.0.0:3080은 서로 충돌한다는 점에 유의하십시오. 모든 인터페이스에 바인딩하는 작업이 이미 루프백까지 포함하기 때문입니다.

버전을 고정하십시오. 개발자 프리뷰 단계입니다

README는 DeepSeek Harness가 개발자 프리뷰 단계이며 빠르게 반복 개선되고 있고, 호환성을 깨뜨리는 변경 사항이 발생할 것임을 명확히 밝히고 있습니다. 이러한 속도 때문에 망설여진다면, dsh와 Claude Code 및 Omnigent 비교를 통해 동일한 곡선상의 서로 다른 지점에 있는 두 도구와 비교해 보십시오.

버전을 지정하지 않은 npx @deepseek-ai/dsh web는 버전을 명시하지 않으므로 어떤 빌드가 실행될지 제어할 수 없습니다. npm 문서에 따르면 지정자가 없는 패키지 이름은 "로컬 프로젝트에 존재하는 버전과 일치"하며, 프로젝트에 없는 패키지는 npm 캐시 폴더에 설치됩니다. 어떤 빌드가 실행될지는 해당 머신에 무엇이 있는지에 따라 달라지므로, 재시작 시 테스트했던 것과 다른 플래그를 가진 CLI가 실행될 수 있습니다. 재시작이 업그레이드로 이어지지 않도록 버전을 고정하십시오.

npx @deepseek-ai/dsh@0.2.0-rc.2 web

2026년 11월 기준(2026-11-01 확인), npm latest 태그는 2026-10-30에 GitHub에 릴리스된 0.2.1-rc.5을 가리킵니다. GitHub 기록에 따르면 0.2.1-rc.4은 2026-10-28 02:49 UTC에 릴리스되었으며, 이는 2026-10-23 15:26 UTC에 릴리스된 0.2.1-rc.3보다 약 4일 11시간 뒤입니다. 따라서 로컬 복사본이 없는 머신에서 단순히 npx @deepseek-ai/dsh을 실행하면 이 가이드에서 고정한 빌드가 아닌 0.2.1 릴리스 후보 버전이 설치됩니다. 이 가이드에서 고정한 0.2.0-rc.2은 2026-09-29에 GitHub에 릴리스되었습니다. 8월에 고정했던 0.1.0-rc.7 빌드는 이제 0.1 라인의 나머지 버전과 0.2 버전을 거쳐 여러 프리뷰 릴리스 뒤처져 있습니다. 수락하기 전에 단순히 npx을 실행했을 때 무엇이 설치되는지 확인하십시오.

npm view @deepseek-ai/dsh version

npm view @deepseek-ai/dsh dist-tags는 모든 태그를 한 번에 나열하므로, 버전을 고정하기 전에 릴리스 후보와 알파 버전을 구분할 수 있습니다.

고정된 버전이 설치되지 않거나, 새 버전을 고정했음에도 npx가 계속 이전 빌드를 실행한다면 설치 및 버전 오류 해결 방법을 참조하여 npx 캐시를 비우고 Node에 번들된 npm 버전을 확인하십시오.

프리뷰 릴리스가 진행되면서 런처와 웹 애플리케이션 간에 플래그가 이동합니다. --port이 이 가이드의 설명과 다르게 동작한다면, 추측하지 말고 애플리케이션에 직접 플래그 목록을 요청하십시오.

dsh --profile web --help

설치 자체와 워크스페이스 설정, 모델 키에 대해서는 VPS에 DeepSeek Harness 설치하기를 참조하십시오. 액세스 단계만 간략히 확인하려면 VPS에서 dsh 웹 UI 접속하기에서 이유를 제외한 터널링 설정 방법을 다룹니다.

FAQ

노트북 브라우저에서 http://127.0.0.1:3080에 접속할 수 없는 이유는 무엇입니까?

127.0.0.1은 현재 사용 중인 컴퓨터를 의미하기 때문입니다. DeepSeek Harness Web UI는 VPS의 루프백 주소에 바인딩되어 있으므로, VPS 내부의 프로세스만 연결할 수 있습니다. 노트북은 별도의 루프백을 가지고 있으며, 해당 기기의 3080 포트에는 아무것도 대기 중이지 않습니다. ssh -N -L 3080:127.0.0.1:3080 you@your-vps을 사용하여 SSH로 포트를 포워딩한 다음, 출력된 전체 URL인 http://127.0.0.1:3080/?token=...를 로컬에서 불러오십시오. -L 인수의 중간 필드는 서버 측에서 해석되므로, 이를 통해 하네스(harness)를 가리키게 됩니다. 토큰을 제외하면 브라우저가 세션 쿠키를 가질 때까지 401 Unauthorized 상태가 됩니다.

공용 VPS에서 dsh Web UI를 0.0.0.0에 바인딩하는 것은 안전합니까?

아니요, 안전하지 않습니다. Web UI는 dsh를 실행하는 사용자의 권한으로 셸 명령을 실행하고 파일을 수정하는 에이전트의 제어 인터페이스입니다. 사용자 계정이나 로그인 화면이 없으며, 유일한 자격 증명은 출력된 URL에 포함된 토큰뿐입니다. 정적 자산은 토큰 없이 제공되며, 프로젝트 문서에서도 해당 포트는 보호되지 않는다고 명시하고 있습니다. 공용 IP의 모든 인터페이스에 바인딩하면 3080 포트에 접근할 수 있는 누구나 URL 하나만 알아내도 서버에서 명령을 실행할 수 있게 됩니다. 공용 IP에 직접 바인딩하는 것도 동일한 위험을 초래합니다. 127.0.0.1에 바인딩을 유지하고, 방화벽에서 3080 포트를 닫아두며, SSH 터널, 사설 오버레이 네트워크 또는 비밀번호 인증이 필요한 리버스 프록시를 사용하십시오.

SSH 세션을 종료한 후에도 dsh Web UI를 계속 실행하려면 어떻게 해야 합니까?

포그라운드에서 실행되는 npx @deepseek-ai/dsh web는 로그인 셸의 자식 프로세스이므로, 셸이 종료되면 함께 종료됩니다. tmux 세션 내에서 시작하고 Ctrl-b d으로 분리하거나, lingering이 활성화된 systemd 사용자 서비스로 실행하십시오. 터널과 하네스는 독립적입니다. 하네스의 부모 프로세스가 로그인 세션보다 오래 유지되는 한, 실행 중인 하네스를 건드리지 않고도 SSH 터널을 자유롭게 끊거나 다시 연결할 수 있습니다.

nginx 뒤에서 긴 에이전트 작업을 수행할 때 dsh Web UI가 중간에 멈추는 이유는 무엇입니까?

WebSocket 연결 상태와 nginx 오류 로그를 확인하십시오. nginx의 기본 proxy_read_timeout은 읽기 간격 60초이지만, 0.2.0-rc.2 버전은 기본적으로 2초마다 WebSocket 핑을 보내므로 긴 에이전트 단계만으로는 타임아웃이 발생하지 않습니다. proxy_read_timeout 3600s;은 비활성 허용 시간을 1시간으로 늘려줍니다. proxy_buffering off;는 HTTP 응답에 대한 버퍼링을 비활성화하지만 WebSocket 프레임에는 적용되지 않습니다. WebSocket 핸드셰이크가 성공하도록 proxy_http_version 1.1;를 사용하여 Upgrade 및 Connection 헤더를 전달하십시오. 해당 헤더가 없으면 페이지는 로드되지만 업데이트를 전혀 받을 수 없습니다.

이 글이 도움이 되었나요?