설치

zqagent에는 명령줄 도구(CLI) 와 데스크톱 앱 두 가지 형태가 있습니다. 이 페이지에서는 CLI의 설치, 업그레이드, 제거를 설명합니다.

명령줄을 쓰고 싶지 않다면 데스크톱 앱을 참고하세요. 설치 파일을 다운로드하면 GUI로 사용할 수 있습니다.

가장 빠른 방법: 한 줄 설치(Linux / macOS)

curl -fsSL https://agent.cd-zq.com/install.sh | sh
# 서버에서는 root로 실행하면 자동 시작 서비스로 설치할 수 있습니다
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

스크립트는 공식 버전 목록을 읽고 해당 아키텍처의 단일 실행 파일을 다운로드해 SHA-256을 검증한 뒤 PATH에 설치합니다. Node를 미리 설치할 필요가 없습니다. 기본적으로 /usr/local/bin(쓰기 가능 시) 또는 ~/.local/bin에 설치합니다. Linux(x64 / arm64)와 macOS(Intel x64 / Apple Silicon arm64)를 지원합니다.

설치 후 자동 시작 서비스로 등록되며(Linux systemd / macOS launchd, 크래시 시 자동 복구), 현재 상태와 세 가지 사용법을 출력합니다:

용도	방법
그래픽 화면	브라우저에서 http://127.0.0.1:8787 열기
명령줄	zqagent(/connect로 모델 설정)
원격 관리	Hub 계정으로 바로 연결: zqagent link --hub https://hub.cd-zq.com --username <이메일/휴대폰> --password '<비밀번호>'(연결 코드도 가능)

터미널이 있는 머신에서는 설치 끝에 Hub 연결 여부를 묻습니다. Hub에 등록한 이메일/휴대폰 번호와 비밀번호를 입력하면 됩니다 (비밀번호는 표시되지 않음). 자동화 환경에서는 설치 명령에 계정을 직접 넘길 수 있습니다(비밀번호는 환경 변수 권장):

# 비밀번호 숨겨 입력(표시 안 됨, 셸 기록에도 남지 않음)
read -rsp 'Hub 비밀번호: ' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# 또는 일회용 연결 코드(15분 유효)
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --code <연결 코드>

설치 시 연결하지 않으려면 --no-enroll을 붙이고 나중에 zqagent link로 보완할 수 있습니다.

비 root로 실행했거나 컨테이너에 systemd가 없으면 서비스화를 건너뛰고 포그라운드 실행 명령을 안내합니다. 순수 CLI만 필요하면 --no-service를 붙입니다.

반복 실행할 수 있습니다: 이미 설치되어 최신이면 다시 다운로드하지 않고 현재 상태 (버전, 서비스 실행 여부, 로컬 주소 접근성, Hub 연결, 자동 업데이트 채널)를 보고합니다. 새 버전이 있으면 자동으로 업그레이드하고 서비스를 재시작합니다.

자주 쓰는 인수(sh -s --로 전달):

# 포트 / 바인드 주소 / 데이터 디렉터리 변경
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --port 9000 --host 0.0.0.0

# 사용자 지정 디렉터리에 설치
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --bin-dir ~/bin

# CLI만, 자동 시작 서비스 없이
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-service

# 설치 후 Hub 계정으로 연결(--code <연결 코드>도 가능)
read -rsp 'Hub 비밀번호: ' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# 설치 끝의 연결 질문 건너뛰기
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --no-enroll

# 이미 설치되어 있어도 강제로 다시 다운로드해 덮어쓰기
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --force

# 강제로 npm 사용
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --npm

# 익명 설치 통계 전송 안 함
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-telemetry

한 줄 스크립트는 macOS / Linux용입니다. Windows는 단일 파일 exe (대상 머신에 Node 불필요)를 다운로드하거나 아래 npm 방식으로 설치하세요.

설치 통계 안내: 설치 성공 후 자체 통계 서비스로 익명 레코드 1건을 전송합니다 (버전, 플랫폼, 아키텍처, 설치 방식만). 각 플랫폼의 실제 사용 상황을 파악하기 위해서입니다. 사용자 이름, 설치 경로, IP, 신원을 식별할 수 있는 정보는 포함하지 않으며 Cookie도 사용하지 않습니다. 원하지 않으면 --no-telemetry를 붙이거나 ZQAGENT_NO_TELEMETRY=1을 설정해 완전히 끌 수 있습니다.

