Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Canaux d'installation et de runtime

Statut : actif Portée : état actuel Dernière revue : 2026-10-09 Responsable : runtime AX Code

Le README racine conserve le chemin d’installation principal. Cette page est la source de vérité pour les canaux d’installation CLI pris en charge, les libellés de runtime ax-code doctor, le comportement du lanceur local et le comportement public de mise à niveau.

Disponibilité publique

Les installateurs de version publique et les archives de runtime signées sont distribués par download.ax-code.com. L’installation n’exige pas d’identifiants GitHub privés.

AX Code et le SDK ne prennent en charge que Node.js 26 ou une version ultérieure. Les installateurs autonomes embarquent un runtime Node.js vérifié. Les checkouts de sources et les applications SDK fondées sur Node.js doivent fournir Node.js 26+ ; l’installation des paquets refuse les versions plus anciennes de Node.js.

AX Code Standard reste gratuit pour un usage personnel et commercial, sous sa licence actuelle. L’accès aux sources de développement est géré à part de la distribution publique. Les composants Business propriétaires prévus ont une licence distincte ; cela ne change pas la licence de Standard. Voir Standard et Business pour le détail et le guide du site pour les mises à jour publiques de l’installation. Les installateurs publics et leurs artefacts signés doivent être joignables et vérifiés avant que le site n’annonce une commande d’installation en une ligne.

Disponibilité des versions

Pousser une étiquette git vMAJOR.MINOR.PATCH démarre le flux de publication. L’ index des versions publiques n’affiche une version qu’une fois ce flux a signé les artefacts et publié. Jusque-là, Latest reste sur l’étiquette publiée précédente. Après la réussite de la validation, les mainteneurs peuvent voir un brouillon de la nouvelle étiquette ; ce n’est pas le Latest public.

Pour les installations existantes, suivez Mise à niveau et reprise.

Chemin recommandé

Utilisez un installateur empaqueté pris en charge, sauf si vous développez depuis un checkout. L’installateur de version est le chemin CLI principal sur macOS et Linux ; utilisez l’installateur PowerShell natif sur Windows.

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 reste une alternative prise en charge pour la CLI macOS :

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

Homebrew exige une confiance explicite pour les taps non officiels. Cette confiance sur l’ensemble du tap couvre toutes les formules actuelles et futures, les casks et les commandes externes publiées dans defai-digital/tap. Le tap partagé contient la formule CLI et le cask Desktop, et Homebrew peut charger les deux définitions en résolvant une installation. Utilisez l’installateur de version si la confiance sur l’ensemble du tap n’est pas acceptable.

Déplacer une installation existante hors du tap hérité

defai-digital/ax-code n’est plus qu’un tap de migration. Les versions d’AX Code ne mettent à jour que defai-digital/tap. Si vous avez installé depuis le tap hérité, ajoutez le tap partagé avant la mise à jour, afin que Homebrew puisse transférer la propriété du tap du paquet installé :

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

Après avoir confirmé que l’installation utilise le tap partagé, retirez le tap hérité :

brew untap defai-digital/ax-code

Si Homebrew signale encore l’ancien tap, exécutez brew reinstall defai-digital/tap/ax-code avant de le détacher. Le dépôt hérité reste accessible pour que les installations existantes découvrent la migration.

Vérifier un installateur Unix épinglé sur une version

Pour une installation Unix inspectée et épinglée sur une version, téléchargez d’abord l’installateur et sa signature depuis la même version. Avec un minisign de confiance déjà disponible :

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

La signature de l’archive n’authentifie pas le script d’amorçage avant l’exécution. Un condensé téléchargé depuis la même origine détecte une corruption, mais ne constitue pas un contrôle indépendant de l’identité de l’éditeur. Le chemin en une ligne s’appuie sur le point de distribution HTTPS.

L’exécution distante en une ligne est un chemin de commodité. L’installateur Windows vérifie le ZIP de la CLI téléchargé avec Minisign après son démarrage, mais irm | iex ne vérifie pas install.ps1 lui-même avant l’exécution.

