Variáveis de ambiente do instalador
Controle o instalador por script (destino, origem, harness, perfil, verificação) com variáveis de ambiente.
Objetivo: conduzir install.sh / install.ps1 sem editar o script, definindo
variáveis de ambiente antes de executá-lo.
Pré-requisitos
- Um shell POSIX (
bash) ou PowerShell 5.1+. Os exemplos de PowerShell abaixo executampwsh(PowerShell 7+). No Windows PowerShell 5.1, executepowershell -NoProfile -ExecutionPolicy Bypass -File install.ps1em vez disso. - As variáveis são lidas uma única vez no início do instalador, então defina-as no mesmo comando (ou exporte-as antes) e depois execute o instalador.
As variáveis do instalador
| Variável | Controla | Padrão |
|---|---|---|
APOTHEM_HOME | Destino de instalação da árvore de código-fonte clonada | $HOME/.apothem |
APOTHEM_REPO | Remoto do Git a clonar | https://github.com/ahmed-g-gad/apothem |
APOTHEM_REF | Ref do Git para fazer checkout; sem definir, resolve a tag vMAJOR.MINOR.PATCH assinada mais recente, um valor de tag a fixa, main seleciona a branch móvel. Uma ref que não seja tag, como main, aborta a operação, a menos que APOTHEM_ALLOW_UNVERIFIED=1 esteja definido. | não definida (tag assinada mais recente) |
APOTHEM_ALLOW_UNVERIFIED | Rebaixa uma falha na verificação da assinatura da tag, de um aborto fatal para um aviso, quando definida como 1 | 0 (verifica; na falha, bloqueia) |
APOTHEM_VERIFY | signature verifica a assinatura GPG da tag de lançamento; checksum instala o arquivo da plataforma do lançamento depois de conferir o SHA-256 dele com o SHA256SUMS do lançamento (integridade, não prova de quem o publicou) | signature |
APOTHEM_RELEASE_BASE | Base de download para o modo checksum | <APOTHEM_REPO>/releases/download |
APOTHEM_SOURCE | Árvore de código-fonte local explícita a usar em vez de clonar | não definida (clona) |
APOTHEM_HARNESS | Harness de escopo de usuário a instalar (antigravity, claude-code, codex, hermes, open-claw, opencode, qwen-code). O instalador não passa --project, então um harness de escopo de projeto falha com project.required; instale-os depois com apothem install --harness NAME --project PATH. | claude-code |
APOTHEM_PROFILE | Caminho para o YAML do perfil compartilhado | $HOME/.config/apothem/profile.yaml |
APOTHEM_SKIP_VERIFY | Pula a etapa de verificação pós-instalação quando definida como 1 | 0 (a verificação é executada) |
APOTHEM_AUTO_INSTALL_DEPS | Instala automaticamente, sem perguntar, os pré-requisitos click / rich ausentes quando definida como 1 | 0 (pergunta, ou recusa em um pipe não interativo) |
APOTHEM_BIN_DIR | Diretório do shim do comando apothem posicionado | $HOME/.local/bin (POSIX); %LOCALAPPDATA%\Microsoft\WindowsApps (Windows) |
NO_COLOR | Desativa a saída colorida quando definida com qualquer valor (no-color.org); a cor também fica desativada sempre que a saída não é um terminal (um pipe, um arquivo, um log de CI) | não definida (cor apenas em um terminal interativo) |
APOTHEM_SOURCE tem precedência sobre um clone: quando definida como um
checkout que contém src/apothem, o instalador o usa diretamente, nunca toca em
APOTHEM_REPO / APOTHEM_REF e pula a resolução da tag e a verificação da
assinatura (nada é baixado para verificar).
Quando APOTHEM_HOME aponta para um diretório existente que não é um clone
git, o instalador se recusa a excluí-lo: mova-o para outro lugar, aponte
APOTHEM_HOME para outro local ou passe --yes (-Yes no Windows) para
autorizar a substituição. Um diretório vazio obsoleto é substituído sem o
sinalizador.
Modelo de confiança
Sem APOTHEM_REF definida, o instalador resolve a tag de lançamento assinada
mais recente e verifica a assinatura dela com git verify-tag antes de
materializar qualquer configuração; uma tag não assinada ou adulterada aborta a
instalação. Uma tag assinada cuja chave pública do mantenedor está ausente do
chaveiro local, em vez disso, aborta com orientações para importar a chave —
importe a chave e confira a impressão digital dela com o valor publicado no
SECURITY.md.
Fixe um lançamento conhecido com APOTHEM_REF=<tag>, obtendo a tag na
página de lançamentos; uma
tag fixada é verificada da mesma forma. Selecione a branch móvel com
APOTHEM_REF=main junto com APOTHEM_ALLOW_UNVERIFIED=1; essa instalação não é
verificada, e main sozinha aborta porque uma branch não é uma tag assinada.
Defina APOTHEM_ALLOW_UNVERIFIED=1 sozinha para prosseguir após uma falha de
verificação com um aviso (uso air-gapped, local ou anterior aos lançamentos
assinados).
APOTHEM_REF=vMAJOR.MINOR.PATCH bash install.shAPOTHEM_VERIFY=checksum bash install.shAPOTHEM_ALLOW_UNVERIFIED=1 bash install.shEtapas (POSIX bash)
-
Instale um harness de escopo de usuário diferente do padrão:
APOTHEM_HARNESS=codex bash install.sh -
Fixe o destino da instalação e selecione a branch móvel
main. Uma branch não é uma tag assinada, então o instalador também precisa deAPOTHEM_ALLOW_UNVERIFIED=1:APOTHEM_REF=main APOTHEM_ALLOW_UNVERIFIED=1 APOTHEM_HOME=/opt/apothem bash install.sh -
Use um checkout local e um perfil personalizado, pulando a verificação:
APOTHEM_SOURCE=/work/apothem \ APOTHEM_PROFILE=/work/profile.yaml \ APOTHEM_SKIP_VERIFY=1 \ bash install.sh
Etapas (PowerShell)
Defina cada variável em $env: antes de executar o instalador:
$env:APOTHEM_HARNESS = 'codex'
pwsh -NoProfile -File install.ps1$env:APOTHEM_ALLOW_UNVERIFIED = '1'
$env:APOTHEM_REF = 'main'
$env:APOTHEM_HOME = 'C:\opt\apothem'
pwsh -NoProfile -File install.ps1$env:APOTHEM_SOURCE = 'C:\work\apothem'
$env:APOTHEM_PROFILE = 'C:\work\profile.yaml'
$env:APOTHEM_SKIP_VERIFY = '1'
pwsh -NoProfile -File install.ps1Verificar
O instalador imprime ✓ Harness <name> installed e depois (a menos que
APOTHEM_SKIP_VERIFY=1) ✓ verify passed. Confirme de forma independente:
apothem verify --harness codexPara um harness de escopo de projeto como o Cursor, execute você mesmo a instalação e a
verificação depois do instalador, com --project:
apothem install --harness cursor --project /path/to/project
apothem verify --harness cursor --project /path/to/projectQuando o perfil ainda não existia, o instalador cria um a partir do exemplo e
segue adiante para instalar e verificar na mesma execução. Os campos de
identidade do exemplo são marcadores de posição, então a instalação imprime um
aviso; edite $APOTHEM_PROFILE e depois execute
apothem update --harness <name> para aplicar a sua identidade. Um --dry-run
sem perfil pré-visualiza com o exemplo no lugar e não grava nada.
Relacionado
- Instalação cobre a instalação via rede em um único passo.
- Adicionar um harness cobre a adição de harnesses pela CLI após a primeira instalação.
Adicionar um harness
Habilite um adaptador de harness para que sua configuração nativa seja materializada a partir do perfil compartilhado.
Run the behavioural evals
Measure whether Apothem's commands and subagents fire on the right requests, whether each pipeline stage produces its artifact, and whether a rule changes behaviour, with a cost-capped eval run.