SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor · 업데이트됨 2026-11-07

VPS에서 dsh를 systemd 서비스로 실행하는 방법

VPS에서 dsh를 헤드리스로 실행하기 위한 systemd 유닛 파일 설정법을 안내합니다. 전용 계정 생성, 자동 재시작 규칙, journalctl 로그 확인 및 SSH 터널링을 통해 DeepSeek Harness를 안정적으로 운영하는 방법을 확인하십시오.

터미널이 아닌 VPS에서 dsh를 헤드리스로 실행하기

VPS에서 dsh를 헤드리스로 실행하려면 systemd 유닛 파일 하나와 이를 소유할 전용 계정이 필요합니다. dsh는 2026년 8월 개발자 프리뷰로 MIT 라이선스 하에 공개된 DeepSeek의 에이전트 런타임인 DeepSeek Harness의 명령줄 실행 도구입니다. 하네스(harness)는 모델 자체가 아니라 모델을 둘러싼 프로그램을 의미하므로, systemd로 관리하는 대상은 DeepSeek의 추론 엔진이 아니라 루프, 도구 및 권한입니다. 퀵스타트 가이드에서는 npx @deepseek-ai/dsh web을 입력하라고 안내하는데, 이는 올바른 방법이지만 SSH(secure shell) 세션을 종료하는 즉시 프로세스가 종료됩니다.

유닛 파일은 다음 네 가지 문제를 한 번에 해결합니다. 서비스가 재부팅 후 자동으로 다시 시작됩니다. 출력 내용이 화면을 지나쳐 사라지지 않고 저널(journal)에 기록됩니다. root가 아닌 별도의 계정으로 실행됩니다. 또한 선택한 특정 버전으로 실행되는데, 이는 업스트림에서 다음과 같이 강조하듯 매우 중요합니다.

DeepSeek Harness는 현재 개발자 프리뷰 단계이며 빠르게 반복 개선되고 있습니다. 호환성을 깨뜨리는 변경 사항이 발생할 것입니다.

이 가이드는 dsh가 이미 수동으로 정상 작동함을 전제로 합니다. 만약 작동하지 않는다면 VPS에 DeepSeek Harness 설치하기를 먼저 수행한 뒤 npx @deepseek-ai/dsh web이 페이지를 정상적으로 제공하는지 확인하고 돌아오십시오.

먼저 Node를 확인해야 합니다. npm 경고만으로는 충분하지 않습니다

node -v

Ubuntu 24.04의 기본 패키지는 Node 18입니다(2026년 8월 기준 18.19.1). 올해 게시된 패키지를 사용하기에는 오래된 버전입니다. npm 자체도 Node 버전을 확인합니다. npm 문서에 따르면 패키지의 engines 필드는 engine-strict를 활성화하지 않으면 "경고만 표시"합니다. 게시된 @deepseek-ai/dsh 매니페스트에는 engines 필드가 전혀 없습니다(2026년 10월 27일에 0.1.0-rc.7, 0.2.1-rc.2, 0.2.1-rc.4에서 확인). 저장소에는 해당 필드가 선언되어 있습니다. 그러나 npm은 의존성의 engine 요구 사항도 확인합니다. 고정된 0.2.1-rc.2 릴리스는 commander: ^15.0.0를 선언하고, Commander 15는 Node >=22.12.0을 요구합니다. 따라서 Ubuntu의 Node 18에 설치하면 일반적인 npm 설정에서 EBADENGINE 경고가 발생합니다. 기본적으로 이 경고가 설치를 중단하지는 않습니다. 따라서 런타임 오류가 발생하기 전에 Node 버전을 확인해야 합니다.

저장소가 요구하는 최저 버전도 올라갔습니다. 0.2.1-rc.2 소스는 ^22.19.0 || >=24.0.0을 허용하지만, 현재 master 브랜치의 CLI 패키지는 >=24.9.0를 선언하며 Node 22는 이를 충족하지 못합니다. NodeSource에서 Node 24를 설치합니다. Node 24는 장기 지원(LTS) 계열이며 2026년 10월 20일부터 유지 관리 단계에 있습니다. 현재 빌드는 두 요구 범위를 모두 충족합니다. Node.js 릴리스 일정에 따르면 Node 26은 2026년 10월 28일에 LTS가 되었습니다.

curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/nodesource_setup.sh
less /tmp/nodesource_setup.sh
sudo -E bash /tmp/nodesource_setup.sh
sudo apt install -y nodejs
node -v

