이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

설치와 런타임 채널

상태: 활성

범위: 현재 상태

최종 검토: 2026-10-09

담당: ax-code 런타임

루트 README가 기본 설치 경로를 유지합니다. 이 페이지는 지원되는 CLI 설치 채널, ax-code doctor 런타임 레이블, 로컬 실행기 동작, 공개 업그레이드 동작의 진실의 원천입니다.

공개 가용성

공개 릴리스 설치 프로그램과 서명된 런타임 아카이브는 download.ax-code.com를 통해 배포됩니다. 설치에 비공개 GitHub 자격 증명은 필요하지 않습니다.

AX Code와 SDK는 Node.js 26 이상만 지원합니다. 독립 설치 프로그램은 검증된 Node 런타임을 묶습니다. 소스 체크아웃과 Node 기반 SDK 애플리케이션은 Node.js 26 이상을 제공해야 합니다. 패키지 설치는 더 오래된 Node 버전을 거부합니다.

AX Code Standard는 기존 라이선스 아래 개인과 상업 사용에 계속 무료입니다. 개발 소스 접근은 공개 배포와 따로 관리됩니다. 계획된 독점 Business 구성 요소는 별도의 라이선스가 있습니다. 이것은 Standard의 라이선스를 바꾸지 않습니다. 상세는 Standard와 Business를, 공개 설치 갱신은 웹사이트 안내를 보십시오. 웹사이트가 한 줄 설치 명령을 알리기 전에 공개 설치 프로그램과 서명된 자산에 도달할 수 있고 검증되어야 합니다.

릴리스 가용성

vMAJOR.MINOR.PATCH git 태그를 푸시하면 Release 작업 흐름이 시작됩니다. 공개 릴리스 색인 목록은 그 작업 흐름이 자산을 서명하고 게시한 뒤에만 버전을 보여 줍니다. 그때까지 Latest는 이전에 게시된 태그에 남습니다. 검증이 성공한 뒤 유지관리자는 새 태그의 Draft를 볼 수 있습니다. 그것은 공개 Latest가 아닙니다.

기존 설치는 업그레이드와 복구를 따릅니다.

권장 경로

체크아웃에서 개발하는 경우가 아니면 지원되는 패키지 설치 프로그램을 사용합니다. 릴리스 설치 프로그램은 macOS와 Linux의 기본 CLI 경로입니다. Windows에서는 네이티브 PowerShell 설치 프로그램을 사용합니다.

macOS(Apple Silicon)

curl -fsSL https://download.ax-code.com/install | bash

Windows

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://download.ax-code.com/install.ps1 | iex"

Ubuntu 24.04 이상

curl -fsSL https://download.ax-code.com/install | bash

Homebrew는 macOS CLI의 지원되는 대안으로 남습니다.

brew tap defai-digital/tap
brew trust defai-digital/tap
brew install defai-digital/tap/ax-code

Homebrew는 비공식 탭에 명시적 신뢰가 필요합니다. 이 탭 전체 신뢰는 defai-digital/tap에 게시된 현재와 미래의 모든 포뮬러, 캐스크, 외부 명령을 다룹니다. 공유 탭에는 CLI 포뮬러와 Desktop 캐스크가 모두 들어 있고, Homebrew는 설치를 해석하면서 두 정의를 모두 적재할 수 있습니다. 탭 전체 신뢰가 허용되지 않으면 릴리스 설치 프로그램을 사용합니다.

레거시 탭에서 기존 설치 옮기기

defai-digital/ax-code는 이제 마이그레이션 전용 탭입니다. AX Code 릴리스는 defai-digital/tap만 갱신합니다. 레거시 탭에서 설치했다면, Homebrew가 설치된 패키지의 탭 소유권을 옮길 수 있도록 갱신 전에 공유 탭을 추가합니다.

brew tap defai-digital/tap
brew trust --formula defai-digital/tap/ax-code
brew update
brew upgrade defai-digital/tap/ax-code
brew info defai-digital/tap/ax-code

설치가 공유 탭을 쓰는지 확인한 뒤 레거시 탭을 제거합니다.

brew untap defai-digital/ax-code

