Skip to content

On Linux (Native)

Install alloy-provisioner directly on any Linux machine: a PC, laptop, or server, a test rack, a CI server, or any existing VM you already manage (VirtualBox, Proxmox, Vagrant, WSL2, etc.). No wrapper tool needed.

Install alloy-provisioner

Quick install (script)

On Linux (amd64 or arm64), run the install script. It detects your architecture and installs the binary to /usr/local/bin/.

curl -fsSL https://raw.githubusercontent.com/alloy-it/alloy-provisioner-releases/main/scripts/install.sh | bash

Requirements: curl or wget, sudo access. Then verify: alloy-provisioner -version.

Manual install (.deb)

Download and install the .deb package from alloy-provisioner-releases:

wget -q -O /tmp/alloy-provisioner.deb \
  https://github.com/alloy-it/alloy-provisioner-releases/releases/download/latest/alloy-provisioner_latest_linux_amd64.deb
sudo apt-get install -y /tmp/alloy-provisioner.deb
rm /tmp/alloy-provisioner.deb

wget -q -O /tmp/alloy-provisioner.deb \
      https://github.com/alloy-it/alloy-provisioner-releases/releases/download/latest/alloy-provisioner_latest_linux_arm64.deb
sudo apt-get install -y /tmp/alloy-provisioner.deb
rm /tmp/alloy-provisioner.deb

ARCH=$(dpkg --print-architecture)
wget -q -O /tmp/alloy-provisioner.deb \
      "https://github.com/alloy-it/alloy-provisioner-releases/releases/download/latest/alloy-provisioner_latest_linux_${ARCH}.deb"
sudo apt-get install -y /tmp/alloy-provisioner.deb
rm /tmp/alloy-provisioner.deb

Verify the installation:

alloy-provisioner -version

Option A: Install from Alloy Hub

Pull a blueprint from Alloy Hub and provision in one step:

sudo alloy-provisioner install community/arm-none-eabi

To install a specific version:

sudo alloy-provisioner install community/arm-none-eabi:1.2.0

The provisioner downloads the blueprint, then executes all tasks. It prints progress as it goes and records completed tasks so re-runs skip what is already done.

Option B: Provision from a local blueprint

If you have a blueprint directory (e.g. committed alongside your project):

sudo alloy-provisioner install --blueprint-dir /path/to/blueprint

Or set the directory via environment variable:

export ALLOY_BLUEPRINT_DIR=/path/to/blueprint
sudo -E alloy-provisioner install --blueprint-dir "$ALLOY_BLUEPRINT_DIR"

Environment variables and credentials

Blueprint tasks can use environment variables for credentials or environment-specific settings. Set them before running the provisioner using an env file:

# Create an env file (never commit this file)
cat > ~/.alloy-env << 'EOF'
GITLAB_TOKEN=glpat-xxxxx
SDK_DESTINATION=/opt/sdk
EOF
chmod 600 ~/.alloy-env

# Source and run
set -a && source ~/.alloy-env && set +a
sudo -E alloy-provisioner install --blueprint-dir /path/to/blueprint

Or use the -env-file flag directly:

sudo alloy-provisioner install --blueprint-dir /path/to/blueprint -env-file ~/.alloy-env

Never commit .env files

Env files contain credentials. Add them to .gitignore. Use CI/CD secret management for pipeline runners.

If the blueprint declares required_env: in manifest.yml, the provisioner validates all required variables are set before running and exits with a clear error if any are missing.

DEV_USERNAME is auto-detected

Blueprints that install SDKs or tools as a non-root user rely on a DEV_USERNAME variable. You do not need to set this manually. When you run sudo alloy-provisioner, the provisioner automatically detects the calling user from $SUDO_USER (or falls back to $USER) and uses it — no .env entry needed.

You only need to set DEV_USERNAME explicitly when provisioning for a different user than the one running sudo, or in CI environments where both SUDO_USER and USER resolve to root:

# .env
DEV_USERNAME=ci-build-user

Re-provisioning

Running the provisioner again is always safe. It uses three layers of idempotency:

  1. creates: guard: if the output path exists, the task is skipped immediately.
  2. State file: alloy.state.yml records a fingerprint of each completed task; tasks with unchanged inputs are skipped.
  3. Adapter-level checks: e.g. apt_install only installs packages that are not already present.

To force all tasks to re-run:

rm alloy.state.yml
sudo alloy-provisioner install --blueprint-dir /path/to/blueprint

Next steps