Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Canali di installazione e runtime

Stato: Attivo Ambito: stato attuale Ultima revisione: 2026-10-09 Responsabile: runtime di ax-code

Il README alla radice tiene il percorso di installazione primario. Questa pagina è la fonte di verità per i canali di installer CLI supportati, le etichette di runtime ax-code doctor, il comportamento del launcher locale e il comportamento pubblico di aggiornamento.

Disponibilità pubblica

Gli installer di rilascio pubblici e gli archivi di runtime firmati sono distribuiti tramite download.ax-code.com. L’installazione non richiede credenziali GitHub private.

AX Code e l’SDK supportano solo Node.js 26 o successivo. Gli installer autonomi includono un runtime Node verificato. I checkout dei sorgenti e le applicazioni SDK basate su Node devono fornire Node.js 26 o successivo; l’installazione dei pacchetti rifiuta le versioni di Node più vecchie.

AX Code Standard resta gratuito per l’uso personale e commerciale sotto la licenza esistente. L’accesso ai sorgenti di sviluppo è gestito separatamente dalla distribuzione pubblica. I componenti Business proprietari pianificati hanno una licenza separata; questo non cambia la licenza di Standard. Vedi Standard e Business per i dettagli e la guida del sito per gli aggiornamenti pubblici di installazione. Gli installer pubblici e i loro asset firmati devono essere raggiungibili e verificati prima che il sito pubblicizzi un comando di installazione di una riga.

Disponibilità dei rilasci

Inviare un tag git vMAJOR.MINOR.PATCH avvia il flusso di rilascio. L’indice pubblico dei rilasci mostra una versione solo dopo che quel flusso ha firmato gli asset e li ha pubblicati. Fino ad allora, Latest resta sul tag pubblicato precedente. Dopo che la validazione riesce, i responsabili possono vedere una bozza per il nuovo tag; non è il Latest pubblico.

Per le installazioni esistenti, segui Aggiornamento e recupero.

Percorso consigliato

Usa un installer impacchettato supportato, salvo che tu stia sviluppando da un checkout. L’installer di rilascio è il percorso CLI primario su macOS e Linux; su Windows usa l’installer PowerShell nativo.

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 resta un’alternativa supportata per la CLI su macOS:

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

Homebrew richiede una fiducia esplicita per i tap non ufficiali. Questa fiducia sull’intero tap copre tutte le formule attuali e future, i cask e i comandi esterni pubblicati in defai-digital/tap. Il tap condiviso contiene sia la formula della CLI sia il cask Desktop, e Homebrew può caricare entrambe le definizioni mentre risolve un’installazione. Usa l’installer di rilascio se la fiducia sull’intero tap non è accettabile.

Spostare un'installazione esistente dal tap legacy

defai-digital/ax-code è ora un tap solo di migrazione. I rilasci di AX Code aggiornano solo defai-digital/tap. Se hai installato dal tap legacy, aggiungi il tap condiviso prima di aggiornare, così Homebrew può spostare la proprietà del tap del pacchetto installato:

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

Dopo aver confermato che l’installazione usa il tap condiviso, rimuovi il tap legacy:

brew untap defai-digital/ax-code

Se Homebrew riporta ancora il vecchio tap, esegui brew reinstall defai-digital/tap/ax-code prima di staccarlo. Il repository legacy resta accessibile perché le installazioni esistenti scoprano la migrazione.

Verificare un installer Unix fissato a una versione

Per un’installazione Unix ispezionata e fissata a una versione, scarica prima l’installer e la sua firma dallo stesso rilascio. Con un minisign attendibile già disponibile:

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 firma dell’archivio non autentica lo script di bootstrap prima dell’esecuzione. Un digest scaricato dalla stessa origine rileva la corruzione, ma non è un controllo indipendente dell’identità dell’editore. Il percorso di una riga si appoggia all’endpoint di distribuzione HTTPS.

L’esecuzione remota di una riga è un percorso di comodità. L’installer Windows verifica lo ZIP della CLI scaricato con minisign dopo l’avvio, ma irm | iex non verifica install.ps1 stesso prima dell’esecuzione.

Se minisign non è già nel PATH, l’installer PowerShell scarica l’archivio minisign 0.12 fissato da download.ax-code.com, ne controlla lo SHA-256 e controlla di nuovo l’eseguibile estratto prima di metterlo in cache. Non devi installare minisign a mano per il percorso di installazione predefinito. Un binario minisign già nel PATH viene usato così com’è.

Per gli ambienti sensibili alla sicurezza, scarica l’installer, verificalo con minisign, ispezionalo e fissa la versione di rilascio usata dalla 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

Imposta AX_CODE_SKIP_MINISIGN_VERIFY=1 solo quando accetti di proposito un download di rilascio non verificabile.

Verifica il runtime installato:

ax-code doctor

Le installazioni utente supportate dovrebbero riportare Runtime: Node vX.Y.Z (node-bundled) su macOS, Windows e Linux (glibc).