Si minisign n’est pas déjà dans PATH, l’installateur PowerShell télécharge l’archive Minisign 0.12 épinglée depuis download.ax-code.com, contrôle son SHA-256, puis contrôle de nouveau l’exécutable extrait avant de le mettre en cache. Vous n’avez pas à installer Minisign à la main pour le chemin d’installation par défaut. Un binaire minisign déjà dans PATH est utilisé tel quel.

Pour les environnements sensibles à la sécurité, téléchargez l’installateur, vérifiez-le avec Minisign, inspectez-le et épinglez la version de publication utilisée par la 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

Ne définissez AX_CODE_SKIP_MINISIGN_VERIFY=1 que si vous acceptez volontairement un téléchargement de version invérifiable.

Vérifiez le runtime installé :

ax-code doctor

Les installations utilisateur prises en charge doivent indiquer Runtime: Node vX.Y.Z (node-bundled) sur macOS, Windows et Linux (glibc).

Ces installateurs distribuent le runtime CLI/TUI. La propriété des versions Desktop relève d’AX Coder, et les nouvelles versions Desktop sont actuellement gelées. Ce guide ne fournit pas de canal d’installation ni de mise à niveau Desktop.

Matrice des canaux

node-bundled et source sont des modes de runtime, pas des noms de gestionnaires de paquets. Ils indiquent quel exécutable charge le code de l’application :

• node-bundled : Node.js charge le runtime de version empaqueté (tous les canaux d’installation utilisateur pris en charge).
• source : Node.js charge les fichiers directement depuis un checkout.

compiled et bun-bundled sont des modes de runtime de l’ère Bun, retirés et conservés seulement pour le diagnostic hérité. Ce ne sont pas des canaux d’installation utilisateur pris en charge.

pnpm dev et pnpm cli compilent le SDK de l’espace de travail (packages/sdk/js) vers dist avec le TypeScript du dépôt avant le lancement, afin qu’un checkout neuf s’exécute sans construction manuelle du SDK. Cette étape invoque typescript/bin/tsc directement via node, donc elle ne dépend pas d’un node_modules/.bin lié. Les chemins empaquetés (pnpm run setup:cli et pnpm --dir packages/ax-code run build) exigent encore pnpm --dir packages/sdk/js run build d’abord.

Politique des plateformes