macOS 안내

• 칩 아키텍처: Intel(macos-x64)과 Apple Silicon(macos-arm64)이 각각 해당 산출물을 다운로드합니다.
• 자동 시작: root로 설치하면 LaunchDaemon으로 등록 (/Library/LaunchDaemons/com.zqagent.node.plist, 부팅 시 시작). 일반 사용자로 설치하면 LaunchAgent로 등록(~/Library/LaunchAgents/, 로그인 후 시작). plist에 KeepAlive가 있어 프로세스가 종료되면 launchd가 즉시 다시 띄웁니다.
• 자동 업데이트: Linux와 동일합니다. 서비스 내에서 조용히 다운로드하고 목록으로 서명을 검증하며, 유휴 시 바이너리를 교체하고 종료하면 launchd가 새 버전을 띄웁니다. zqagent update --status로 관리 상태와 마지막 확인 시간을 볼 수 있습니다.
• 제거: sudo sh -s -- uninstall. 시스템 수준 Daemon과 sudo를 실행한 사용자의 Agent를 함께 정리합니다. 데이터 디렉터리와 바이너리는 남으며 반복 실행해도 오류가 없습니다.
• 단일 인스턴스: root로 재설치할 때 해당 사용자의 LaunchAgent를 먼저 제거해 시스템 수준과 사용자 수준 두 인스턴스가 같은 포트를 다투지 않게 합니다.

기본 데이터 디렉터리: 일반 사용자는 ~/Library/Application Support/zqagent, root로 설치하면 /var/root/Library/Application Support/zqagent.

macOS 두 아키텍처의 단일 파일 산출물은 각 버전과 함께 공개되며, 설치 시 Node를 미리 설치할 필요가 없습니다. 어떤 목록에 현재 아키텍처 산출물이 없으면 스크립트가 자동으로 npm으로 폴백합니다(Node ≥ 18.17 필요). npm 전역 디렉터리에 쓸 수 없으면 ~/.local에 설치하고 안내를 표시합니다.

포트가 사용 중이면 자동 변경

기본 포트 8787은 개발 머신에서 다른 서비스가 쓰고 있는 경우가 많습니다. 설치 스크립트는 서비스 등록 전에 포트를 확인하고, 사용 중이면 8788, 8789…로 차례로 늘리며 각 시도를 출력하고, 최종 포트로 서비스 구성을 생성합니다:

→ 포트 8787 사용 가능 여부 확인 ...
! 포트 8787은 다른 프로세스가 사용 중
→ 포트 8788 시도 ...
! 포트 8788로 자동 변경했습니다(예정 8787이 사용 중)
  로컬 콘솔: http://127.0.0.1:8788

노드 프로세스 자체에도 같은 보호가 있습니다: 서비스 시작 시 포트가 사용 중이면 자동으로 다음 빈 포트로 바꾸고 로그에 설명하며, 실제 포트를 데이터 디렉터리의 server-port 파일에 기록합니다. 설치 스크립트와 zqagent update --status는 그것을 기준으로 주소를 보고합니다.

포트를 이 노드 자신이 사용 중이면(서비스 실행 중) 스크립트는 그 포트를 이어받고 두 번째 인스턴스를 띄우지 않습니다. 고정하려면 --port <포트>를 사용합니다. 시작 포트부터 연속 20개가 사용 중이면 오류로 종료합니다.

Windows 단일 파일(Node 불필요)

Windows 산출물은 단일 zqagent.exe이며 대상 머신에 Node/npm이 필요 없습니다.

시스템 요구 사항: Windows 10 / Server 2016 이상(64비트 x64 또는 ARM64만). Windows 7, 8, 8.1과 Server 2008 R2 / 2012는 실행할 수 없습니다. 부족한 것은 시스템 API이며 C++ 런타임을 설치해도 해결되지 않습니다. 자세히는 Windows 지원 버전을 참고하세요.