Questi installer distribuiscono il runtime CLI/TUI. La proprietà dei rilasci Desktop è in AX Coder, e i nuovi rilasci Desktop sono oggi congelati. Questa guida non fornisce un canale di installazione o di aggiornamento di Desktop.

Matrice dei canali

node-bundled e source sono modalità di runtime, non nomi di gestori di pacchetti. Descrivono quale eseguibile carica il codice dell’app:

• node-bundled: Node.js carica il runtime di rilascio incluso (tutti i canali di installazione utente supportati).
• source: Node carica i file direttamente da un checkout.

compiled e bun-bundled sono modalità di runtime ritirate dell’era Bun, conservate solo per la diagnostica legacy. Non sono canali di installazione utente supportati.

pnpm dev e pnpm cli compilano l’SDK del workspace (packages/sdk/js) in dist con il TypeScript del repository prima dell’avvio, così un checkout nuovo gira senza una build manuale dell’SDK. Il passo invoca typescript/bin/tsc tramite node direttamente, quindi non dipende dal fatto che node_modules/.bin sia collegato. I percorsi inclusi (pnpm run setup:cli e pnpm --dir packages/ax-code run build) hanno ancora bisogno prima di pnpm --dir packages/sdk/js run build.

Policy delle piattaforme

• macOS: usa l’installer di rilascio bash come percorso CLI documentato primario. Installa sotto ~/.ax-code, prepara Minisign fissato quando serve, verifica l’archivio di rilascio e non richiede Homebrew. L’archivio darwin-arm64 include un sidecar autonomo di AX Engine per l’inferenza locale. Le build di chi contribuisce usano pnpm run setup:cli.
• Il percorso Homebrew supportato fa il tap e si fida in modo esplicito di defai-digital/tap prima di usare comandi di installazione pienamente qualificati. La fiducia sull’intero tap include tutte le formule, i cask e i comandi esterni attuali e futuri nel tap condiviso; usa l’installer di rilascio bash quando quell’ambito di fiducia non è accettabile.
• CLI Linux: usa l’installer bash per Ubuntu Desktop/Server 24.04 LTS e successivi su amd64 e arm64 (glibc). Le build di rilascio producono ax-code-linux-x64.tar.gz e ax-code-linux-arm64.tar.gz su runner Ubuntu 24.04, così la linea di base glibc resta compatibile con 24.04 e successivi. Musl (Alpine) non è supportato dagli archivi di rilascio attuali.
• Archivi CLI di macOS: le build di rilascio pubblicano solo darwin-arm64 (Apple Silicon). macOS Intel non è un bersaglio di installazione supportato per i pacchetti CLI e Desktop attuali.
• CLI Windows: usa l’installer PowerShell nativo. Installa l’asset di rilascio GitHub in una directory locale all’utente e aggiorna il PATH utente, salvo che sia fornito -NoModifyPath. Verifica lo ZIP scaricato con la chiave pubblica fissata prima dell’estrazione e si chiude in fallimento salvo che AX_CODE_SKIP_MINISIGN_VERIFY=1 sia impostato di proposito. Se manca minisign, l’installer scarica l’archivio minisign 0.12 fissato da download.ax-code.com in %LOCALAPPDATA%\ax-code\tools\minisign e controlla l’eseguibile estratto prima di metterlo in cache. Un binario minisign già nel PATH viene usato così com’è. Usa -Uninstall per rimuovere l’installazione locale all’utente e la voce di PATH.
• Desktop Windows: usa l’installer Electron firmato da GitHub Releases, chiamato AX-Code-<version>-win-x64.exe o AX-Code-<version>-win-arm64.exe. L’editore Authenticode atteso è DEFAI Private Limited. Non descrivere install.ps1 come un installer Desktop. Installazione silenziosa: .\AX-Code-<version>-win-x64.exe /S (NSIS).
• Winget: i manifest dei pacchetti sono generati con pnpm exec tsx tools/winget/generate-manifests.ts --version <ver> e inviati a microsoft/winget-pkgs (vedi tools/winget/README.md). Finché non sono pubblicati a monte, GitHub Releases resta la fonte di verità dell’installazione Windows.
• npm: non è un canale supportato di installazione o di aggiornamento.

L’esecuzione remota di una riga è un percorso di comodità, non l’unico. Tieni nella documentazione un flusso di installer ispezionabile (e, su Windows, verificato con minisign), usa versioni fissate nella CI e documenta gli installer di piattaforma solo con una copertura della matrice di installazione che verifichi ax-code --version e verifichi che ax-code doctor riporti la modalità di runtime attesa per quella piattaforma.

Installazioni aziendali e non presidiate