Homebrew가 여전히 옛 탭을 보고하면, 탭을 풀기 전에 brew reinstall defai-digital/tap/ax-code를 실행합니다. 레거시 저장소는 기존 설치가 마이그레이션을 발견할 수 있도록 접근 가능한 채로 남습니다.

버전이 고정된 Unix 설치 프로그램 검증

검사되고 버전이 고정된 Unix 설치에서는 먼저 같은 릴리스에서 설치 프로그램과 서명을 내려받습니다. 신뢰할 수 있는 minisign가 이미 있으면 다음을 사용합니다.

AX_INSTALL_VERSION="<release>"
AX_INSTALL_BASE="https://download.ax-code.com/releases/download/v${AX_INSTALL_VERSION}"
curl -fsSL "$AX_INSTALL_BASE/install" -o ax-code-install
curl -fsSL "$AX_INSTALL_BASE/install.minisig" -o ax-code-install.minisig
minisign -Vm ax-code-install -x ax-code-install.minisig -P 'RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO'
# Inspect ax-code-install before running it.
bash ax-code-install --version "$AX_INSTALL_VERSION" --no-modify-path

아카이브의 서명은 실행 전에 부트스트랩 스크립트를 인증하지 않습니다. 같은 출처에서 내려받은 다이제스트는 손상을 감지하지만 독립된 게시자 신원 검사는 아닙니다. 한 줄 경로는 HTTPS 배포 엔드포인트에 의존합니다.

한 줄 원격 실행은 편의 경로입니다. Windows 설치 프로그램은 시작한 뒤 내려받은 CLI ZIP을 minisign으로 검증하지만, irm | iex는 실행 전에 install.ps1 자체를 검증하지 않습니다.

minisign가 이미 PATH에 없으면 PowerShell 설치 프로그램은 download.ax-code.com에서 고정된 minisign 0.12 아카이브를 내려받고, SHA-256을 확인하며, 캐시하기 전에 추출한 실행 파일을 다시 확인합니다. 기본 설치 경로에서는 minisign을 수동으로 설치할 필요가 없습니다. PATH에 이미 있는 minisign 바이너리는 있는 그대로 사용됩니다.

보안에 민감한 환경에서는 설치 프로그램을 내려받고, minisign으로 검증하고, 검사하고, CI가 쓰는 릴리스 버전을 고정합니다.

$AX_CODE_VERSION = "<release>"
$AxCodeMinisignPublicKey = "RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO"
irm https://download.ax-code.com/install.ps1 -OutFile ax-code-install.ps1
irm https://download.ax-code.com/install.ps1.minisig -OutFile ax-code-install.ps1.minisig
# Optional: use a preinstalled minisign, or let install.ps1 bootstrap one when verifying the archive.
minisign -Vm ax-code-install.ps1 -x ax-code-install.ps1.minisig -P $AxCodeMinisignPublicKey
Get-Content .\ax-code-install.ps1
.\ax-code-install.ps1 -Version $AX_CODE_VERSION -NoModifyPath

검증할 수 없는 릴리스 다운로드를 의도적으로 받아들일 때만 AX_CODE_SKIP_MINISIGN_VERIFY=1를 설정합니다.

설치된 런타임을 검증합니다.

ax-code doctor

지원되는 사용자 설치는 macOS, Windows, Linux(glibc)에서 Runtime: Node vX.Y.Z (node-bundled)를 보고해야 합니다.

이 설치 프로그램은 CLI와 TUI 런타임을 배포합니다. Desktop 릴리스 소유권은 AX Coder에 있고, 새 Desktop 릴리스는 현재 동결되어 있습니다. 이 안내는 Desktop 설치나 업그레이드 채널을 제공하지 않습니다.

채널 행렬

node-bundled와 source는 패키지 관리자 이름이 아니라 런타임 모드입니다. 어떤 실행 파일이 앱 코드를 적재하는지를 설명합니다.

• node-bundled: Node.js가 번들된 릴리스 런타임을 적재합니다(지원되는 모든 사용자 설치 채널).
• source: Node가 체크아웃에서 파일을 직접 적재합니다.

compiled와 bun-bundled는 은퇴한 Bun 시대의 런타임 모드이며, 레거시 진단에만 남습니다. 지원되는 사용자 설치 채널이 아닙니다.