node -v는 이제 24.9.0 이상인 v24 버전을 출력해야 합니다. less 줄을 추가한 이유는 원격 스크립트를 그대로 bash에 파이프하면 읽지 않은 코드를 실행하게 되기 때문입니다.

unit 파일을 작성하기 전에 실행을 확인합니다

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

이 프로세스를 실행한 상태로 둡니다. 두 번째 SSH 세션에서 다음을 실행합니다.

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/

HTTP 상태 코드가 반환되면 웹 프로필이 loopback에서 수신 대기 중이라는 뜻입니다. 이 프로필은 기본적으로 loopback에 바인딩됩니다. 401를 예상할 수 있으며, 이는 성공으로 처리합니다. UI는 출력된 URL의 launch token으로 브라우저를 인증하고, 이 토큰을 서명된 세션 쿠키로 교환합니다. 따라서 둘 다 포함하지 않은 요청은 401을 반환합니다. 000과 curl: (7) Failed to connect to 127.0.0.1 port 3080이 함께 나타나면 프로세스가 수신 대기 중이지 않다는 뜻이며, 첫 번째 터미널에 그 원인이 표시됩니다. 다음 단계로 진행하기 전에 Ctrl+C로 수동 실행을 중지합니다. 이미 다른 프로세스가 사용 중인 포트에 바인딩하려는 unit은 Error: listen EADDRINUSE: address already in use 127.0.0.1:3080와 함께 실패합니다.

0.1.0-rc.7은 18 August 2026에 공개된 버전이며, 이 가이드에서 사용하는 브라우저 인증보다 이전 버전입니다. 해당 Connection README는 이 차단 기능이 연결 가능성을 제어하는 정책이며 "the Web carrier provides no authentication layer"라고 설명합니다. 11 October 2026에 latest 태그는 0.2.0-rc.2를 가리켰습니다. 27 October 2026에는 latest이 0.2.1-rc.2을, next가 0.2.1-rc.4을 가리켰으므로 여기의 명령은 0.2.1-rc.2을 고정합니다. 4 November 2026의 npm 버전 목록에는 latest과 next가 모두 0.2.1-rc.5으로 표시됩니다. 여기의 명령은 기존 pin을 유지합니다. npm view @deepseek-ai/dsh version로 현재 버전을 확인한 다음, 실행할 버전을 결정하고 고정합니다.

고정한 버전을 전역으로 설치합니다

npx은 unit 파일 안에서 사용하면 안 되는 도구다. 버전을 지정하지 않았거나 일치하는 로컬 설치가 없으면 프로세스가 시작될 때 패키지 버전을 확인한다. 따라서 3개월 후 재시작할 때 사용자가 아무것도 변경하지 않았어도 preview 단계 agent의 다른 빌드가 실행될 수 있다. 누락된 패키지나 캐시 데이터가 필요한 경우에도 npm registry가 필요하다. 그러면 registry가 느릴 때 시작이 지연되거나 실패할 수 있다. npm은 캐시를 사용한 실행과 오프라인 실행도 지원한다. 한 번만 설치하고, 기록해 둔 버전을 사용한다.

sudo npm install -g @deepseek-ai/dsh@0.2.1-rc.2
command -v dsh
npm ls -g --depth=0 @deepseek-ai/dsh

command -v dsh은 npm이 NodeSource에서 설치된 경우 /usr/bin/dsh을 출력하고, Ubuntu 자체 패키지에서 설치된 경우 /usr/local/bin/dsh을 출력한다. unit 파일에는 실제로 출력된 경로를 사용한다. npm ls -g은 정확한 버전을 출력한다. 6주 후 동작이 변경되었을 때 무엇을 설치했는지 기억하지 못하더라도 확인할 수 있는 값이다. 설치가 실패하거나, 이후 command -v dsh이 아무것도 출력하지 않거나, 반환된 버전이 요청한 버전과 다르면 unit 파일을 작성하기 전에 일반적인 dsh 설치 및 버전 문제를 해결한다.

서비스만 소유하는 사용자

에이전트는 셸 명령을 실행한다. 이것이 에이전트의 역할이다. 에이전트를 root로 실행하면 모든 도구 호출이 root 권한으로 수행되므로, 로그인 셸이 없는 전용 계정을 만든다.

sudo useradd --system --create-home --home-dir /var/lib/dsh --shell /usr/sbin/nologin dsh
sudo install -d -o dsh -g dsh -m 750 /var/lib/dsh/harness /var/lib/dsh/workspace
id dsh