• macOS : utilisez l’installateur de version bash comme chemin CLI documenté principal. Il installe sous ~/.ax-code, amorce Minisign épinglé au besoin, vérifie l’archive de version et n’exige pas Homebrew. L’archive darwin-arm64 inclut un sidecar AX Engine autonome pour l’inférence locale. Les constructions de contributeurs utilisent pnpm run setup:cli.
• Le chemin Homebrew pris en charge ajoute le tap et fait confiance explicitement à defai-digital/tap avant d’utiliser des commandes d’installation pleinement qualifiées. La confiance sur l’ensemble du tap inclut toutes les formules, casks et commandes externes actuels et futurs du tap partagé ; utilisez l’installateur de version bash lorsque ce périmètre de confiance n’est pas acceptable.
• CLI Linux : utilisez l’installateur bash pour Ubuntu Desktop/Server 24.04 LTS et les versions plus récentes, sur amd64 et arm64 (glibc). Les constructions de version produisent ax-code-linux-x64.tar.gz et ax-code-linux-arm64.tar.gz sur des exécuteurs Ubuntu 24.04, afin que la base glibc reste compatible avec 24.04 et au-delà. Musl (Alpine) n’est pas pris en charge par les archives de version actuelles.
• Archives CLI macOS : les constructions de version ne publient que darwin-arm64 (Apple Silicon). macOS Intel n’est pas une cible d’installation prise en charge pour les paquets CLI et Desktop actuels.
• CLI Windows : utilisez l’installateur PowerShell natif. Il installe l’artefact de version GitHub dans un répertoire local à l’utilisateur et met à jour le PATH utilisateur, sauf si -NoModifyPath est fourni. Il vérifie le ZIP téléchargé avec la clé publique épinglée avant l’extraction et échoue en position fermée, sauf si AX_CODE_SKIP_MINISIGN_VERIFY=1 est défini volontairement. Si minisign est absent, l’installateur télécharge l’archive Minisign 0.12 épinglée depuis download.ax-code.com vers %LOCALAPPDATA%\ax-code\tools\minisign et contrôle l’exécutable extrait avant de le mettre en cache. Un binaire minisign déjà dans PATH est utilisé tel quel. Utilisez -Uninstall pour retirer l’installation locale utilisateur et l’entrée de PATH.
• Desktop Windows : utilisez l’installateur Electron signé de GitHub Releases, nommé AX-Code-<version>-win-x64.exe ou AX-Code-<version>-win-arm64.exe. L’éditeur Authenticode attendu est DEFAI Private Limited. Ne décrivez pas install.ps1 comme un installateur Desktop. Installation silencieuse : .\AX-Code-<version>-win-x64.exe /S (NSIS).
• Winget : les manifestes de paquets sont générés avec pnpm exec tsx tools/winget/generate-manifests.ts --version <ver> et soumis à microsoft/winget-pkgs (voir tools/winget/README.md). Tant qu’ils ne sont pas publiés en amont, GitHub Releases reste la source de vérité pour l’installation Windows.
• npm : ce n’est pas un canal d’installation ni de mise à niveau pris en charge.

L’exécution distante en une ligne est un chemin de commodité, pas le seul. Conservez dans la documentation un flux d’installateur inspectable (et, sous Windows, vérifié par Minisign), utilisez des versions épinglées en CI, et ne documentez les installateurs de plateforme qu’avec une couverture de la matrice d’installation qui vérifie ax-code --version et vérifie que ax-code doctor signale le mode de runtime attendu pour cette plateforme.

Installations d'entreprise et sans opérateur

CLI Windows (locale utilisateur, sans administrateur)

# 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 (locale utilisateur / Homebrew / MDM)

Utilisez l’installateur de version pour une installation CLI locale utilisateur sans Homebrew :

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

Les Mac gérés peuvent utiliser la formule Homebrew, afin que les mises à jour de la CLI suivent le tap :

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

Pour les installations DMG empaquetées par un MDM, utilisez le AX-Code-*-mac-arm64.dmg notarié issu de GitHub Releases et vérifiez la signature détachée .minisig lorsque la politique exige des contrôles de chaîne d’approvisionnement.

Disponibilité de Winget

Utilisez l’installateur public, sauf si un paquet CLI communautaire vérifié est disponible. Ne supposez pas que les lots de manifestes hébergés sur GitHub sont accessibles de façon anonyme.

Mise à jour

Choisissez le canal qui possède l’installation active :

Les utilisateurs encore sur le tap hérité doivent suivre la migration vers le tap partagé. Une seconde installation peut masquer la première dans PATH ; utilisez which -a ax-code, ax-code --version et ax-code doctor avant de changer de canal. Installer la version autonome ne désinstalle pas Homebrew. Ne changez de canal que délibérément, et conservez vos données de session et de configuration.

Les mises à niveau automatiques Unix récupèrent l’installateur depuis la version cible et exigent son fichier annexe SHA-256. Un installateur ou un condensé manquant arrête la mise à niveau ; il n’existe pas de repli vers une branche main mutable. Pour installer une archive plus ancienne d’une version sans artefacts d’installateur, téléchargez et vérifiez un installateur publié actuel, puis exécutez-le avec --version <older-version>.

