DeepSeek Harness dsh 설치 튜토리얼: Web 실행, Headless, AI Coding 실측

DeepSeek Harness dsh란 무엇인가요?

DeepSeek Harness는 DeepSeek가 공개한 Agent 실행 기반이고, MIT 라이선스이며 CLI 이름은 dsh입니다. 제품 페이지는 모델, 도구, Skill, 세션, 샌드박스, 저장, 루프, UI가 모두 교체 가능한 플러그인이라고 적습니다. 아래 조합 계층은 Cordis이고, 구호는 Everything is a plugin입니다. (deepseek.com/harness)

「DeepSeek Harness란」을 검색할 때 필요한 것은 함수 호출 설명을 한 번 더 듣는 일이 아닙니다. 나눠야 할 것은 다음 세 가지입니다.

API는 엔진이고, dsh는 핸들, 공구함, 운전 로직까지 얹힌 런타임입니다. 직접 while을 짜서 chat/completions를 도는 일은 다른 길입니다. 8월 DeepSeek Harness AI Agent 개발 안내가 그 자체 루프를 다룹니다. 이 글은 공식 런처만 검수합니다. 어떻게 설치하는지, Web이 어디에 뜨는지, 첫 코딩 작업을 어떻게 통과시킬지입니다.

공식 사이트는 실행 모드도 나열합니다. 처음에는 Standard Web UI면 충분합니다. 완전한 코딩 Agent라서 파일 수정, shell, 검색이 됩니다. Code 모드는 Standard 위에서 모델이 TypeScript로 여러 라운드 도구 호출을 짜게 합니다. 3080이 안정된 뒤에 여세요. Minimal은 거의 bash와 편집기만 남깁니다. 모델 비교용이지 일상 IDE가 아닙니다. Creator는 런타임을 보고 플러그인을 시험하는 용도입니다. 첫 한 시간은 건너뛰어도 됩니다.

dsh 설치 전에 무엇을 준비하나요?

공식 README의 무설치 경로는 두 줄입니다. 먼저 Node.js를 넣고, 그다음 npx @deepseek-ai/dsh web을 실행합니다. 커뮤니티 문서는 Node ^22.19.0 또는 >=24.0.0을 보탠 적이 있습니다. 맞춰야 할 것은 이 컴퓨터의 npx가 @deepseek-ai/dsh를 띄울 수 있는지입니다. 어떤 블로그 숫자에 맞추려고 시스템 Node를 내리지 마세요.

키 해석 순서는 공식 CLI 설명과 같습니다. 프로세스 환경 → ~/.dsh/.credentials.yaml → 현재 디렉터리 .env → ~/.dsh/.env. 처음에는 하나만 쓰면 됩니다. 네 곳에 쓰고 맞추지 마세요.

export DEEPSEEK_API_KEY=sk-당신의-키
mkdir -p ~/.dsh
printf 'DEEPSEEK_API_KEY=sk-당신의-키\n' >> ~/.dsh/.env
chmod 600 ~/.dsh/.env

공식 어댑터 이름은 deepseek-official이고, 기본은 공식 모델 경로입니다. 요청을 자체 게이트웨이로 보내는 일은 두 번째 단계입니다. 먼저 OmniRoute 실측이 필요한지 보세요. 첫 한 시간에 Base URL을 바꿀 필요는 없습니다.

CLI는 명령을 실행한 현재 디렉터리를 기본 워크스페이스로 씁니다. 빈 저장소나 사본을 만드세요. 예는 ~/work/dsh-first-run입니다. SAFETY.md는 최소 권한을 권하고, 버릴 수 있는 가상 머신, 컨테이너, 전용 환경을 우선합니다. 키와 격리 디렉터리가 준비되기 전에 npx를 실행하지 마세요. 화면은 뜨는데 작업을 통제하지 못하는 편이, 설치가 안 되는 것보다 나쁩니다.

dsh는 어떻게 설치하고 Web UI를 여나요?

처음에는 clone하지 않아도 됩니다. 격리 디렉터리에 들어간 뒤:

cd ~/work/dsh-first-run
npx @deepseek-ai/dsh web

이것이 공식 README의 입구입니다. dsh web은 --profile web의 별칭이고, 첫 실행은 템플릿으로 ~/.dsh/profiles/web/을 초기화합니다. 기본으로 http://127.0.0.1:3080에 작업 화면을 올리고, 이 컴퓨터에서 켜면 기본 브라우저도 엽니다. SSH로 켜면 호스트 URL만 출력하고, 로컬 포워딩은 SSH 클라이언트나 에디터가 가집니다. 프리뷰 단계에서는 명령이 바뀝니다. 그날의 deepseek-ai/deepseek-harness README와 CLI 설명을 기준으로 하세요.