pnpm dev와 pnpm cli는 실행 전에 저장소 TypeScript로 작업 공간 SDK(packages/sdk/js)를 dist로 컴파일하므로, 새 체크아웃이 수동 SDK 빌드 없이 실행됩니다. 그 단계는 typescript/bin/tsc를 node를 통해 직접 호출하므로, node_modules/.bin가 연결되어 있는지에 의존하지 않습니다. 번들 경로(pnpm run setup:cli와 pnpm --dir packages/ax-code run build)는 여전히 먼저 pnpm --dir packages/sdk/js run build가 필요합니다.

플랫폼 정책

• macOS: 문서화된 기본 CLI 경로로 bash 릴리스 설치 프로그램을 사용합니다. ~/.ax-code 아래에 설치하고, 필요할 때 고정된 Minisign을 준비하며, 릴리스 아카이브를 검증하고, Homebrew가 필요하지 않습니다. darwin-arm64 아카이브에는 로컬 추론용 자체 포함 AX Engine 사이드카가 들어 있습니다. 기여자 빌드는 pnpm run setup:cli를 사용합니다.
• 지원되는 Homebrew 경로는 완전 수식 설치 명령을 쓰기 전에 defai-digital/tap를 명시적으로 탭하고 신뢰합니다. 탭 전체 신뢰는 공유 탭의 현재와 미래 포뮬러, 캐스크, 외부 명령을 모두 포함합니다. 그 신뢰 범위가 허용되지 않으면 bash 릴리스 설치 프로그램을 사용합니다.
• Linux CLI: amd64와 arm64(glibc)의 Ubuntu Desktop과 Server 24.04 LTS 이상에 bash 설치 프로그램을 사용합니다. 릴리스 빌드는 glibc 기준이 24.04 이상과 호환되도록 Ubuntu 24.04 러너에서 ax-code-linux-x64.tar.gz와 ax-code-linux-arm64.tar.gz를 만듭니다. Musl(Alpine)은 현재 릴리스 아카이브가 지원하지 않습니다.
• macOS CLI 아카이브: 릴리스 빌드는 darwin-arm64만 게시합니다(Apple Silicon). Intel macOS는 현재 CLI와 Desktop 패키지의 지원 설치 대상이 아닙니다.
• Windows CLI: 네이티브 PowerShell 설치 프로그램을 사용합니다. GitHub 릴리스 자산을 사용자 로컬 디렉터리에 설치하고, -NoModifyPath가 제공되지 않으면 사용자 PATH를 갱신합니다. 추출 전에 고정된 공개 키로 내려받은 ZIP을 검증하고, AX_CODE_SKIP_MINISIGN_VERIFY=1가 의도적으로 설정되지 않으면 닫힌 실패를 합니다. minisign가 없으면 설치 프로그램은 download.ax-code.com에서 고정된 minisign 0.12 아카이브를 %LOCALAPPDATA%\ax-code\tools\minisign 안으로 내려받고, 캐시하기 전에 추출한 실행 파일을 확인합니다. PATH에 이미 있는 minisign 바이너리는 있는 그대로 사용됩니다. 사용자 로컬 설치와 PATH 항목을 제거하려면 -Uninstall를 사용합니다.
• Windows Desktop: GitHub Releases의 서명된 Electron 설치 프로그램을 사용하며, 이름은 AX-Code-<version>-win-x64.exe 또는 AX-Code-<version>-win-arm64.exe입니다. 기대 Authenticode 게시자는 DEFAI Private Limited입니다. install.ps1를 Desktop 설치 프로그램으로 설명하지 않습니다. 무인 설치는 .\AX-Code-<version>-win-x64.exe /S입니다(NSIS).
• Winget: 패키지 매니페스트는 pnpm exec tsx tools/winget/generate-manifests.ts --version <ver>로 생성되어 microsoft/winget-pkgs에 제출됩니다(tools/winget/README.md를 보십시오). 업스트림에 게시되기 전까지 GitHub Releases가 Windows 설치의 진실의 원천으로 남습니다.
• npm: 지원되는 설치나 업그레이드 채널이 아닙니다.