/var/lib/dsh/harness는 dsh가 프로필을 저장하는 디렉터리인 DSH_HOME가 된다. 프로필은 이름이 지정된 플러그인 번들 스택이며, 그 위에 사용자가 작성한 패치 계층이 추가된다. web 프로필과 headless 프로필은 처음 부팅할 때 제공된 템플릿으로부터 자체적으로 생성된다. 이후 이 스택에 추가하는 항목은 에이전트 자체의 파일 및 셸 접근 권한으로 이 사용자로 실행된다. 따라서 플러그인을 설치하기 전에 검토하는 작업은 계정을 만드는 작업과 같은 범주에 속한다. 최초 부팅에서는 파일을 작성하고 번들을 가져올 수 있으므로, 가능한 경우 실행 과정을 확인하면서 수동으로 수행한다.

sudo -u dsh env HOME=/var/lib/dsh DSH_HOME=/var/lib/dsh/harness /usr/bin/dsh --profile web

HOME를 명시적으로 설정한다. sudo가 이를 처리하는 방식에 의존하지 않아야 한다. sudo가 HOME을 유지할지 다시 작성할지는 /etc/sudoers의 env_reset, env_keep, always_set_home 등을 포함한 설정에 따라 달라진다. 잘못 설정하면 최초 실행에서 사용자의 홈 디렉터리를 캐시와 상태 저장에 사용하려 한다. 이로 인해 권한 오류가 발생하거나, 나중에 서비스가 사용하지 않을 위치에 상태가 저장될 수 있다. curl 확인 결과에 상태 코드가 출력되면 Ctrl+C로 중지한다.

유닛 파일

다음을 작성합니다. /etc/systemd/system/dsh.service:

[Unit]
Description=DeepSeek Harness (dsh) web profile
Documentation=https://github.com/deepseek-ai/deepseek-harness
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=5

[Service]
Type=exec
User=dsh
Group=dsh
WorkingDirectory=/var/lib/dsh/workspace
Environment=HOME=/var/lib/dsh
Environment=DSH_HOME=/var/lib/dsh/harness
ExecStart=/usr/bin/dsh --profile web
Restart=on-failure
RestartSec=5s
TimeoutStopSec=30s
SyslogIdentifier=dsh
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target

ExecStart=에는 command -v dsh에서 확인한 절대 경로를 지정합니다. systemd는 명령 이름만 지정된 경우 고정된 경로 목록에서 검색하지만, 이 목록은 셸의 PATH가 아닙니다. 따라서 절대 경로를 지정하면 추측할 필요가 없습니다.

WorkingDirectory=는 상대 경로가 해석되는 기준 디렉터리이며, 인수 없이 ls을 실행하는 도구 호출이 시작되는 위치입니다. 에이전트에 제공할 작업 공간을 이 디렉터리로 지정합니다. 디렉터리가 없거나 서비스 사용자가 해당 디렉터리에 들어갈 수 없으면 dsh가 실행되기도 전에 유닛이 status=200/CHDIR과 함께 실패합니다.

ProtectHome=true는 프로세스에서 /home 및 /root을 숨깁니다. 서비스가 접근하는 모든 항목이 /var/lib/dsh 아래에 있으므로 여기서는 안전합니다. 작업 공간을 /home 아래의 경로로 지정하면 에이전트는 해당 디렉터리가 없다고 보고합니다. 이 줄을 기억하지 못하면 원인을 파악하기 어렵습니다. ProtectSystem=full은 /usr, /boot 및 /etc을 읽기 전용으로 설정하며, 서비스는 여기에 쓸 필요가 없습니다.

더 엄격하게 제한하고 싶은 마음이 들 수 있지만, 대개는 잘못된 설정입니다. ProtectSystem=strict은 kernel pseudo-filesystem을 제외한 전체 filesystem을 읽기 전용으로 설정하고, 이 유닛의 PrivateTmp=true에 따라 /tmp 및 /var/tmp을 쓰기 가능한 예외로 둡니다. 따라서 workspace에 쓰는 작업은 EROFS: read-only file system과 함께 실패합니다. 이 수준의 제한이 필요하다면 같은 편집에서 ReadWritePaths=/var/lib/dsh를 추가합니다.

어떤 Type=을 사용해야 하는가

Type=exec를 사용해야 합니다. dsh는 포그라운드에서 실행되며 포크(fork)를 하지 않기 때문입니다. 기본값 대신 이 설정을 사용하면 실제 오류 메시지를 확인할 수 있다는 장점이 있습니다. Type=simple을 사용하면 systemd는 프로세스가 포크되자마자 시작이 성공했다고 간주합니다. 바이너리 파일의 존재 여부조차 확인하기 전이므로 systemctl start dsh는 정상 종료된 것처럼 보이고, 실패 여부는 저널에서만 확인할 수 있습니다. Type=exec를 사용하면 systemd는 execve()이 성공할 때까지 기다립니다. 따라서 ExecStart=에 오타가 있으면 방금 입력한 명령어가 즉시 실패하며, 그 결과를 바로 확인할 수 있습니다.