1. 아키텍처에 맞는 산출물 다운로드(대상 머신에 Node/npm 불필요):

   아키텍처	대상	다운로드
   x64	대부분의 Windows	zqagent-windows-x64

   파일 이름에는 버전과 빌드 시간이 들어갑니다. 링크는 사이트 빌드 시 현재 릴리스로 자동 연결됩니다. 전체 목록은 https://agent.cd-zq.com/downloads/zqagent/stable.json(binaries.windows-x64.url)에 있습니다. Windows ARM64 산출물은 현재 없습니다. x64 버전을 사용하세요(Windows가 에뮬레이션으로 실행).

2. 임의 디렉터리(예: %LOCALAPPDATA%\zqagent\)에 두고 PowerShell 또는 cmd에서 실행:

   .\zqagent-windows-x64-v<버전>-<빌드시간>.exe

   첫 실행 후 /connect로 모델을 설정하면 사용할 수 있습니다.

3. zqagent를 직접 입력하려면: 해당 디렉터리를 사용자 PATH에 추가하고(「시스템 속성 → 환경 변수」), 파일 이름을 zqagent.exe로 바꿉니다. 명령줄 방식(setx는 너무 긴 PATH를 자릅니다):

   setx PATH "%PATH%;%LOCALAPPDATA%\zqagent"

원격 관리 가능한 노드로 상주:

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"

자동 시작이 필요하면 「작업 스케줄러」에서 '로그온 시 실행' 작업을 만듭니다. 프로그램에는 exe 절대 경로, 인수에는 serve --port 8787 --data-dir "%APPDATA%\zqagent"를 지정합니다.

• Windows에는 systemd / launchd가 없어 단일 파일은 자동 업데이트가 비활성입니다(자신을 교체해도 서비스 관리자가 다시 띄우지 못함). 업그레이드 방법: 프로세스 중지 → 새 exe 다운로드해 덮어쓰기 → 재시작.
• 산출물에 Authenticode 서명이 없습니다(SEA를 주입하면 node.exe의 서명이 깨짐). 첫 실행 시 SmartScreen 경고가 나올 수 있습니다. 정식 배포 전에 signtool로 다시 서명하세요.
• CLI에 ripgrep이 내장되어 있어 rg를 따로 설치할 필요가 없습니다.

시스템 요구 사항

항목	요구 사항
운영체제	macOS / Linux / Windows. Windows는 10 / Server 2016 이상(데스크톱 앱은 10 1709+). 자세히는 Windows 지원 버전
Node.js	≥ 18.17(npm 설치에서만 필요. Linux / macOS / Windows 단일 파일은 런타임 내장)
네트워크	agent.cd-zq.com(단일 파일) 또는 공개 npm registry.npmjs.org(npm) 접근 가능

하위 명령: 설치된 노드 관리

install.sh는 관리 도구이기도 합니다. 설치 외에 status / logs / restart / rollback / print-config 하위 명령을 지원합니다(sudo가 필요하면 붙임):

sudo sh -s -- status        # 버전, 서비스, 로컬 주소, 원격 연결, 자동 업데이트
sudo sh -s -- logs          # 노드 로그 추적
sudo sh -s -- restart       # 서비스 재시작
sudo sh -s -- rollback      # 직전 자동 업데이트 이전 버전으로 롤백
sudo sh -s -- print-config  # 사용할 구성만 출력하고 아무 동작도 하지 않음
sudo sh -s -- uninstall     # 서비스 제거(데이터 디렉터리와 바이너리는 유지)

파이프로 실행할 때 하위 명령은 sh -s -- 뒤에 둡니다:

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- status

스크립트를 이미 내려받았다면 인수로 직접 전달: sudo sh install.sh status.

설치 스크립트는 다음을 합니다:

1. 공식 목록에서 최신 버전을 읽고 플랫폼/아키텍처에 맞는 바이너리 다운로드
2. SHA-256과 버전 검증
3. 검증용 공개 키 자동 획득(--pubkey로 명시 지정 가능)
4. /usr/local/bin/zqagent(또는 ~/.local/bin)에 설치
5. 서비스로 등록: Linux는 systemd, macOS는 launchd

따라서 명령 하나로 완료되며 공개 키를 직접 찾을 필요가 없습니다.

구성 포함 설치(포트, 데이터 디렉터리)

curl -fsSLO https://agent.cd-zq.com/install.sh
sudo sh install.sh --port 8787 --data-dir /srv/zqagent

공개 키 직접 지정(선택)