한 줄 원격 실행은 편의 경로이며 유일한 경로는 아닙니다. 문서에는 검사할 수 있는, Windows에서는 minisign으로 검증된 설치 흐름을 유지하고, CI에는 고정된 버전을 쓰며, 플랫폼 설치 프로그램은 ax-code --version를 검증하고 ax-code doctor가 그 플랫폼의 기대 런타임 모드를 보고하는지를 검증하는 설치 행렬 커버리지가 있을 때만 문서화합니다.

엔터프라이즈와 무인 설치

Windows CLI(사용자 로컬, 관리자 없음)

# Pin version in CI/images
$env:AX_CODE_VERSION = "7.9.4"
irm https://download.ax-code.com/releases/download/v$env:AX_CODE_VERSION/install.ps1 -OutFile install.ps1
# Optional: verify install.ps1.minisig first (see SECURITY.md)
.\install.ps1 -Version $env:AX_CODE_VERSION -NoModifyPath
# Then add %USERPROFILE%\.ax-code\bin to the machine/user PATH via your MDM.

macOS(사용자 로컬, Homebrew, MDM)

Homebrew 없이 사용자 로컬 CLI를 설치하려면 릴리스 설치 프로그램을 사용합니다.

curl -fsSL https://download.ax-code.com/install | bash

관리되는 Mac은 CLI 갱신이 탭을 따르도록 Homebrew 포뮬러를 쓸 수 있습니다.

brew tap defai-digital/tap
brew trust defai-digital/tap
brew install defai-digital/tap/ax-code

MDM으로 패키지된 DMG 설치에는 GitHub Releases의 공증된 AX-Code-*-mac-arm64.dmg를 사용하고, 정책이 공급망 검사를 요구하면 분리된 .minisig를 검증합니다.

Winget 가용성

검증된 커뮤니티 CLI 패키지를 쓸 수 없으면 공개 설치 프로그램을 사용합니다. GitHub에 호스트된 매니페스트 묶음이 익명으로 접근 가능하다고 가정하지 않습니다.

갱신

활성 설치를 소유한 채널을 고릅니다.

기존 레거시 탭 사용자는 공유 탭 마이그레이션을 따라야 합니다. 두 번째 설치가 PATH에서 첫 번째를 가릴 수 있습니다. 채널을 바꾸기 전에 which -a ax-code, ax-code --version, ax-code doctor를 사용합니다. 독립 버전을 설치해도 Homebrew는 제거되지 않습니다. 채널 사이 이동은 의도적으로만 하고, 세션과 구성 데이터는 유지합니다.

Unix 자체 업그레이드는 대상 릴리스에서 설치 프로그램을 가져오고 SHA-256 사이드카가 필요합니다. 설치 프로그램이나 다이제스트가 없으면 업그레이드가 멈춥니다. 변하는 main으로의 폴백은 없습니다. 설치 프로그램 자산이 없는 릴리스에서 더 오래된 아카이브를 설치하려면, 현재 릴리스된 설치 프로그램을 내려받아 검증한 뒤 --version <older-version>와 함께 실행합니다.

독립 Unix 설치는 ~/.ax-code/bin/ax-code를 ~/.ax-code/versions/ 아래의 고유한 런타임 세대로 가는 안정적인 심볼릭 링크로 사용합니다. 설치 프로그램은 그 링크를 바꾸기 전에 새 트리 전체를 검증합니다. 버전을 다시 설치하면 새 세대가 만들어집니다. 이미 실행 중인 에이전트가 자신의 모듈을 계속 적재할 수 있도록 옛 세대와 레거시 런타임 파일을 유지합니다. 실행 중인 에이전트를 다시 시작하지는 않습니다. 새 버전을 쓰려면 새 클라이언트와 런타임을 시작합니다. 런타임 재시작 전에 활성 작업을 명시적으로 멈춥니다. Homebrew 파일은 Homebrew가 계속 관리합니다.