잘못된 두 가지 설정은 모두 프로세스를 멈추게 만듭니다. Type=forking은 systemd에게 부모 프로세스가 종료될 때까지 기다리라고 지시하는데, dsh는 종료되지 않으므로 TimeoutStartSec가 만료될 때까지(기본값 90초) 시작 과정이 차단된 후 Job for dsh.service failed because a timeout was exceeded. 오류를 보고합니다. Type=notify은 sd_notify을 통해 READY=1 메시지를 기다리는데, 이를 보내지 않는 Node 프로세스는 동일한 방식으로 멈춰 버립니다. systemd 서비스 타입 전체 비교 문서에서 notify를 구성할 가치가 있는 경우를 포함한 나머지 내용을 다룹니다.

실패를 명확히 드러내는 재시작 규칙

Restart=on-failure은 0이 아닌 종료 코드로 종료되거나 정상적이지 않은 신호로 종료되면 재시작하고, 정상적으로 종료되면 unit을 그대로 중지 상태로 둔다. systemd는 이 서비스 유형에서 SIGHUP, SIGINT, SIGTERM, SIGPIPE을 정상 종료 신호로 처리한다. 프리뷰 빌드에는 이 동작이 적합하다. dsh가 마음에 들지 않는 설정을 읽은 뒤에도 0으로 종료하면 unit은 중지되고 중지 상태를 유지하며, systemctl status dsh에서 inactive (dead)를 확인할 수 있다. Restart=always을 사용하면 같은 이벤트가 재시작 루프로 바뀌므로 겉으로는 정상적으로 동작하는 것처럼 보인다.

속도 제한은 자주 빠지는 부분이다. systemd의 기본값은 10초 동안 5회 시작하는 것이다. RestartSec=5s을 사용하면 10초 동안 5회 시작하는 상황에 도달하지 않으므로, 시작 시 충돌하는 unit이 계속 재시작되고 이 사실은 journal에서만 확인할 수 있다. StartLimitIntervalSec=300와 StartLimitBurst=5을 함께 사용하면 5분 동안 5회 시작할 수 있으며, 그 간격 안에서는 추가 시작을 거부한다. systemd는 재시작을 포기하고 unit을 failed 상태에 둔 뒤 Start request repeated too quickly.를 기록한다. 원인을 수정한 후에는 sudo systemctl reset-failed dsh로 이 상태를 해제한다. 두 설정은 [Unit]에 지정해야 하며 [Service]에 지정하면 안 된다. 인식하지 못한 옵션은 조용히 무시되지 않고 경고 로그를 생성한다.

서비스 시작 및 확인

sudo systemctl daemon-reload
sudo systemctl enable --now dsh
systemctl status dsh

enable --now는 두 가지 역할을 수행합니다. enable는 재부팅 후 서비스를 다시 시작하게 만들며, --now는 현재 부팅 세션에서 서비스를 시작합니다. systemctl start만 단독으로 사용하면 다음 재부팅 시 서비스가 유지되지 않으며, 커널 업데이트 등으로 인해 재부팅이 발생할 수 있습니다.

systemctl status dsh을 실행하면 Active: active (running), Main PID, 그리고 Memory: 항목이 표시되어야 합니다. 그 후 서비스가 어느 주소에서 대기 중인지 확인하십시오.

sudo ss -lntp | grep 3080

127.0.0.1:3080이 표시되어야 합니다. 만약 다른 주소가 보인다면, --host 플래그가 리스너를 해당 주소가 속한 네트워크로 이동시킨 것입니다. 이 경우 TLS가 설정되지 않았다면 일반 HTTP로 서비스됩니다. 해당 출력에 나타나는 프로세스 이름은 dsh가 아니라 node입니다. dsh 바이너리는 Node 스크립트이므로 pgrep -x dsh으로는 아무것도 찾을 수 없습니다. 대신 systemctl show -p MainPID dsh을 사용하십시오.

그다음 한 번 재부팅하십시오. 재부팅 후에도 정상적으로 동작하지 않는 서비스는 아직 완성된 서비스가 아닙니다.

sudo reboot

다시 접속하여 systemctl is-active dsh을 실행하십시오. 그러면 active가 출력됩니다.

journalctl로 로그 읽기

