2026 DeepSeek Harness는 launchd로 어떻게 자동 시작하나요?

일반 사용자 계정의 LaunchAgent로 DeepSeek Harness를 관리하는 것이 기본 선택입니다. DeepSeek Harness launchd 로그인 자동 시작을 적용하기 전에는 실행 파일, 작업 폴더, Profile, 인증 정보 위치를 고정하고, 적용 후에는 프로세스·포트·모델 작업·재시작 복구를 모두 확인해야 합니다. 로그인하지 않은 상태에서도 계속 실행해야 하는 독립 서버가 아니라면 root 권한의 LaunchDaemon부터 만들 필요는 없습니다.

이 글은 다음 독자를 위한 안내입니다.

원격 맥에서 재로그인이나 재시작 뒤 DeepSeek Harness Web 또는 Headless 작업을 다시 올리려는 개발자에게 적합합니다. 플랫폼 엔지니어는 프로세스 계정과 로그 위치를 통일할 수 있고, 인수 담당자는 “실행됨”과 “업무가 복구됨”을 구분해 검수할 수 있습니다.

이번 주에는 설치보다 복구 경로를 먼저 고정하는 방식으로 진행하는 것이 안전합니다.

• 준비 단계: 관리할 실행 형태와 중지 방법 기록
• 첫 설정: 일반 사용자 계정의 LaunchAgent 작성
• 첫 로드: 프로세스 신원과 로그만 확인
• 사용 가능 확인: Web 또는 Headless 최소 작업 실행
• 복구 검증: 중지, 비정상 종료, 재로그인, 재시작 테스트
• 인수 단계: 중지와 업그레이드 절차를 문서화

DeepSeek Harness는 공식 실행 문서에서 npm 또는 소스 기반 실행 방식을 제공하지만, 2026년 8월 19일 기준으로 macOS 서비스 설치기를 기본 제공한다고 단정할 공식 근거는 확인하지 못했습니다. 따라서 이번 구성은 Harness 자체 기능이 아니라 macOS의 공식 프로세스 관리 기능인 launchd를 이용한 운영 방식으로 봐야 합니다. 실행 방식은 DeepSeek Harness 공식 실행 문서와 최신 저장소의 README 및 릴리스 내용을 적용 시점에 다시 대조해야 합니다.

주의: LaunchAgent는 로그인한 특정 사용자 세션에서 실행됩니다. 로그인하지 않은 상태에서도 항상 떠 있어야 하는 서비스라면 요구 조건이 달라지므로, Web UI의 사용자 세션 의존성을 먼저 확인해야 합니다. Apple은 사용자별 작업을 LaunchAgent, 시스템 맥락의 작업을 LaunchDaemon으로 구분합니다. (developer.apple.com)

한 개의 plist에 Web UI, Headless 일회성 작업, 장시간 자동화를 모두 넣으면 장애 원인을 분리하기 어렵습니다. 다음 항목을 실행 전에 기록합니다.

• Web UI인지 Headless 단일 작업인지 구분합니다.
• 현재 정상 실행되는 명령을 그대로 기록합니다.
• dsh 또는 npx의 절대 경로를 확인합니다.
• Profile 이름과 작업 폴더를 고정합니다.
• 실행할 macOS 사용자 계정을 정합니다.
• 정상 중지 명령과 강제 종료 절차를 기록합니다.
• 로그를 보관할 폴더를 미리 만듭니다.

Apple 문서에 따르면 사용자 Agent는 로그인한 사용자에게 속한 맥락에서 실행되며, 시스템 Daemon과 동일한 권한이나 환경을 갖지 않습니다. 이 차이 때문에 Web 작업이 사용자 홈 폴더, 키체인, 승인 상태를 필요로 한다면 일반 계정의 LaunchAgent가 더 자연스럽습니다. 반대로 여러 사용자가 공통으로 접근하는 시스템 서비스라면 별도 설계가 필요합니다. (developer.apple.com)