npx @deepseek-ai/dsh web --no-open
npx @deepseek-ai/dsh web --port 8080

기본은 루프백만 묶습니다. 원격으로 화면을 보려면 SSH 로컬 포워딩이면 됩니다. 첫날에 UI를 랜에 노출할 필요는 없습니다. 공식 사용자 가이드는 워크스페이스를 Web UI의 디렉터리 선택기로 지정하고, CLI 플래그가 아니라고 합니다. 3080을 연 뒤 현재 디렉터리가 격리 저장소인지 먼저 확인하고, 그다음 작업을 보내세요.

설정은 ~/.dsh/에 떨어집니다. 홈은 스스로 만들게 두세요. sessions/에서 도구 호출을 되돌려 봅니다. .env에는 키만 넣고 권한은 600입니다. profiles/web/은 첫날에 손으로 patch하지 마세요.

clone할 가치는 세 가지뿐입니다. 특정 커밋을 따를 때, 플러그인을 고칠 때, npx가 실패해 빌드 산출물을 볼 때. 그때 공식 저장소를 git clone하고 pnpm install, pnpm run build, pnpm dsh web을 실행합니다. pnpm dsh web은 산출물을 바로 쓰고 다시 빌드하지 않습니다. 소스 트리에서는 AGENTS.md를 따르세요. 시연 명령을 운영 스크립트에 복사하지 마세요.

dsh Headless는 어떻게 쓰나요?

dsh run은 삭제되었습니다. 일회성 작업은 headless입니다. 새 세션을 열고, 마지막 비어 있지 않은 어시스턴트 텍스트를 stdout에 찍은 뒤 종료합니다.

cd ~/work/dsh-first-run
npx @deepseek-ai/dsh --profile headless "현재 디렉터리의 파일 이름을 나열하고, 파일은 수정하지 마세요"

이것이 노트에 남길 첫 실측입니다. 프로세스 종료 코드, stdout에 최종 답변이 있는지, ~/.dsh/sessions/에 되돌려 볼 로그가 늘었는지. 작업은 읽기 전용이어야 합니다. 공식은 sdk / sdk-minimal / acp처럼 다른 프로세스가 JSON-RPC나 ACP로 붙는 프로필도 제공합니다. 그건 둘째 주 일입니다. 첫 한 시간에 같이 열지 마세요.

dsh로 AI Coding을 하려면?

Web이나 headless가 말한다고 해서 「저장소를 고쳐도 된다」는 뜻은 아닙니다. 공식 Standard 능력대로 파일 수정, shell, 검색, 하위 Agent는 됩니다. 프리뷰 소프트웨어에 명령을 쓰는 모델이 붙으므로, 첫 코딩 작업은 git diff로 대조할 수 있어야 합니다. 벤치마크가 아닙니다. 지정한 디렉터리에서 함수 하나를 제대로 고치는지만 봅니다.

먼저 눈으로 정오를 가릴 수 있는 작은 저장소를 만듭니다. greet.ts는 일부러 hi Ada를 반환하고, 테스트는 Hello, Ada를 기대합니다. 맞고 틀림은 직접 볼 수 있고, 모델이 「그럴듯하게」 말할 필요는 없습니다.

mkdir -p ~/work/dsh-first-run && cd ~/work/dsh-first-run
git init
printf '%s\n' 'export function greet(name: string): string {' '  return "hi " + name' '}' > greet.ts
printf '%s\n' 'import { greet } from "./greet.ts"' 'if (greet("Ada") !== "Hello, Ada") {' '  throw new Error("unexpected greeting")' '}' > greet.test.ts
git add . && git commit -m "chore: isolated dsh first-run repo"

1. 읽기: greet.ts와 greet.test.ts를 읽고, 테스트가 실패하는 이유를 설명하세요. 파일은 수정하지 마세요. 통과: 반환값과 테스트 기대가 다르다고 짚고, 작업 영역의 git status는 깨끗한 상태.
2. 단일 파일: greet.ts만 수정해 greet("Ada")가 Hello, Ada를 반환하게 하세요. 테스트는 바꾸지 말고, 커밋하지 마세요. 고친 뒤 직접 테스트를 돌립니다. 러너가 없으면 함수 반환값을 본 다음 git diff를 실행합니다. 통과: diff가 greet.ts만 건드리고, 반환값이 테스트와 맞음.
3. 테스트가 아직 실패하면 실패 출력을 붙여 같은 파일만 다시 고치게 하세요. 커밋 전에는 반드시 직접 diff를 보세요. 코딩이 실패하면 ~/.dsh/sessions/나 공식 Trajectory를 열고 「도구를 잘못 골랐다」「인자가 잘못됐다」「승인을 거절했다」「워크스페이스가 이 디렉터리가 아니다」를 나누세요.