dsh가 stdout과 stderr에 기록하는 모든 내용은 unit 이름으로 journal에 저장된다.

journalctl -u dsh -f
journalctl -u dsh -n 200 --no-pager
journalctl -u dsh --since "10 min ago" -p err

-f은 새 줄을 계속 표시하고, -n은 마지막 N개 항목을 표시하며, -p err는 priority로 필터링한다. unit에 설정된 SyslogIdentifier=dsh 때문에 해당 줄이 node이 아니라 dsh으로 태그된다. unit으로 필터링하지 않은 journal 출력을 처음 읽을 때 이 차이가 중요하다.

필요해지기 전에 journal이 재부팅 후에도 유지되는지 확인한다.

journalctl -u dsh -b -1

출력 결과가 Specifying boot ID or boot offset has no effect, no persistent journal was found이면 journal은 /run에 저장되며 재부팅할 때마다 삭제된다. Storage=auto을 사용하려면 디렉터리를 생성하고 daemon을 재시작한다. Storage=volatile이 설정되어 있으면 먼저 persistent로 변경한다.

sudo mkdir -p /var/log/journal
sudo systemctl restart systemd-journald

sudo journalctl --flush을 실행하면 persistent storage로 전환되고 현재 부팅 세션의 로그가 디스크에 저장된다.

SSH 터널로 UI에 접속하고 공용 포트는 사용하지 않습니다

dsh는 기본적으로 127.0.0.1:3080에서 웹 UI(user interface)를 제공합니다. 기본값은 loopback이지만 유일한 선택지는 아닙니다. --host에는 로컬 인터페이스의 구체적인 IPv4 또는 IPv6 주소 하나를 지정할 수 있습니다. loopback이 아닌 주소를 지정하면 --tls-cert 및 --tls-key도 함께 전달하지 않는 한 해당 주소가 속한 네트워크에 일반 HTTP로 서비스를 제공하며, 시작할 때 경고를 표시합니다. dsh가 거부하는 것은 wildcard입니다. --host 0.0.0.0을 요청하면 오류가 다음과 같이 시작합니다.

webserver: host "0.0.0.0" is an unspecified (wildcard) address, which is not supported:

이어서 "모든 인터페이스에 bind하면 원격 코드 실행이 네트워크에 노출된다"고 설명하고, "대신 로컬 인터페이스의 구체적인 IPv4 또는 IPv6 주소 하나에 bind하라"고 안내합니다. hostname처럼 IP literal이 아닌 값은 is not a concrete IPv4 or IPv6 address literal 오류로 실패합니다.

그래도 기본값을 유지해야 합니다. web API(application programming interface)가 agent를 제어하고, agent는 shell 명령을 실행합니다. dsh는 해당 API 앞에 인증을 적용합니다. Host 및 Origin 검사와, 출력된 URL에 포함된 launch token을 UI가 signed session cookie로 교환하는 방식입니다. 그러나 일반 HTTP에서는 이 token이 네트워크를 평문으로 통과합니다. upstream의 자체 문서도 Host 검사가 listening port 자체를 보호하지 않는다고 설명합니다. 실제 hostname으로 UI를 제공해야 한다면 DeepSeek의 public deployments guide에서 --public-url 및 --trusted-host을 사용하는 reverse proxy나, --tls-cert 및 --tls-key을 사용하는 native TLS 구성을 확인할 수 있습니다. 이동하기 전에 startup output에 표시되는 127.0.0.1:3080 행의 실제 의미를 읽어 보는 것이 좋습니다. 자신만 사용하는 서버라면 자신의 컴퓨터에서 포트를 forward하십시오.

ssh -N -L 3080:127.0.0.1:3080 you@203.0.113.10