Les installations Unix autonomes utilisent ~/.ax-code/bin/ax-code comme lien symbolique stable vers une génération de runtime unique sous ~/.ax-code/versions/. L’installateur vérifie l’arbre nouveau dans son entier avant de basculer ce lien. Réinstaller une version crée une génération neuve. Les anciennes générations et les fichiers de runtime hérités sont conservés, afin que les agents déjà lancés puissent continuer à charger leurs propres modules. Les agents en cours ne sont pas redémarrés. Démarrez un nouveau client ou runtime pour utiliser la nouvelle version ; arrêtez explicitement le travail actif avant un redémarrage du runtime. Les fichiers Homebrew restent gérés par Homebrew.

Pour un retour arrière, utilisez un installateur vérifié avec --version <previous-version>. Le fichier version de chaque génération conservée identifie sa version. Les anciennes générations ne sont pas élaguées automatiquement ; après avoir arrêté tous les processus qui les utilisent, vous pouvez retirer les générations inutilisées. Lors de la désinstallation, conservez les sessions et la configuration avec --keep-data --keep-config si besoin ; suivez le guide de retrait du binaire et ne retirez les générations de runtime inutilisées qu’après l’arrêt de leurs processus. Ne supprimez pas l’ensemble du dossier .ax-code si vous y avez placé d’autres fichiers de configuration ou personnels.

Une installation Unix simultanée échoue en indiquant l’emplacement du répertoire .install-lock. Un installateur interrompu brutalement peut laisser ce répertoire vide. Vérifiez qu’aucun installateur n’est actif avant de retirer un verrou périmé et de réessayer ; ne le retirez pas pendant qu’une installation est en cours.

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

Sous Windows, cela met à jour la CLI. Pour retirer l’installation de la CLI et son entrée de PATH utilisateur :

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

Comportement du lanceur contributeur

Cette section exige un checkout de sources autorisé. Elle n’est pas nécessaire pour une installation ou une mise à niveau publique ; voir Accès aux sources.

pnpm run setup:cli suit volontairement un chemin compilé par défaut. Il construit ou réutilise le binaire local empaqueté sous packages/ax-code/dist/... et installe un lanceur global qui pointe vers ce binaire. Les contrôles du runtime empaqueté local restent ainsi proches de ce qu’exécutent les utilisateurs de Homebrew et de l’installateur curl.

Ce lanceur se place en général dans ~/.local/bin ou PNPM_HOME, en général plus tôt dans PATH que Homebrew. Si Homebrew fournit déjà ax-code, setup:cli installe le checkout sous le nom ax-code-src et retire un enveloppeur ax-code écrit auparavant, afin que brew upgrade ax-code continue de mettre à jour la commande ax-code. N’utilisez pnpm run setup:cli -- --override-homebrew que si vous voulez volontairement que le checkout prenne le contrôle de ax-code. ax-code doctor signale encore cette prise de contrôle sous la forme PATH launchers.

Après des changements de sources qui doivent affecter le runtime empaqueté, rafraîchissez le binaire empaqueté avant de tester le lanceur global :

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

N’utilisez le lanceur de sources que si vous voulez volontairement que la commande du checkout exécute ce checkout par Node.js, à partir des fichiers sources :

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

Le lanceur de sources doit indiquer Runtime: Node vX.Y.Z (source).

Exigences de la chaîne d'outils

Le dépôt impose pnpm@10.33.4 par le champ racine packageManager et par only-allow pnpm : le crochet preinstall bloque les installations autres que pnpm, et les crochets racine pre<script> bloquent npm run <script> avec la même exigence. Node.js doit correspondre au moteur racine package.json (>=26), qui fournit aussi --experimental-ffi pour les commandes TUI en mode source.

N’utilisez pas le pnpm test racine ; le script racine se termine volontairement avec do not run tests from root. Pour packages/ax-code, lancez les tests depuis packages/ax-code/.

Les installations Homebrew reçoivent des avis de mise à jour, sans mise à niveau automatique en arrière-plan. Terminez les exécutions d’agent en cours avant de mettre à niveau explicitement ou de nettoyer d’anciens kegs Homebrew.