--pubkey를 넘기지 않으면 스크립트가 $BASE_URL/update-public.b64에서 자동 획득합니다. 이 파일은 업데이트 목록과 같은 출처이므로 이 기본 신뢰는 '사이트 HTTPS와 도메인이 뚫리지 않았음'에 기반합니다. 더 강한 보장이 필요하면 대역 외에 보관한 공개 키를 설치 시 명시적으로 전달하세요:

sudo sh install.sh --pubkey "$(cat /path/to/update-public.b64)"

명시한 공개 키가 우선하며 스크립트가 네트워크로 덮어쓰지 않습니다. 형식이 잘못되면 오류로 종료합니다.

인수	설명	기본값
--port <n>	바인드 포트	8787
--host <addr>	바인드 주소	127.0.0.1
--data-dir <dir>	데이터 디렉터리	Linux ~/.zqagent_data, macOS ~/Library/Application Support/zqagent(로그도 따라감)
--pubkey <key>	자동 업데이트 검증 공개 키	$BASE_URL/update-public.b64에서 자동 획득
--service-name <n>	systemd unit 이름	zqagent
--label <name>	launchd 작업 이름	com.zqagent.node
--channel <name>	업데이트 채널	stable
--version <x.y.z>	버전 지정	목록의 최신 버전
--no-service	바이너리만 설치	—

Windows는 데스크톱 앱을 사용하세요. WSL 안에서는 위의 Linux 방식으로 설치할 수 있습니다.

원격 서버 설치

먼저 서버에 로그인할 필요 없이 로컬에서 SSH로 설치 작업을 보낼 수 있습니다. 서버에 curl과 sudo만 있으면 되고 Node/npm은 필요 없습니다. 다운로드하는 것은 런타임 내장 단일 바이너리입니다.

ssh deploy@your-server \
  'curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh'

포트나 데이터 디렉터리를 지정하려면 먼저 다운로드한 뒤 실행합니다(파이프 방식은 인수를 전달할 수 없음):

ssh deploy@your-server '
  curl -fsSLO https://agent.cd-zq.com/install.sh &&
  sudo sh install.sh --port 8787 --data-dir /srv/zqagent
'

설치 후에는 마찬가지로 install.sh status|logs|restart|rollback 하위 명령을 쓰며, 이후 업그레이드는 노드가 목록에 따라 자동으로 수행합니다(다음 절 참조).

통합 전 공개된 install-node.sh 주소(/downloads/zqagent/install-node.sh)에도 같은 내용의 복사본이 계속 동기화됩니다. 기존 스크립트는 수정할 필요가 없지만, 새 스크립트는 install.sh로 통일하는 것을 권장합니다.

단일 파일 설치의 업그레이드

단일 파일로 설치한 노드는 자동 업데이트합니다. 새 버전을 조용히 다운로드하고 실행 중인 작업이 없을 때 자신을 교체한 뒤 재시작합니다. 자세히는 노드 시작 · 자동 업데이트를 참고하세요.

수동으로 확인하려면:

zqagent update --check     # 새 버전이 있는지
zqagent update --status    # 현재 버전, 채널, 마지막 확인

소프트웨어 소스