DeepSeek Harness의 실행 명령은 설치 방식과 릴리스에 따라 달라질 수 있으므로 다음처럼 자리표시자로 기록합니다.

실행 계정: <실행할_사용자>
프로그램 경로: <dsh_또는_npx의_절대경로>
작업 폴더: <프로젝트_절대경로>
프로필: <web_또는_headless_프로필>
중지 방법: <정상_중지_명령>
로그 폴더: <로그_절대경로>

여기서 <실행할_사용자>는 실제 로그인 계정으로 바꾸고, 셸에서 command -v node, command -v npx, command -v dsh를 각각 실행해 결과를 확인합니다. 터미널에서 명령이 작동했다는 이유만으로 LaunchAgent에서도 같은 PATH가 보인다고 가정하면 안 됩니다.

사용자별 설정은 일반적으로 ~/Library/LaunchAgents 아래에 둡니다. 시스템 전체에서 실행되는 LaunchDaemon과 달리 LaunchAgent는 해당 사용자의 로그인 세션에 연결됩니다. 사용자 인터페이스나 사용자별 작업 공간에 접근하는 Web 흐름을 root로 올리면 권한과 파일 소유권이 오히려 복잡해질 수 있습니다. (developer.apple.com)

아래 예시는 완성품이 아닙니다. 계정, 경로, 실행 인자, 포트, Profile을 실제 환경에 맞게 교체해야 합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.deepseek-harness</string>

    <key>ProgramArguments</key>
    <array>
        <string><절대_실행경로></string>
        <string><실행_인자_1></string>
        <string><실행_인자_2></string>
    </array>

    <key>WorkingDirectory</key>
    <string><작업_폴더_절대경로></string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string><필요한_실행경로만_포함한_PATH></string>
        <key>DEEPSEEK_PROFILE</key>
        <string><Profile_이름></string>
    </dict>

    <key>StandardOutPath</key>
    <string><표준출력_로그_절대경로></string>

    <key>StandardErrorPath</key>
    <string><표준오류_로그_절대경로></string>

    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

실제 API Key는 plist 안에 넣지 않습니다. 환경 파일, 키체인 또는 별도 비밀 관리 방식 중 하나를 선택하고, 실행 계정이 읽을 수 있는지 확인합니다. 파일 권한은 해당 계정만 읽을 수 있도록 제한해야 하며, 표준 출력과 표준 오류에 인증 값이 남지 않는지도 확인합니다.

KeepAlive는 프로세스가 종료된 뒤 다시 실행하도록 요청하는 설정일 뿐입니다. 잘못된 경로, 누락된 Node.js 환경, 손상된 Profile을 고쳐 주지 않습니다. 계속 재실행되는 상태를 정상 복구로 오해하면 로그만 빠르게 쌓이고 원인은 늦게 발견됩니다. Apple도 launchd 작업이 너무 빠르게 반복 종료되면 재실행 실패 상태가 될 수 있음을 설명합니다. (developer.apple.com)

plist를 저장한 뒤에는 곧바로 재부팅하지 않고, 먼저 현재 사용자 세션에서 로드합니다. macOS 버전에 따라 launchctl bootstrap, launchctl bootout, launchctl print의 사용 방식이 달라질 수 있으므로 설치된 시스템의 launchctl help와 Apple 문서를 함께 확인합니다.

plutil -lint ~/Library/LaunchAgents/com.example.deepseek-harness.plist

launchctl bootstrap gui/$(id -u) \
  ~/Library/LaunchAgents/com.example.deepseek-harness.plist

launchctl print gui/$(id -u)/com.example.deepseek-harness

첫 검증에서는 Web 화면을 여는 것보다 다음 순서가 중요합니다.

• 프로세스가 예상한 사용자 계정으로 실행되는지 확인합니다.
• 작업 폴더가 설정한 절대 경로인지 확인합니다.
• Node.js, npx, dsh 경로가 실제로 해석되는지 확인합니다.
• 표준 출력과 표준 오류가 지정한 로그에 기록되는지 확인합니다.
• 인증 값이나 세션 토큰이 로그에 노출되지 않는지 확인합니다.

