Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Canais de instalação e de runtime

Status: Ativo Escopo: estado atual Última revisão: 2026-10-09 Responsável: ax-code runtime

O README da raiz guarda o caminho principal de instalação. Esta página é a fonte da verdade para os canais com suporte do instalador da CLI, os rótulos de runtime ax-code doctor, o comportamento do lançador local e o comportamento público de atualização.

Disponibilidade pública

Instaladores públicos de versão e arquivos assinados de runtime são distribuídos por download.ax-code.com. A instalação não exige credenciais privadas do GitHub.

O AX Code e o SDK aceitam somente Node.js 26 ou posterior. Os instaladores independentes empacotam um runtime Node verificado. Checkouts do código-fonte e aplicativos de SDK baseados em Node precisam fornecer Node.js 26 ou posterior; a instalação de pacote rejeita versões mais antigas do Node.

O AX Code Standard continua gratuito para uso pessoal e comercial, sob a licença já existente. O acesso ao código-fonte de desenvolvimento é administrado à parte da distribuição pública. Os componentes proprietários planejados do Business têm licenciamento separado; isso não muda a licença do Standard. Veja Standard e Business para os detalhes e o guia do site para atualizações públicas de instalação. Os instaladores públicos e os ativos assinados deles precisam estar alcançáveis e verificados antes de o site anunciar um comando de instalação de uma linha.

Disponibilidade da versão

Enviar uma tag git vMAJOR.MINOR.PATCH inicia o fluxo de Release. O índice público de versões só mostra uma versão depois que esse fluxo assinou os ativos e publicou. Até lá, Latest permanece na tag publicada anterior. Depois que a validação passa, quem mantém pode ver um rascunho da tag nova; ele não é o Latest público.

Para instalações já existentes, siga Atualização e recuperação.

Caminho recomendado

Use um instalador empacotado com suporte, a menos que esteja desenvolvendo a partir de um checkout. O instalador de versão é o caminho principal da CLI no macOS e no Linux; use o instalador nativo em PowerShell no 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

O Homebrew continua sendo uma alternativa com suporte para a CLI no macOS:

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

O Homebrew exige confiança explícita para taps que não são oficiais. Essa confiança do tap inteiro cobre todas as fórmulas atuais e futuras, casks e comandos externos publicados em defai-digital/tap. O tap compartilhado contém tanto a fórmula da CLI quanto o cask do Desktop, e o Homebrew pode carregar as duas definições ao resolver uma instalação. Use o instalador de versão se a confiança do tap inteiro não for aceitável.

Mover uma instalação existente do tap legado

defai-digital/ax-code agora é um tap só de migração. As versões do AX Code atualizam apenas defai-digital/tap. Se você instalou a partir do tap legado, acrescente o tap compartilhado antes de atualizar, para que o Homebrew possa mover a posse do tap do pacote instalado:

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

Depois de confirmar que a instalação usa o tap compartilhado, remova o tap legado:

brew untap defai-digital/ax-code

Se o Homebrew ainda informar o tap antigo, execute brew reinstall defai-digital/tap/ax-code antes de soltá-lo. O repositório legado permanece acessível para instalações existentes descobrirem a migração.

Verificar um instalador Unix fixado por versão

Para uma instalação Unix inspecionada e fixada por versão, baixe primeiro o instalador e a assinatura dele da mesma versão. Com um minisign confiável já disponível:

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

A assinatura do arquivo não autentica o script de arranque antes da execução. Um resumo baixado da mesma origem detecta corrupção, mas não é uma checagem independente da identidade do publicador. O caminho de uma linha depende do endpoint de distribuição HTTPS.

A execução remota de uma linha é um caminho de conveniência. O instalador do Windows verifica o ZIP baixado da CLI com Minisign depois de iniciar, mas irm | iex não verifica install.ps1 antes da execução.

Se minisign ainda não estiver no PATH, o instalador PowerShell baixa o arquivo fixado do Minisign 0.12 a partir de download.ax-code.com, confere o SHA-256 e confere de novo o executável extraído antes de guardá-lo em cache. Você não precisa instalar o Minisign à mão no caminho padrão de instalação. Um binário minisign que já esteja no PATH é usado como está.

Para ambientes sensíveis à segurança, baixe o instalador, verifique-o com Minisign, inspecione-o e fixe a versão usada pela 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

Defina AX_CODE_SKIP_MINISIGN_VERIFY=1 somente quando você aceitar de propósito um download de versão que não se pode verificar.

Verifique o runtime instalado:

ax-code doctor

Instalações de usuário com suporte devem informar Runtime: Node vX.Y.Z (node-bundled) no macOS, no Windows e no Linux (glibc).

Estes instaladores distribuem o runtime da CLI e da TUI. A posse da versão do Desktop está no AX Coder, e versões novas do Desktop estão congeladas no momento. Este guia não oferece um canal de instalação ou de atualização do Desktop.