CLI Windows (locale all'utente, senza amministratore)

# 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 all'utente / Homebrew / MDM)

Usa l’installer di rilascio per un’installazione CLI locale all’utente, senza Homebrew:

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

I Mac gestiti possono usare la formula Homebrew, così gli aggiornamenti della CLI seguono il tap:

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

Per le installazioni DMG impacchettate via MDM, usa il AX-Code-*-mac-arm64.dmg notarizzato da GitHub Releases e verifica il .minisig staccato quando la policy richiede controlli della catena di fornitura.

Disponibilità di Winget

Usa l’installer pubblico, salvo che sia disponibile un pacchetto CLI di comunità verificato. Non dare per scontato che i bundle di manifest ospitati su GitHub siano accessibili in modo anonimo.

Aggiornamento

Scegli il canale che possiede l’installazione attiva:

Gli utenti del tap legacy esistente dovrebbero seguire la migrazione al tap condiviso. Una seconda installazione può oscurare la prima nel PATH; usa which -a ax-code, ax-code --version e ax-code doctor prima di cambiare canale. Installare la versione autonoma non disinstalla Homebrew. Passa da un canale all’altro solo di proposito, e conserva i dati di sessione e di configurazione.

Gli auto-aggiornamenti Unix recuperano l’installer dal rilascio di destinazione e richiedono il suo sidecar SHA-256. Un installer o un digest mancante ferma l’aggiornamento; non c’è un ripiego sul main mutabile. Per installare un archivio più vecchio da un rilascio senza asset di installer, scarica e verifica un installer di rilascio corrente, poi eseguilo con --version <older-version>.

Le installazioni Unix autonome usano ~/.ax-code/bin/ax-code come symlink stabile verso una generazione di runtime unica sotto ~/.ax-code/versions/. L’installer verifica l’intero nuovo albero prima di commutare quel collegamento. Reinstallare una versione crea una generazione nuova. Conserva le generazioni vecchie e i file di runtime legacy, così gli agenti già in esecuzione possono continuare a caricare i propri moduli. Non riavvia gli agenti in esecuzione. Avvia un nuovo client o runtime per usare la nuova versione; ferma in modo esplicito il lavoro attivo prima di un riavvio del runtime. I file Homebrew restano gestiti da Homebrew.

Per il rollback, usa un installer verificato con --version <previous-version>. Il file version in ogni generazione conservata ne identifica il rilascio. Le generazioni vecchie non vengono potate in automatico; dopo aver fermato tutti i processi che le usano, puoi rimuovere le generazioni inutilizzate. Durante la disinstallazione, conserva sessioni e configurazione con --keep-data --keep-config se serve; segui la guida di rimozione del binario e rimuovi separatamente le generazioni di runtime inutilizzate solo dopo che i loro processi si sono fermati. Non cancellare l’intera cartella .ax-code se vi hai memorizzato altra configurazione o file personali.

Un’installazione Unix concorrente fallisce con la posizione della directory .install-lock. Un installer ucciso di colpo può lasciare quella directory vuota. Controlla che non ci siano installer attivi prima di rimuovere un lock stantio e di ritentare; non rimuoverlo mentre un’installazione è in corso.

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

Su Windows questo aggiorna la CLI. Per rimuovere l’installazione della CLI e la sua voce di PATH utente:

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

Comportamento del launcher di chi contribuisce

Questa sezione richiede un checkout dei sorgenti autorizzato. Non serve per l’installazione o gli aggiornamenti pubblici; vedi Accesso ai sorgenti.

pnpm run setup:cli è di proposito, per impostazione predefinita, un percorso compilato. Compila o riusa il binario incluso locale sotto packages/ax-code/dist/... e installa un launcher globale che punta a quel binario. Questo tiene i controlli del runtime impacchettato locale vicini a ciò che eseguono gli utenti di Homebrew e dell’installer curl.

Quel launcher di solito finisce in ~/.local/bin o PNPM_HOME, che di norma sta prima nel PATH rispetto a Homebrew. Se Homebrew fornisce già ax-code, setup:cli installa il checkout come ax-code-src e rimuove un involucro ax-code scritto in precedenza, così brew upgrade ax-code continua ad aggiornare il comando ax-code. Usa pnpm run setup:cli -- --override-homebrew solo quando vuoi di proposito che il checkout prenda il controllo di ax-code. ax-code doctor avvisa comunque di quella sostituzione come PATH launchers.

Dopo modifiche ai sorgenti che devono influire sul runtime impacchettato, aggiorna il binario incluso prima di provare il launcher globale:

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

Usa il launcher dai sorgenti solo quando vuoi di proposito che il comando del checkout esegua questo checkout tramite Node, dai file sorgente:

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

Il launcher dai sorgenti dovrebbe riportare Runtime: Node vX.Y.Z (source).

Requisiti della toolchain

Il repository impone pnpm@10.33.4 tramite il campo radice packageManager e only-allow pnpm: l’hook preinstall blocca le installazioni non pnpm, e gli hook radice pre<script> bloccano npm run <script> con lo stesso requisito. Node.js deve corrispondere al motore radice package.json (>=26), che fornisce anche --experimental-ffi per i comandi TUI in modalità sorgente.

Non usare pnpm test alla radice; lo script radice esce di proposito con do not run tests from root. Per packages/ax-code, esegui i test da packages/ax-code/.

Le installazioni Homebrew ricevono notifiche di aggiornamento senza aggiornamenti automatici in background. Termina le esecuzioni di agente attive prima di aggiornare in modo esplicito o di pulire i keg Homebrew vecchi.