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.

Prerequisites¶

On a fresh Ubuntu or Debian system, install packages the provisioner and its .deb dependencies need:

sudo apt-get update
sudo apt-get install -y ca-certificates curl rsync git

Package	Why
`ca-certificates`	HTTPS downloads (registry, toolchains)
`curl` or `wget`	Install script and blueprint downloads
`rsync`	Required by the `alloy-provisioner` package; install it before the `.deb` if you use `dpkg -i`
`git`	`alloy-provisioner catalog update` clones the toolchain catalog
`sudo`	Most provisioning tasks need root

The install script only needs curl or wget beforehand; it runs apt-get install on the downloaded .deb so dependencies are resolved automatically.

Install alloy-provisioner¶

Quick install (script)¶

On Linux (amd64 or arm64), run the install script. It detects your architecture, verifies checksums.txt, and installs the binary (typically under /usr/local/bin/ via the .deb).

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

Pin a specific release (use the version without v):

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

Or set the version before bash (not on the same line as curl, or the variable applies to curl only):

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

Verify:

alloy-provisioner --version

Manual install (.deb)¶

Download and install the .deb from alloy-provisioner-releases. Prefer apt-get install ./file.deb so apt pulls dependencies; avoid bare dpkg -i without rsync already installed.

amd64

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

arm64

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

Pin version (example 1.4.0)

Release assets use a v prefix in the download path:

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

alloy-provisioner --version

Before you run¶

Useful commands before a full install:

# List published community blueprints and tags
alloy-provisioner clone --list community

# Pre-flight URL checks on a local blueprint (no tasks run)
alloy-provisioner check --blueprint-dir /path/to/blueprint

# See what would run without changing the system (pulls blueprint; may write under ~/.alloy-it)
sudo alloy-provisioner install --dry-run community/nordic/nrf91:1.1.3

# Check for a newer provisioner release
alloy-provisioner update-check

Set a custom registry host with ALLOY_URL, ALLOY_REGISTRY_URL, or ALLOY_REGISTRY (default api.alloy-it.io). For private registries use ALLOY_REGISTRY_USERNAME and ALLOY_REGISTRY_PASSWORD.

Optional global flags: --preflight (URL reachability before provisioning), --env-file, --docker, --wsl2. See Provisioner CLI.

Install from Alloy Hub¶

Blueprint names must include a published tag (there is no working latest on the registry today). List tags with clone --list.

alloy-provisioner clone --list community

Example: Nordic nRF91 (large download; first install can take a long time and several GB of disk):

sudo alloy-provisioner install --dry-run community/nordic/nrf91:1.1.3
sudo alloy-provisioner install community/nordic/nrf91:1.1.3

Smaller smoke-test blueprint:

sudo alloy-provisioner install community/raspberry-pi/raspberry-pi-1-model-b:1.0.0

New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0

Untagged names such as community/nordic/nrf91 will resolve to the highest published semver. install will write /etc/alloy/env and print source /etc/alloy/env for non-login shells.

Use your environment¶

With release 1.4.0, blueprints activate the toolchain via scripts under /etc/profile.d/. They are loaded in a new login shell, not in an existing non-login session (typical CI run: steps).

# Open a login shell, then verify
bash -l
arm-none-eabi-gcc --version

In CI, use a login shell for build steps:

- name: Build
  shell: bash -l {0}
  run: arm-none-eabi-gcc --version && make build

New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0

After install, the provisioner writes /etc/alloy/env. In CI or scripts, run source /etc/alloy/env instead of relying on /etc/profile.d alone.

In a container or WSL2¶

Inside Docker (or another container), tasks that call udevadm fail unless the docker environment tag is active. Pass --docker on 1.4.0:

sudo alloy-provisioner install --docker community/nordic/nrf91:1.1.3

On WSL2, use --wsl2 similarly.

New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0

The provisioner detects Docker (/.dockerenv, /run/.containerenv) and WSL automatically and enables the matching tag. You can still pass --docker or --wsl2, or override with --docker=false.

Option: 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"

Avoid sudo -E with a user home blueprint

Running sudo -E can leave files under ~/.alloy-it owned by root. A later clone as your user may hit permission errors. Prefer --blueprint-dir pointing at a root-owned path (e.g. under /opt) or run registry installs without -E when possible.

Environment variables and credentials¶

Blueprint tasks can use environment variables for credentials or environment-specific settings:

cat > ~/.alloy-env << 'EOF'
GITLAB_TOKEN=glpat-xxxxx
SDK_DESTINATION=/opt/sdk
EOF
chmod 600 ~/.alloy-env

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

Or use --env-file:

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.

DEV_USERNAME is auto-detected¶

When you run sudo alloy-provisioner, the provisioner detects the calling user from $SUDO_USER (or $USER) for run_as: tasks. Set DEV_USERNAME explicitly in CI when both resolve to root.

Re-provisioning¶

Running install again is usually safe, but idempotency is layered:

State file (alloy.state.yml): tasks recorded as completed with the same inputs are skipped first.
creates: guard: if the output path exists, the task is skipped even after you delete alloy.state.yml.
Adapters: e.g. apt_install skips packages already installed.

To re-run as much as possible, remove the state file; tasks guarded only by creates: still skip until outputs are removed:

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

Removing¶

There is no uninstall command yet. A typical install may leave:

Toolchains and SDKs under /opt/ (and paths defined in the blueprint)
Environment snippets in /etc/profile.d/ (and udev rules under /etc/udev/rules.d/ if the blueprint added them)
Packages installed via apt_install
Downloaded blueprint data under ~/.alloy-it/ (and alloy.state.yml in the blueprint directory)

Remove those manually if you need a clean machine. Re-installing the .deb or re-running install does not roll back prior changes.

On Linux (Native)¶

Prerequisites¶

Install alloy-provisioner¶

Quick install (script)¶

Manual install (.deb)¶

Before you run¶

Install from Alloy Hub¶

Use your environment¶

In a container or WSL2¶

Option: Provision from a local blueprint¶

Environment variables and credentials¶

DEV_USERNAME is auto-detected¶

Re-provisioning¶

Removing¶

Next steps¶