ps -axo user,pid,ppid,command | grep -i dsh
tail -f <표준출력_로그_절대경로>
tail -f <표준오류_로그_절대경로>

로그가 비어 있다고 해서 성공으로 판단하지 않습니다. 프로그램이 출력하지 않았을 수도 있고, 파일 권한 때문에 기록하지 못했을 수도 있습니다. 반대로 오류가 반복된다고 해서 KeepAlive를 먼저 강화하지도 않습니다. 경로, 실행 계정, 작업 폴더, 환경 변수 순서로 원인을 줄이는 편이 운영 비용이 낮습니다.

프로세스가 살아 있는 것과 DeepSeek Harness가 실제 작업을 수행하는 것은 다른 상태입니다. Web 모드라면 설정한 주소와 포트가 지정한 인터페이스에서 열리는지 확인하고, 작업 공간을 읽은 뒤 저위험 모델 작업 하나를 실행합니다. 원격 맥 외부에서 접근할 때는 로컬 바인딩인지 외부 노출인지도 구분해야 합니다. 접근 제어 없이 관리 화면을 넓게 노출하지 않는 편이 안전합니다.

Headless 모드라면 화면 대신 종료 상태와 결과 파일을 확인합니다. 입력 파일, 작업 폴더, 결과물 경로, 오류 로그를 하나의 최소 시나리오로 묶어야 합니다. 인증 성공만 확인하고 파일 생성이나 모델 응답을 확인하지 않으면 실제 자동화는 아직 검증되지 않은 것입니다.

이 단계에서 DeepSeek Harness 원격 Web UI 접근 점검 안내와 DeepSeek Harness 백그라운드 작업 검수 기준을 함께 참고하면, 포트가 열렸지만 작업이 대기 상태에 머무는 문제를 프로세스 장애와 분리할 수 있습니다.

복구 테스트는 한 번의 재부팅으로 끝내지 않습니다. 최소한 아래 네 가지 상태를 분리해 기록합니다.

• 정상 중지 뒤 다시 로드했을 때
• 프로세스를 강제 종료했을 때
• 사용자가 로그아웃한 뒤 다시 로그인했을 때
• 맥을 재시작한 뒤 로그인했을 때

각 테스트에서 프로세스 생성 여부, 로그 재개 여부, Web 포트 응답, 작업 공간 접근, 모델 작업 결과를 따로 기록합니다. 복구 시점은 환경과 작업 상태에 따라 달라질 수 있으므로 고정된 회복 시간을 약속하지 않습니다.

특히 프로세스가 다시 시작됐다고 해서 실행 중이던 Headless 작업이 이어지는 것은 아닙니다. 메모리에만 있던 대화, 승인 대기, 임시 파일, 외부 API 요청은 자동으로 복원되지 않을 수 있습니다. 작업 재개가 필요하면 체크포인트, 입력 파일, 결과물의 원자적 저장, 중복 실행 방지 키를 DeepSeek Harness의 작업 설계에 별도로 넣어야 합니다.

운영 경험: 자동 시작의 검수 문장은 “프로세스가 다시 떴다”가 아니라 “재로그인 뒤 같은 작업 폴더에서 안전한 작업이 한 번 완료되고 결과물이 확인됐다”여야 합니다. 두 문장은 비슷해 보이지만 인수 기준은 전혀 다릅니다.

LaunchAgent와 LaunchDaemon은 서로 상위·하위 관계가 아닙니다. 필요한 세션과 권한이 다릅니다. Web UI를 root로 실행하면 편해 보일 수 있지만, 사용자 홈의 Profile이나 키체인 접근이 끊겨 화면만 뜨고 작업은 실패하는 구성이 될 수 있습니다. Apple의 세션 설명처럼 root 세션과 로그인 세션은 별도로 관리되므로, 필요한 서비스 범위를 먼저 정해야 합니다. (developer.apple.com)

