Installer environment variables

Goal: drive install.sh / install.ps1 without editing the script by setting environment variables before you run it.

PrerequisitesCopy Anchor Link

• A POSIX shell (bash) or PowerShell 5.1+. The PowerShell examples below run pwsh (PowerShell 7+). Under Windows PowerShell 5.1, run powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 instead.
• The variables are read once at the top of the installer, so set them in the same command (or export them first), then run the installer.

The installer variablesCopy Anchor Link

APOTHEM_SOURCE takes precedence over a clone: when set to a checkout that contains src/apothem, the installer uses it directly, never touches APOTHEM_REPO / APOTHEM_REF, and skips tag resolution and signature verification (nothing is fetched to verify).

When APOTHEM_HOME points at an existing directory that is not a git clone, the installer refuses to delete it: move it aside, point APOTHEM_HOME elsewhere, or pass --yes (-Yes on Windows) to authorize the replacement. A stale empty directory is replaced without the flag.

Trust modelCopy Anchor Link

With no APOTHEM_REF set, the installer resolves the latest signed release tag and verifies its signature with git verify-tag before materializing any configuration; an unsigned or tampered tag aborts the install. A signed tag whose maintainer public key is missing from the local keyring aborts with key-import guidance instead - import the key and check its fingerprint against the value published in SECURITY.md. Pin a known release with APOTHEM_REF=<tag>, taking the tag from the releases page; a pinned tag is verified the same way. Select the moving branch with APOTHEM_REF=main plus APOTHEM_ALLOW_UNVERIFIED=1; that install is unverified, and main alone aborts because a branch is not a signed tag. Set APOTHEM_ALLOW_UNVERIFIED=1 on its own to proceed past a verification failure with a warning (air-gapped, local, or pre-signed-release use).

APOTHEM_REF=vMAJOR.MINOR.PATCH bash install.sh

APOTHEM_VERIFY=checksum bash install.sh

APOTHEM_ALLOW_UNVERIFIED=1 bash install.sh

Steps (POSIX bash)Copy Anchor Link

1. Install a non-default user-scope harness:

   Copy Text

   APOTHEM_HARNESS=codex bash install.sh

2. Pin the install destination and select the moving main branch. A branch is not a signed tag, so the installer also needs APOTHEM_ALLOW_UNVERIFIED=1:

   Copy Text

   APOTHEM_REF=main APOTHEM_ALLOW_UNVERIFIED=1 APOTHEM_HOME=/opt/apothem bash install.sh

3. Use a local checkout and a custom profile, skipping verify:

   Copy Text

   APOTHEM_SOURCE=/work/apothem \
   APOTHEM_PROFILE=/work/profile.yaml \
   APOTHEM_SKIP_VERIFY=1 \
   bash install.sh

Steps (PowerShell)Copy Anchor Link

Set each variable on $env: before running the installer:

$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.ps1

VerifyCopy Anchor Link

The installer prints ✓ Harness <name> installed, then (unless APOTHEM_SKIP_VERIFY=1) ✓ verify passed. Confirm independently:

apothem verify --harness codex

For a project-scope harness such as Cursor, run the install and the verify yourself after the installer, with --project:

apothem install --harness cursor --project /path/to/project
apothem verify --harness cursor --project /path/to/project

When the profile did not yet exist, the installer creates one from the example and carries on to install and verify in the same run. The example's identity fields are placeholders, so the install prints a note; edit $APOTHEM_PROFILE, then run apothem update --harness <name> to apply your identity. A --dry-run with no profile previews with the example in place and writes nothing.

RelatedCopy Anchor Link

• Installing covers the one-shot network install.
• Add a harness covers adding harnesses through the CLI after the first install.