-L 3080:127.0.0.1:3080는 laptop의 3080 포트를 열고, 해당 포트로 들어오는 모든 요청을 127.0.0.1:3080로 전달합니다. 이 주소는 VPS에서 확인된 값입니다. -N은 원격 명령을 실행하지 않는다는 뜻입니다. 따라서 세션은 tunnel을 열어 둔 상태로만 유지됩니다. 이 명령을 실행한 채로 두고, 시작할 때 dsh가 출력한 URL을 journalctl -u dsh -n 100 --no-pager로 확인한 다음 browser에서 엽니다. 해당 URL에는 launch token이 포함되어 있습니다. 로그인하지 않은 browser에서 기본 http://127.0.0.1:3080/을 열면 401이 반환됩니다. token은 실행 중인 process에 속하지만, token으로 발급되는 session cookie는 process보다 오래 유지됩니다. 이 cookie는 dsh가 $DSH_HOME/.credentials.yaml에 보관하는 secret으로 서명되며 기본적으로 30일 동안 유효합니다. 따라서 이미 로그인한 browser에서는 restart 후에도 기본 URL을 다시 열 수 있습니다. 새 browser를 사용하거나 cookie가 만료된 경우에만 journal에서 새 URL을 가져오면 됩니다. URL을 credential로 취급해야 합니다. upstream은 이 URL을 지정된 사용자에게만 공유하라고 안내합니다. system journal을 읽을 수 있는 사용자는 URL도 읽을 수 있습니다. 접속한 뒤 Settings에서 Models로 이동하면 DeepSeek API key를 입력할 수 있고 workspace directory도 선택할 수 있습니다. workspace를 서비스 사용자가 소유한 디렉터리인 /var/lib/dsh/workspace으로 지정하십시오. 그렇지 않으면 agent의 file tools가 EACCES: permission denied로 실패합니다.

laptop에서 port 3080이 사용 중이면 ssh가 다음과 같이 알립니다.

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

ssh -N -L 3081:127.0.0.1:3080 you@203.0.113.10를 사용해 다른 local port를 지정한 다음, 출력된 URL에서 3080을 3081로 변경해 엽니다. 자신의 컴퓨터에서 ~/.ssh/config에 입력을 저장해 두십시오.

Host dsh-vps
  HostName 203.0.113.10
  User you
  LocalForward 3080 127.0.0.1:3080

그다음에는 ssh -N dsh-vps이 전체 명령입니다. 이제 이 tunnel이 agent로 들어가는 유일한 경로입니다. 따라서 이를 보호하는 것은 SSH daemon입니다. key만 사용하고 password authentication은 비활성화해야 합니다. 나머지 VPS에서 SSH hardening하기도 평소보다 더 엄격하게 적용해야 합니다. 해당 VPS가 database나 staging box가 있는 소규모 private network로 확장된다면 subnet router로 해당 주소를 tailnet에 광고하기를 사용하면 서비스마다 forward를 설정하지 않아도 됩니다. 다만 dsh가 기본적으로 loopback에서 동작하므로 UI 자체는 여전히 tunnel을 통해 접속해야 합니다.

key를 unit file에 넣으면 안 됩니다. Environment= 값은 모든 box 사용자가 실행할 수 있는 systemctl show dsh -p Environment이 출력합니다. 설치한 plugin이 환경 변수에 key를 필요로 한다면 /etc/dsh.env에 저장하고, root가 소유하도록 mode 600을 설정한 뒤 EnvironmentFile=/etc/dsh.env으로 참조하십시오. systemd는 exec 시점에 해당 파일을 root 권한으로 읽으며, systemctl show은 파일 내용을 출력하지 않습니다. 각 설정이 실제로 disk의 어느 파일에 저장되는지, 그리고 DeepSeek API 대신 local Ollama endpoint를 사용하도록 dsh를 지정했을 때 어떤 데이터가 box 밖으로 나가는지는 dsh의 key, model 및 endpoint 구성하기에서 설명합니다.

운영 비용

추론은 VPS가 아닌 DeepSeek API에서 수행됩니다. 사용자의 서버는 Node 프로세스, 제공되는 UI, 그리고 에이전트가 실행하기로 결정한 모든 명령에 대한 비용을 부담합니다. 앞의 두 가지는 일정하고 적은 양이지만, 세 번째는 이 unit 파일에서 아무런 제한을 받지 않습니다.

다른 사람의 수치를 신뢰하기보다 본인의 서버에서 직접 최소 사용량을 측정하십시오.

systemctl show dsh -p MemoryCurrent
systemd-cgtop -1 --depth 2

MemoryCurrent는 바이트 단위입니다. 에이전트가 유휴 상태일 때가 아니라 작업 중일 때 모니터링하십시오.

도구 호출은 서비스의 자식 프로세스이므로 동일한 제어 그룹(control group)에 속하며 동일한 제한 사항의 적용을 받습니다. npm install을 실행하거나 작업 공간 내에서 테스트 스위트를 실행하는 에이전트는 하네스(harness) 자체보다 훨씬 더 많은 메모리를 사용할 수 있습니다. 1 GB VPS에서는 이 지점에서 문제가 발생합니다. 커널이 프로세스를 선택하여 종료시키며, journalctl -k | grep -i "out of memory"은 선택된 프로세스를 지목하는 Out of memory: Killed process 라인을 보여줍니다. 해당 프로세스는 종종 문제를 일으킨 원인이 아닙니다.