• [ ] Web, Headless, 자동화 중 관리 대상이 하나로 정의되어 있습니다.
• [ ] 실행 파일과 Node.js 관련 경로가 절대 경로로 기록되어 있습니다.
• [ ] 작업 폴더와 Profile이 고정되어 있습니다.
• [ ] 실행 계정이 root가 아닌 일반 계정으로 검토되었습니다.
• [ ] API Key가 plist와 명령행에 평문으로 들어 있지 않습니다.
• [ ] 표준 출력과 표준 오류 로그의 위치와 보관 책임이 정해졌습니다.
• [ ] 첫 로드 뒤 프로세스 계정과 작업 폴더를 확인했습니다.
• [ ] Web 모드에서 포트뿐 아니라 저위험 모델 작업까지 완료했습니다.
• [ ] Headless 모드에서 종료 상태와 결과물을 확인했습니다.
• [ ] 정상 중지와 비정상 종료 뒤 복구를 각각 시험했습니다.
• [ ] 로그아웃, 재로그인, 맥 재시작 뒤 상태를 기록했습니다.
• [ ] 실행 중 작업이 자동으로 이어지지 않을 수 있음을 인수 문서에 적었습니다.
• [ ] 업그레이드 전에 기존 인스턴스를 중지할 절차가 있습니다.
• [ ] 새 버전의 경로와 포트가 기존 상태 디렉터리와 충돌하지 않습니다.
• [ ] 실패 시 LaunchAgent를 bootout하고 수동 실행으로 되돌리는 절차가 있습니다.

업그레이드할 때는 새 실행 파일을 먼저 올리는 대신 기존 LaunchAgent를 중지하고, 현재 로그를 보존한 뒤 새 경로를 검증합니다. 같은 포트나 상태 폴더를 두 인스턴스가 함께 사용하면 Web UI 충돌, 잠금 파일 오류, 중복 작업이 발생할 수 있습니다.

실제 중지 명령은 등록한 Label과 macOS 버전에 맞춰 사용합니다.

launchctl bootout gui/$(id -u)/com.example.deepseek-harness

plist 파일을 삭제하는 것만으로 이미 실행 중인 프로세스가 반드시 종료되는 것은 아닙니다. 등록 해제, 프로세스 상태, 로그 보존을 각각 확인해야 합니다. Apple은 launchd 작업을 등록한 위치와 세션에 따라 관리하도록 설명하므로, 다른 사용자나 root 세션에서 명령을 실행해 결과를 혼동하지 않아야 합니다. (developer.apple.com)

현재 맥에서 이 구성을 직접 유지하는 방식은 비용이 낮아 보이지만, 재시작 뒤 로그인하지 않는 운영 환경, 절전 정책, 네트워크 변경, 수동 업데이트가 겹치면 지속 실행 책임이 사용자에게 남습니다. 반면 JEXCLOUD의 원격 맥을 사용하면 별도 장비를 계속 켜 두는 부담은 줄일 수 있지만, 장기간 안정적인 고정 부하나 물리 장치 연결이 필요한 작업에는 직접 보유한 맥이 더 적합할 수 있습니다. 먼저 DeepSeek Harness 클라우드 맥 인수 점검 안내를 기준으로 필요한 로그인 상태와 접속 조건을 확인한 뒤, 현재 맥이 지속 점유 창을 제공하지 못하는 경우에만 원격 맥 환경과 임대 기간을 비교하는 편이 합리적입니다.

마지막으로 재시작 뒤 최소 작업이 완료된 로그를 보관하고, 민감한 값이 제거된 인수 기록을 남깁니다. 자동 시작을 설정하는 목적은 부팅 명령을 한 줄 줄이는 데 있지 않고, 장애 뒤 어떤 상태까지 자동으로 복구되며 어디서 사람의 확인이 필요한지 명확히 하는 데 있습니다.

• 런치드로 맥 에이전트를 자동 시작하고 재시작 상태를 점검하는 방법
• 원격 맥에서 런치드 에이전트와 로그를 설정하고 게이트웨이를 상시 실행하는 방법