처음에는 기본 Standard / native 도구면 됩니다. 단일 파일 작업이 안정된 뒤에 DSH_TOOLS_MODE=code나 both를 고려하고, 모델이 TypeScript로 여러 라운드를 짜게 하세요. 공식 참고에서 DSH_PERMISSION_MODE의 프로세스 수준 폴백은 workspace-write에 가깝습니다. danger-full-access는 승인을 거의 묻지 않습니다. 첫 실행 목록에서 빼 두었습니다. JSON 도구 인자에서 막히면 먼저 JSON Schema와 AI Agent를 읽고, 그다음에 모델을 바꾸세요. 작업을 너무 크게 잘라 왕복하면 AI Coding 워크플로를 보세요. dsh가 푸는 것은 「공식 런타임이 있는가」뿐입니다.

dsh 설치가 성공했는지 어떻게 확인하나요?

제목의 「실측」은 벤치마크 표가 아닙니다. 30분 목록입니다. 다섯 항이 모두 지나야 「dsh가 이 머신에서 된다」고 적으세요. 빠지면 해당 단계로 돌아가고, 파일 수정 범위를 넓히지 마세요.

다섯 항 중 하나라도 빠지면 「파일 수십 개를 자동으로 고친다」로 가지 마세요. 프리뷰는 갱신이 빠릅니다. 명령, Node 버전, dsh 패키지 버전, 날짜를 노트에 남기세요. 다음 주에 다시 돌릴 때 환경이 바뀐 것인지, 업스트림 breaking change인지 가릅니다.

dsh에서 자주 나는 오류는?

npx가 실패하거나 느리다. 처음에는 @deepseek-ai/dsh를 받습니다. 네트워크가 불안정하면 소스 빌드로 바꾸거나, 먼저 npm registry를 확인하세요. 실패한 반쪽 캐시를 「이미 설치됐다」고 보지 마세요.

3080이 열리지 않는다. --no-open 뒤 직접 여세요. 포트가 막혔는지, 또는 --port를 썼는데도 3080을 열고 있는지 확인하세요.

화면은 뜨는데 모델이 일하지 않는다. 대개 키 층이 안 맞습니다. 프로세스 환경이 가장 높고, ~/.dsh/.env는 예비일 뿐입니다. 고친 뒤에는 web 프로세스를 다시 켜세요. 키가 바로 반영되길 기대하지 마세요.

고치면 안 되는 디렉터리가 바뀌었다. 시작할 때 현재 디렉터리와 Web에서 고른 저장소를 보세요. 홈을 워크스페이스로 쓰는 일이 가장 흔한 실수입니다.

아직 dsh run을 쓰거나, headless가 종료하지 않는다. 공식 사용자 가이드는 그 하위 명령이 삭제됐다고 적습니다. 일회성 작업은 --profile headless입니다. 작업을 읽기 전용 한 문장으로 줄이고, 승인을 기다리는 상태가 아닌지 확인한 뒤, 세션 로그가 어디서 멈췄는지 보세요.

dsh는 Claude Code나 Codex의 껍데기가 아닙니다. 출시는 각각 DeepSeek, Anthropic, OpenAI입니다. 형태로는 dsh가 독립 런타임에 Web / headless를 붙인 것이고, 나머지 둘은 각자의 CLI입니다. 설정 디렉터리도 통하지 않습니다. dsh는 ~/.dsh입니다. 첫 확인에서 dsh는 3080 또는 headless 한 건, 나머지 둘은 각자 공식 스모크를 타세요. 같이 설치해도 되지만 키, 권한, 세션이 공유된다고 가정하지 마세요. 세 경로를 한곳으로 모을 때는 그때 게이트웨이를 평가하세요. 첫날에는 dsh만 통과시키세요.

지금은 운영 런타임으로 다루면 안 됩니다. 공식 README는 developer preview라고 적었고 호환을 깨는 변경이 있다고 합니다. SAFETY.md는 더 셉니다. 보안 감사를 받지 않았고, 모델이 만든 명령을 실행하고, 서드파티 플러그인을 읽고, 네트워크와 넘긴 파일에 닿습니다. 샌드박스와 승인은 위험을 낮추지만 유일한 보안 통제가 될 수는 없습니다. 지금 맞는 일은 격리 디렉터리에서 설치를 확인하고, 단일 함수 AI Coding을 하고, 세션 로그를 보며 실험하는 것입니다. 지금 맞지 않는 일은 운영 저장소에서 높은 권한을 여는 것, 무인으로 모노레포 전체를 고치는 것, preview를 대외 SLA에 적는 것입니다.

자주 묻는 질문