해결책은 의도적으로 제한을 설정하는 것입니다. [Service] 섹션의 MemoryMax=과 CPUQuota=는 피해를 unit 내부로 한정하므로, 제어할 수 없는 빌드가 발생해도 전체 서버가 멈추는 대신 해당 프로세스만 종료됩니다. systemd로 메모리 및 CPU 제한하기에서 수치와 실패 동작을 다룹니다. 디스크 또한 DSH_HOME 하위의 세션 기록과 에이전트가 작업 공간에 기록하는 내용으로 인해 증가하므로, 디스크 모니터링 도구에 du -sh /var/lib/dsh을 추가하십시오.

연결하고 분리할 수 있는 대화형 에이전트를 원한다면 서비스 형태는 적합하지 않으며, 지속적인 tmux 세션에서 에이전트 실행하기가 더 적합합니다. 항상 실행 중이어야 하고 터널을 통해 접근 가능해야 할 때만 dsh를 unit으로 실행하십시오.

실패 유형과 표시되는 문자열

status=203/EXEC. systemd가 파일을 실행하지 못했으며 로그에 Failed to locate executable /usr/local/bin/dsh: No such file or directory이 표시됩니다. ExecStart=의 경로가 command -v dsh에 출력된 경로와 일치하지 않습니다. 이는 숨기지 않고 systemctl start 시점에 Type=exec이 보고하는 실패입니다.

status=217/USER. systemd가 User= 및 Group=에서 사용자 자격 증명을 확인하거나 변경하지 못했거나 사용자 네임스페이스를 설정하지 못했습니다. 이 unit에서 일반적인 원인은 존재하지 않는 계정입니다. id dsh로 확인합니다.

status=200/CHDIR. WorkingDirectory=이 없거나 서비스 사용자가 해당 디렉터리에 들어갈 수 없습니다. sudo -u dsh ls /var/lib/dsh/workspace로 이 문제를 직접 재현할 수 있습니다.

Error: listen EADDRINUSE: address already in use 127.0.0.1:3080. 이미 무언가가 해당 포트를 사용하고 있습니다. 일반적으로 다른 터미널에서 실행한 npx이 열린 상태로 남아 있기 때문입니다. sudo ss -lntp | grep 3080로 해당 프로세스를 확인합니다.

EACCES: permission denied 뒤에 경로가 표시되는 경우. /var/lib/dsh 아래의 소유권이 잘못되었습니다. 보통 첫 실행을 root로 수행했거나 잘못된 HOME을 사용했기 때문입니다. sudo chown -R dsh:dsh /var/lib/dsh로 수정합니다.

Start request repeated too quickly. unit이 시작 속도 제한에 도달하여 포기했습니다. 실제 오류는 그 위의 줄에 있습니다. 다시 시도하기 전에 sudo systemctl reset-failed dsh을 실행합니다.

unit은 active (running)이지만 브라우저에 아무것도 표시되지 않는 경우. VPS에서 확인 명령을 실행합니다. 그곳에서 curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/에 상태 코드가 출력되면 VPS에서 listener가 응답하는 것이므로 다음으로 포트 포워딩을 확인합니다. 해당 코드만으로 모든 항목이 로드되었다고 단정할 수는 없습니다. upstream에 따르면 선택적 플러그인 오류가 readiness를 억제하지 않으므로 journalctl -u dsh -n 200 --no-pager도 확인하여 플러그인 오류를 검토합니다. 브라우저에서 401이 표시되면 유효한 세션 쿠키가 없고 URL에도 유효한 launch token이 없다는 뜻입니다. bare URL을 열었거나 token이 마지막 재시작 이전에 생성되었기 때문일 수 있습니다. 현재 프로세스가 출력한 URL을 엽니다.

의도적으로 업그레이드하기

고정하면 업그레이드는 저절로 발생하는 일이 아니라 직접 수행하는 작업이 된다. 먼저 릴리스 노트를 읽어야 한다. 상위 프로젝트가 호환성을 깨뜨리는 변경을 경고하는 것이 바로 버전을 고정하는 이유이기 때문이다. 상태 디렉터리를 백업한 다음 버전을 교체한다.

sudo systemctl stop dsh
sudo tar czf /root/dsh-home-$(date +%F).tgz -C /var/lib/dsh harness
sudo npm install -g @deepseek-ai/dsh@0.2.1-rc.2
sudo systemctl start dsh
journalctl -u dsh -n 50 --no-pager

