본문으로 건너뛰기

설치

이 가이드는 Nexus Agent Platform을 로컬, 또는 서버 환경에 설치하는 방법을 안내합니다.

사전 준비​

  1. Git — 소스 코드 관리 및 다운로드 도구

    Nexus Agent 코드를 다운로드하거나 버전 관리를 위해 Git이 설치되어 있어야 합니다. 터미널(또는 명령 프롬프트)에서 git --version을 입력해 설치 여부를 먼저 확인하세요.

    macOS:

    # Homebrew를 통한 설치
    brew install git

    (또는 터미널에 git 명령을 입력하면 나타나는 Apple Command Line Tools 가이드를 따라 설치할 수도 있습니다.)

    Windows (PowerShell):

    # Winget을 통한 설치
    winget install --id Git.Git -e --source winget

  2. uv — Python 패키지 관리 도구

    macOS / Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Windows (PowerShell):

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  3. GitHub CLI (gh) — (선택) GitHub 릴리즈 다운로드 및 로그인용

    GitHub Release 방식(방법 1)으로 다운로드하려면 gh 명령어가 필요합니다.

    macOS:

    brew install gh

    Windows (PowerShell):

    winget install --id GitHub.cli

  4. GitHub 인증 — Private Repository 접근에 필요

    방식환경설정 방법
    GitHub CLI (권장)로컬 개발gh auth login 실행
    SSH로컬 개발GitHub에 SSH 키 등록
    PATCI/CD, 자동화GITHUB_TOKEN 환경변수 설정

    PAT 발급: GitHub → Settings → Developer settings → Personal access tokens → repo 권한을 포함한 토큰 생성

방법 1: GitHub Release에서 직접 설치 (권장)​

태그가 push될 때마다 GitHub Actions가 자동으로 빌드한 wheel (.whl) 파일을 Release에 첨부합니다. 본 프로젝트는 Private 상태이므로 인증된 다운로드가 필요합니다.

macOS / Linux (Bash):

# GitHub CLI로 다운로드 위치 지정 후 로컬 설치 (gh auth login 필요)
gh release download --repo EJCHO-salary/track_platform --pattern "*.whl" --dir /tmp
uv tool install /tmp/nexus_agent_platform-*.whl

Windows (PowerShell):

# 임시 폴더에 다운로드 후 설치 (와일드카드(*)를 해석하기 위해 Resolve-Path 사용)
$tempDir = [System.IO.Path]::GetTempPath()
gh release download --repo EJCHO-salary/track_platform --pattern "*.whl" --dir $tempDir
$whlFile = Resolve-Path (Join-Path $tempDir "nexus_agent_platform-*.whl")
uv tool install $whlFile

특정 버전 지정 설치:​

gh release download v0.4.13 --repo EJCHO-salary/track_platform --pattern "*.whl" --dir /tmp
uv tool install /tmp/nexus_agent_platform-0.4.13-py3-none-any.whl

PAT 방식 (gh CLI 없이 CLI 다운로드 구축 시):

export GITHUB_TOKEN="ghp_your_token_here"
curl -L -H "Authorization: token ${GITHUB_TOKEN}" -H "Accept: application/octet-stream" \
  "https://api.github.com/repos/EJCHO-salary/track_platform/releases/latest" \
  | python3 -c "import sys,json; a=json.load(sys.stdin)['assets']; print([x for x in a if x['name'].endswith('.whl')][0]['url'])" \
  | xargs -I{} curl -L -H "Authorization: token ${GITHUB_TOKEN}" -H "Accept: application/octet-stream" {} -o /tmp/nexus_agent.whl
uv tool install /tmp/nexus_agent.whl

방법 2: Git 저장소에서 직접 설치​

소스에서 직접 설치합니다. 단, 프론트엔드 빌드가 포함되어 있지 않아 개발 용도로 사용됩니다.

# SSH 방식
uv tool install "git+ssh://git@github.com/EJCHO-salary/track_platform.git@v0.4.13"

# PAT 방식
uv tool install "git+https://${GITHUB_TOKEN}@github.com/EJCHO-salary/track_platform.git@v0.4.13"

Git 설치 시 웹 브라우저 접속을 위한 프론트엔드 정적 파일(nexus_agent/static/)이 제외됩니다. 프론트엔드 UI가 필요하다면 **방법 1 (GitHub Release)**을 사용하세요.

방법 3: 다른 프로젝트의 의존성으로 추가​

Nexus Agent 서버를 당신의 기존 pyproject.toml에 라이브러리로 추가할 때 사용합니다.

# SSH 방식
uv add "nexus-agent-platform @ git+ssh://git@github.com/EJCHO-salary/track_platform.git@v0.4.13"

요구사항​

  • Python 3.13 이상 (uv 사용 시 지원 대상 자동 관리됨)
  • 지원 LLM 프로바이더 중 최소 1개의 API Key (Google Gemini, OpenAI, Claude 등)