@zqagent 시리즈 패키지는 공개 npm(https://registry.npmjs.org/)에 게시되어 있으며 가입이나 계정 신청 없이 npm 기본 소스로 바로 설치할 수 있습니다.

로컬 npm이 국내 미러(registry.npmmirror.com 등)를 기본으로 해도 정상 설치됩니다. 미러는 게시 후 자동 동기화됩니다. 어느 경우든 @zqagent용 스코프를 따로 설정할 필요가 없습니다.

npm 설치(개발자 / Node 사용 중)

개발 머신에서 언제든 zqagent를 쓰고 싶을 때 적합합니다. 자동 업데이트 관리 대상이 아니며 업그레이드는 npm으로 합니다.

# 로컬 기본 소스 사용(권장)
npm i -g @zqagent/core

# 또는 임시로 공개 npm 지정
npm i -g @zqagent/core --registry=https://registry.npmjs.org/

버전 채널

공개 npm은 현재 안정판(latest 태그)만 게시합니다:

채널	설치 명령	설명
안정판(기본)	npm i -g @zqagent/core@latest	릴리스마다 latest 갱신. 일상 사용에 적합

버전을 지정하지 않으면 @latest와 같습니다. 초기 문서에 있던 @dev 테스트 채널은 아직 공개되지 않았으며, npm i -g @zqagent/core@dev는 버전을 찾을 수 없다는 오류가 나므로 사용하지 마세요.

설치 확인

zqagent link --help       # macOS / Linux(PATH에 추가됨)

.\zqagent-windows-x64-v<버전>-<빌드시간>.exe link --help    :: Windows 단일 파일(PATH 미추가)

이후 zqagent를 실행해 대화형 CLI로 들어가고 /connect로 모델을 설정하면 시작할 수 있습니다. 자세히는 빠른 시작을 참고하세요.

업그레이드와 제거

Windows 단일 파일

:: 업그레이드: 실행 중인 serve를 중지한 뒤 새 exe로 기존 파일 덮어쓰기
:: (파일 이름은 그대로라 작업 스케줄러 / 바로 가기는 수정 불필요)
copy /Y zqagent-windows-x64.exe "%LOCALAPPDATA%\zqagent\zqagent.exe"

:: 제거: 프로세스 중지 후 exe와 데이터 디렉터리 삭제
rmdir /S /Q "%LOCALAPPDATA%\zqagent"

단일 파일 설치(install.sh, macOS / Linux)

# 업그레이드: 설치 스크립트를 다시 실행하면 됩니다. 최신이면 상태만 보고
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

# 서비스 제거(데이터 디렉터리와 바이너리는 유지)
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- uninstall

# 완전 정리(Linux. 데이터는 기본으로 실행 사용자 홈)
sudo rm -rf ~/.zqagent_data /usr/local/bin/zqagent

# 완전 정리(macOS. 일반 사용자 설치 시 데이터는 ~/Library/Application Support/zqagent)
sudo rm -rf "/var/root/Library/Application Support/zqagent" /usr/local/bin/zqagent

설치와 제거 모두 반복 실행할 수 있습니다: 이미 설치된 상태에서 다시 실행하면 재다운로드 없이 현재 상태만 보고합니다. 서비스가 없을 때 uninstall을 실행해도 오류가 없습니다. 제거 후 다시 설치하면 남아 있던 바이너리와 데이터 디렉터리를 재사용하며, 연결된 Hub 자격 증명과 모델 구성도 그대로 남습니다.

npm 설치

# 최신 안정판으로 업그레이드
npm i -g @zqagent/core@latest

# 제거
npm uninstall -g @zqagent/core

업그레이드는 프로그램 본체만 교체하며 모델 구성과 세션 데이터는 건드리지 않습니다 (구성은 ~/.config/zqagent/, 세션과 프로젝트 데이터는 각 데이터 디렉터리. 노드 시작 참조).

자주 묻는 질문

zqagent: command not found가 나오나요? 전역 bin 디렉터리가 PATH에 없습니다. 확인 후 PATH에 추가하세요:

Windows 단일 파일은 전체 경로 또는 .\zqagent.exe로 실행합니다. PATH 추가 방법은 Windows 단일 파일을 참고하세요.

npm prefix -g        # npm 전역 접두사 출력. bin은 그 안(Windows는 같은 디렉터리)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc   # macOS/Linux

설치 시 EACCES 권한 오류가 나나요? npm 전역 디렉터리가 root 소유입니다. sudo npm i -g를 쓰지 말고, 버전 관리 도구(nvm/fnm)를 쓰거나 npm 전역 접두사를 사용자 디렉터리로 바꾸세요:

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

설치가 느리거나 시간 초과되나요?https://registry.npmjs.org/(또는 설정한 미러)에 접근할 수 있는지 확인하세요. 사내망에서는 HTTP 프록시를 설정할 수 있습니다:

npm config set proxy http://<host>:<port>
npm config set https-proxy http://<host>:<port>

다른 머신에서는 다시 설정해야 하나요?~/.npmrc와 ~/.config/zqagent/는 사용자 디렉터리에 있어 머신을 바꾸면 소스를 다시 설정해야 합니다. 모델 API Key는 /connect로 다시 연결할 수 있습니다.

다음 단계

• 빠른 시작: 모델 연결과 첫 작업 완료
• 노드 시작: zqagent를 원격 관리 가능한 노드로 상주
• 노드 콘솔: GUI로 노드, 세션, 사용량 관리