Matriz de canais

node-bundled e source são modos de runtime, não nomes de gerenciador de pacotes. Eles descrevem qual executável carrega o código do aplicativo:

• node-bundled: o Node.js carrega o runtime empacotado da versão (todos os canais de instalação de usuário com suporte).
• source: o Node carrega arquivos direto de um checkout.

compiled e bun-bundled são modos aposentados da era Bun, conservados só para diagnóstico legado. Não são canais de instalação de usuário com suporte.

pnpm dev e pnpm cli compilam o SDK do workspace (packages/sdk/js) para dist com o TypeScript do repositório antes de iniciar, então um checkout novo executa sem uma compilação manual do SDK. O passo invoca typescript/bin/tsc por node de forma direta, então não depende de node_modules/.bin estar ligado. Os caminhos empacotados (pnpm run setup:cli e pnpm --dir packages/ax-code run build) ainda precisam de pnpm --dir packages/sdk/js run build primeiro.

Política de plataforma

• macOS: use o instalador bash de versão como o caminho principal documentado da CLI. Ele instala em ~/.ax-code, prepara o Minisign fixado quando necessário, verifica o arquivo da versão e não exige Homebrew. O arquivo darwin-arm64 inclui um sidecar autossuficiente do AX Engine para inferência local. Compilações de quem contribui usam pnpm run setup:cli.
• O caminho Homebrew com suporte faz tap e confia de forma explícita em defai-digital/tap antes de usar comandos de instalação totalmente qualificados. A confiança do tap inteiro inclui todas as fórmulas, casks e comandos externos atuais e futuros do tap compartilhado; use o instalador bash de versão quando esse escopo de confiança não for aceitável.
• CLI no Linux: use o instalador bash para Ubuntu Desktop e Server 24.04 LTS e mais novos, em amd64 e arm64 (glibc). As compilações de versão produzem ax-code-linux-x64.tar.gz e ax-code-linux-arm64.tar.gz em executores Ubuntu 24.04, para que a linha de base glibc continue compatível com 24.04 ou posterior. Musl (Alpine) não tem suporte nos arquivos atuais de versão.
• Arquivos da CLI no macOS: as compilações de versão publicam só darwin-arm64 (Apple Silicon). macOS Intel não é um alvo de instalação com suporte para os pacotes atuais de CLI e Desktop.
• CLI no Windows: use o instalador nativo em PowerShell. Ele instala o ativo de versão do GitHub num diretório local do usuário e atualiza o PATH do usuário, a menos que -NoModifyPath seja informado. Ele verifica o ZIP baixado com a chave pública fixada antes da extração e falha fechado, a menos que AX_CODE_SKIP_MINISIGN_VERIFY=1 seja definido de propósito. Se minisign estiver ausente, o instalador baixa o arquivo fixado do Minisign 0.12 a partir de download.ax-code.com para %LOCALAPPDATA%\ax-code\tools\minisign e confere o executável extraído antes de guardá-lo em cache. Um binário minisign que já esteja no PATH é usado como está. Use -Uninstall para remover a instalação local do usuário e a entrada do PATH.
• Desktop no Windows: use o instalador Electron assinado das GitHub Releases, nomeado AX-Code-<version>-win-x64.exe ou AX-Code-<version>-win-arm64.exe. O publicador Authenticode esperado é DEFAI Private Limited. Não descreva install.ps1 como um instalador do Desktop. Instalação silenciosa: .\AX-Code-<version>-win-x64.exe /S (NSIS).
• Winget: os manifestos de pacote são gerados com pnpm exec tsx tools/winget/generate-manifests.ts --version <ver> e enviados a microsoft/winget-pkgs (veja tools/winget/README.md). Até serem publicados na origem, as GitHub Releases continuam sendo a fonte da verdade da instalação no Windows.
• npm: não é um canal com suporte de instalação nem de atualização.

A execução remota de uma linha é um caminho de conveniência, não o único. Mantenha na documentação um fluxo de instalador inspecionável (e, no Windows, verificado com Minisign), use versões fixadas na CI e documente instaladores de plataforma só com cobertura da matriz de instalação que verifique ax-code --version e verifique que ax-code doctor informa o modo de runtime esperado daquela plataforma.

Instalações empresariais e sem supervisão

CLI do Windows (local do usuário, sem administrador)

# 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 (local do usuário / Homebrew / MDM)

Use o instalador de versão para uma instalação local da CLI, sem Homebrew:

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

Macs gerenciados podem usar a fórmula Homebrew, para que as atualizações da CLI acompanhem o tap:

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

Para instalações DMG empacotadas por MDM, use o AX-Code-*-mac-arm64.dmg notarizado das GitHub Releases e verifique o .minisig destacado quando a política exigir checagens de cadeia de suprimento.