롤백은 이전 버전으로 동일한 npm install -g을 수행하고 해당 tarball을 복원하는 과정이다. 단, tarball을 미리 만들어 둔 경우에만 가능하다. 프리뷰 단계의 에이전트 런타임은 업그레이드 과정에서 설정 형식을 변경할 수 있는 대표적인 소프트웨어다.

FAQ

dsh는 SSH 세션을 닫으면 왜 중지됩니까?

npx @deepseek-ai/dsh web는 로그인 세션이 소유한 포그라운드 프로세스이므로 세션이 종료되면 함께 종료됩니다. systemd unit은 init 시스템이 소유하므로 연결을 끊은 뒤에도 계속 실행되고 재부팅 후 다시 시작됩니다. sudo systemctl enable --now dsh는 두 가지를 모두 제공하는 단계의 조합입니다. enable은 재부팅 후 시작을 담당하고, --now은 현재 부팅 세션에서 시작합니다.

dsh에는 Type=simple과 Type=exec 중 무엇을 사용해야 합니까?

Type=exec입니다. dsh는 포그라운드에서 실행되고 fork하지 않으므로 둘 다 동작합니다. 그러나 Type=exec을 사용하면 systemd가 execve()의 성공을 확인한 후에만 시작 성공으로 처리합니다. 따라서 ExecStart=의 경로가 잘못되면 systemctl start이 status=203/EXEC과 함께 즉시 실패합니다. Type=simple를 사용하면 같은 오류가 성공으로 반환되어 journal에 묻힙니다. Type=forking와 Type=notify은 여기서 모두 잘못된 설정이며, 기본적으로 90초 후 TimeoutStartSec이 만료될 때까지 둘 다 멈춘 것처럼 보입니다.

노트북에서 dsh 웹 UI를 열려면 어떻게 해야 합니까?

SSH로 포트를 전달합니다: ssh -N -L 3080:127.0.0.1:3080 you@your-vps. 그런 다음 브라우저에서 dsh가 시작 시 출력한 URL을 엽니다. 이 URL은 journalctl -u dsh에서 확인할 수 있습니다. URL에는 실행 토큰이 포함되어 있으므로 로그인하지 않은 브라우저는 토큰 없이 401을 받습니다. 로그인하면 세션 쿠키는 기본적으로 30일 동안 유지되며 서비스가 재시작되어도 남아 있습니다. 서비스는 loopback 기본값으로 유지합니다. dsh는 --host 0.0.0.0과 같은 wildcard를 지정되지 않은 주소로 간주하여 거부합니다. 하나의 구체적인 로컬 주소는 허용하지만, loopback이 아닌 주소에 bind하면 TLS를 설정하지 않는 한 일반 HTTP가 제공됩니다. 그러면 네트워크를 통해 shell 명령을 실행하는 agent의 실행 토큰이 평문으로 전송됩니다.

권한을 단순하게 유지하기 위해 dsh를 root로 실행해도 됩니까?

아니요. 이 harness는 명령을 실행하고 파일을 작성하므로 서비스에 부여된 권한을 agent도 그대로 가집니다. useradd --system --shell /usr/sbin/nologin dsh으로 system account를 만들고, /var/lib/dsh의 소유자를 해당 account로 변경한 다음, NoNewPrivileges=true을 unit에 추가합니다. 이후 EACCES: permission denied가 발생한다면 일반적인 원인은 이전에 root로 실행하여 root 소유 파일이 남아 있는 것입니다. sudo chown -R dsh:dsh /var/lib/dsh으로 이를 정리할 수 있습니다.

unit에는 dsh의 어떤 버전을 고정해야 합니까?

서비스를 설정할 때 npm view @deepseek-ai/dsh version이 보고하는 버전을 사용합니다. 이 버전은 npm install -g @deepseek-ai/dsh@<that version>으로 설치하고 확인할 수 있는 위치에 기록해 둡니다. 2026년 8월 18일에는 0.1.0-rc.7이 최신이었고, 2026년 10월 11일에는 0.2.0-rc.2이 최신이었으며, 2026년 10월 27일에는 0.2.1-rc.2이 최신이었고 next은 이미 0.2.1-rc.4에 도달했습니다. 2026년 11월 4일에는 latest과 next이 모두 0.2.1-rc.5를 가리킵니다. 0.1.0-rc.7만큼 오래된 build에는 browser authentication이 없으므로 web profile에 사용하지 마십시오. 중요한 것은 버전 번호 자체가 아닙니다. 버전 없이 npx을 사용하면 시작 시점에 package가 resolve되므로 unattended restart로 인해 config format이 다른 build로 조용히 변경될 수 있다는 점이 중요합니다.

이 글이 도움이 되었나요?