롤백에는 --version <previous-version>가 있는 검증된 설치 프로그램을 사용합니다. 유지된 각 세대의 version 파일이 그 릴리스를 식별합니다. 옛 세대는 자동으로 정리되지 않습니다. 그것을 쓰는 모든 프로세스를 멈춘 뒤에 쓰지 않는 세대를 제거할 수 있습니다. 제거 중에는 필요하면 --keep-data --keep-config로 세션과 구성을 유지합니다. 바이너리 제거 안내를 따르고, 쓰지 않는 런타임 세대는 그 프로세스가 멈춘 뒤에만 따로 제거합니다. 다른 구성이나 개인 파일을 거기에 저장했다면 .ax-code 폴더 전체를 삭제하지 않습니다.

동시 Unix 설치는 .install-lock 디렉터리 위치와 함께 실패합니다. 갑자기 죽인 설치 프로그램이 그 빈 디렉터리를 남길 수 있습니다. 낡은 잠금을 제거하고 다시 시도하기 전에 활성 설치 프로그램이 있는지 확인합니다. 설치가 실행 중일 때는 제거하지 않습니다.

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://download.ax-code.com/install.ps1 | iex"

Windows에서 이것은 CLI를 갱신합니다. CLI 설치와 사용자 PATH 항목을 제거하려면 다음을 사용합니다.

irm https://download.ax-code.com/install.ps1 -OutFile ax-code-install.ps1
.\ax-code-install.ps1 -Uninstall

기여자 실행기 동작

이 절은 인가된 소스 체크아웃이 필요합니다. 공개 설치나 업그레이드에는 필요하지 않습니다. 소스 접근을 보십시오.

pnpm run setup:cli는 의도적으로 기본이 컴파일된 경로입니다. packages/ax-code/dist/... 아래의 로컬 번들 바이너리를 빌드하거나 재사용하고, 그 바이너리를 가리키는 전역 실행기를 설치합니다. 이렇게 하면 로컬 패키지 런타임 검사가 Homebrew와 curl 설치 사용자가 실행하는 것에 가깝게 유지됩니다.

그 실행기는 보통 ~/.local/bin 또는 PNPM_HOME에 놓이며, 이는 전형적으로 Homebrew보다 PATH에서 앞입니다. Homebrew가 이미 ax-code를 제공하면, setup:cli는 체크아웃을 ax-code-src로 설치하고 이전에 쓴 ax-code 래퍼를 제거하므로 brew upgrade ax-code가 ax-code 명령을 계속 갱신합니다. pnpm run setup:cli -- --override-homebrew는 체크아웃이 ax-code를 인수하기를 의도할 때만 사용합니다. ax-code doctor는 그 덮어쓰기를 PATH launchers로 계속 경고합니다.

패키지된 런타임에 영향을 줘야 하는 소스 변경 뒤에는, 전역 실행기를 시험하기 전에 번들 바이너리를 새로 고칩니다.

pnpm --dir packages/ax-code run build -- --single
pnpm run setup:cli -- --rebuild
ax-code-src --version   # or `ax-code` if Homebrew is not installed

체크아웃 명령이 소스 파일에서 Node를 통해 이 체크아웃을 실행하기를 의도할 때만 소스 실행기를 사용합니다.

pnpm run setup:cli -- --source
ax-code-src doctor      # or `ax-code doctor` if Homebrew is not installed

소스 실행기는 Runtime: Node vX.Y.Z (source)를 보고해야 합니다.

도구 모음 요구

저장소는 pnpm@10.33.4를 루트 packageManager 필드와 only-allow pnpm를 통해 강제합니다. preinstall 훅이 pnpm이 아닌 설치를 막고, 루트 pre<script> 훅이 같은 요구로 npm run <script>를 막습니다. Node.js는 루트 package.json 엔진(>=26)과 일치해야 하며, 그 엔진은 소스 모드 TUI 명령에 --experimental-ffi도 제공합니다.

루트 pnpm test는 사용하지 않습니다. 루트 스크립트는 의도적으로 do not run tests from root로 종료합니다. packages/ax-code의 경우 packages/ax-code/에서 테스트를 실행합니다.

Homebrew 설치는 자동 배경 업그레이드 없이 갱신 알림을 받습니다. 명시적으로 업그레이드하거나 오래된 Homebrew 케그를 정리하기 전에 활성 에이전트 실행을 마칩니다.