Disponibilidade do Winget

Use o instalador público, a menos que um pacote comunitário verificado da CLI esteja disponível. Não suponha que pacotes de manifesto hospedados no GitHub sejam acessíveis de forma anônima.

Atualização

Escolha o canal que é dono da instalação ativa:

Quem ainda usa o tap legado deve seguir a migração para o tap compartilhado. Uma segunda instalação pode sombrear a primeira no PATH; use which -a ax-code, ax-code --version e ax-code doctor antes de trocar de canal. Instalar a versão independente não desinstala o Homebrew. Mude de canal só de propósito, e conserve os dados de sessão e de configuração.

Atualizações próprias no Unix buscam o instalador da versão alvo e exigem o arquivo auxiliar SHA-256. Um instalador ou resumo ausente interrompe a atualização; não há reserva de um main mutável. Para instalar um arquivo mais antigo de uma versão sem ativos de instalador, baixe e verifique um instalador atual já lançado, e depois execute-o com --version <older-version>.

Instalações Unix independentes usam ~/.ax-code/bin/ax-code como um link simbólico estável para uma geração única de runtime em ~/.ax-code/versions/. O instalador verifica a árvore nova completa antes de trocar esse link. Reinstalar uma versão cria uma geração nova. Ele conserva gerações antigas e arquivos legados de runtime, para que agentes já em execução possam continuar carregando os próprios módulos. Ele não reinicia agentes em execução. Inicie um cliente ou runtime novo para usar a versão nova; pare o trabalho ativo de forma explícita antes de reiniciar o runtime. Os arquivos do Homebrew continuam administrados pelo Homebrew.

Para reverter, use um instalador verificado com --version <previous-version>. O arquivo version em cada geração conservada identifica a versão dela. Gerações antigas não são podadas de forma automática; depois de parar todos os processos que as usam, você pode remover gerações sem uso. Durante a desinstalação, conserve sessões e configuração com --keep-data --keep-config se precisar; siga a orientação de remoção do binário e remova à parte as gerações sem uso de runtime só depois que os processos delas pararem. Não apague a pasta inteira .ax-code se você tiver guardado ali outra configuração ou arquivos pessoais.

Uma instalação Unix concorrente falha com o local do diretório .install-lock. Um instalador morto de forma abrupta pode deixar esse diretório vazio. Confira se há instaladores ativos antes de remover um bloqueio velho e tentar de novo; não o remova enquanto uma instalação estiver em curso.

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

No Windows, isto atualiza a CLI. Para remover a instalação da CLI e a entrada do PATH do usuário:

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

Comportamento do lançador de quem contribui

Esta seção exige um checkout autorizado do código-fonte. Não é necessária para instalação ou atualização públicas; veja Acesso ao código-fonte.

pnpm run setup:cli é, de propósito, um caminho compilado por padrão. Ele compila ou reutiliza o binário local empacotado em packages/ax-code/dist/... e instala um lançador global que aponta para esse binário. Isso mantém as checagens locais do runtime empacotado perto do que usuários do Homebrew e do instalador por curl executam.

Esse lançador em geral cai em ~/.local/bin ou PNPM_HOME, que costuma vir antes no PATH do que o Homebrew. Se o Homebrew já fornecer ax-code, setup:cli instala o checkout como ax-code-src e remove um invólucro ax-code escrito antes, para que brew upgrade ax-code continue atualizando o comando ax-code. Use pnpm run setup:cli -- --override-homebrew somente quando você quiser de propósito que o checkout assuma ax-code. ax-code doctor ainda avisa sobre essa substituição como PATH launchers.

Depois de alterações no código-fonte que devam afetar o runtime empacotado, atualize o binário empacotado antes de testar o lançador 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

Use o lançador de código-fonte somente quando quiser de propósito que o comando do checkout execute este checkout pelo Node, a partir dos arquivos de código:

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

O lançador de código-fonte deve informar Runtime: Node vX.Y.Z (source).

Requisitos da cadeia de ferramentas

O repositório impõe pnpm@10.33.4 pelo campo raiz packageManager e por only-allow pnpm: o hook preinstall bloqueia instalações que não sejam pnpm, e os hooks raiz pre<script> bloqueiam npm run <script> com o mesmo requisito. O Node.js precisa casar com o engine raiz package.json (>=26), que também fornece --experimental-ffi para comandos da TUI no modo de código-fonte.

Não use pnpm test na raiz; o script da raiz sai de propósito com do not run tests from root. Para packages/ax-code, execute os testes a partir de packages/ax-code/.

Instalações Homebrew recebem avisos de atualização sem atualizações automáticas em segundo plano. Termine as execuções ativas do agente antes de atualizar de forma explícita ou de limpar kegs antigos do Homebrew.