Skip to content

With Alloy Host

alloy-host is a helper tool for developer workstations. It manages the lifecycle of isolated build environments (VMs, WSL2, or Docker) so that alloy-provisioner can run inside them, without touching your host machine.

Use alloy-host when you want to:

  • Keep your host clean and switch between project environments easily.
  • Give teammates a one-command environment setup from a published blueprint on Alloy Hub.

Note

alloy-host is a helper tool. Any Linux VM or container you manage yourself can run alloy-provisioner natively. alloy-host is not required.

Local blueprint paths (--blueprint ./my-dir) are not supported yet; use a registry name and tag from alloy-provisioner clone --list community.

Install alloy-host

The bootstrap installer is in alloy-host-releases. It picks OS/architecture, verifies checksums, and installs the binary. Details: scripts/README.md.

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

Installs to /usr/local/bin (requires sudo). Pin a version (no v prefix):

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

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

Pin: …/install.sh | bash -s -- 2.1.0. Or …/install.sh | ALLOY_HOST_VERSION=2.1.0 bash (the variable must apply to bash, not curl).

Download install.ps1, then run:

powershell -ExecutionPolicy Bypass -File .\install.ps1

By default the script installs under %LOCALAPPDATA%\alloy-host and adds that directory to your user PATH.

Verify:

alloy-host --version
alloy-host check-health

check-health (release 2.1.0) checks Vagrant and VirtualBox only and exits 0 when those are found. It does not yet validate Docker or WSL2.

New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0

alloy-host check-health --backend vm|wsl2|docker|all reports OK / WARN / FAIL per backend and exits non-zero when a requested backend fails.

Choose a backend

Backend Flag Platforms Notes
VirtualBox + Vagrant --backend vm (default) Windows, macOS, Linux Requires VirtualBox and Vagrant
WSL2 --backend wsl2 Windows Requires WSL2 enabled
Docker --backend docker All with Docker No USB; project folder not mounted in guest

VirtualBox + Vagrant prerequisites (default backend):

  • macOS / Linux: VirtualBox and Vagrant
  • Windows: same, or use WSL2 instead
  • Apple Silicon: VirtualBox 7.1 or later

Quick start: Docker backend

Fastest path when you already have Docker and do not need USB or a mounted project tree:

alloy-host init nrf-docker --blueprint community/nordic/nrf91:1.1.3 --backend docker
cd nrf-docker
alloy-host up
alloy-host ssh
  • First up builds the image and runs provisioning; expect several minutes and large disk use for toolchain-heavy blueprints.
  • Your host project directory is not mounted inside the container; copy sources in or clone inside ssh.
  • USB passthrough is not supported on the docker backend; use vm or wsl2 for boards and debuggers.

New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0

up keeps the container running and reuses it when unchanged; ssh uses a login shell; destroy removes the container but keeps the image until destroy --all.

Create your first environment (VM or WSL2)

1. Initialize

alloy-host init arm-dev --blueprint community/nordic/nrf91:1.1.3

Creates an arm-dev/ directory in your current working directory (not under ~/.alloy-it/envs/). The environment does not start until up.

alloy-host init arm-dev --blueprint community/nordic/nrf91:1.1.3 --backend wsl2

2. Start and provision

cd arm-dev
alloy-host up

alloy-host starts the backend, installs alloy-provisioner in the guest, and runs the blueprint. Output is backend-specific (Vagrant logs, provisioner task lines, provisioning report). The first run downloads toolchains.

On docker, alloy-host passes --docker to the provisioner so exclude: [docker] tasks are skipped. On wsl2 today, only ALLOY_BACKEND is set in the bootstrap; use blueprint tasks compatible with WSL or provision natively inside the distro if udev-style steps fail.

New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0

WSL2 bootstrap will pass --wsl2 to the provisioner automatically.

3. Enter the environment

alloy-host ssh
Backend What you get (2.1.0)
vm SSH shell; host folder synced to guest (Vagrant default, often /vagrant)
wsl2 Shell in the distro; paths depend on export layout
docker Shell in the container; non-login shell unless you start bash -l; no project mount

Verify the toolchain (use a login shell on docker if PATH looks empty):

bash -l -c 'arm-none-eabi-gcc --version'

4. Stop when done

alloy-host stop

This stops the environment (vagrant halt, wsl --terminate, docker stop). Data layout is backend-specific; docker up may rebuild the image on a later run.

Running up again

Backend Behaviour (2.1.0)
vm Boots an existing VM if halted; does not re-run full provision unless you run provision
wsl2 Re-runs bootstrap provisioning on each up
docker Rebuilds image / creates a new container on each up

Daily workflow

alloy-host up
alloy-host ssh
# ... work inside the environment ...
alloy-host stop

When inside the environment directory you can omit the name:

alloy-host ssh arm-dev

Updating the environment

alloy-host provision

Re-runs the blueprint frozen at init time (name:tag from .alloy-blueprint). On docker this is effectively a cached image rebuild, not an incremental patch inside a running container.

To move to a new blueprint version, change the tag in .alloy-blueprint (or re-init) and run provision or up as appropriate for your backend.

Managing multiple environments

alloy-host list

Shows registered environments with status and blueprint. Since Alloy Host 2.2.0, docker environments show their real status (running / stopped).

Destroying and rebuilding

alloy-host destroy

Removes the running instance (VM, WSL export session, or docker container) depending on backend. Host project files in your init directory are not deleted.

Backend destroy (2.1.0) destroy --all
vm Destroys the Vagrant machine Same as plain destroy (no separate data disk)
wsl2 Terminates/removes guest instance Does not remove the WSL export tarball by itself
docker Removes the container and the registry entry; keeps the image (often many GB) Also removes the image

New in Alloy Host 2.2.0 / alloy-provisioner 1.5.0

destroy keeps the docker image and registry entry; destroy --all removes container, image, and registry entry. WSL2 destroy keeps the export; up re-imports it.

alloy-host up

USB and hardware

USB passthrough works on vm (and WSL2 with usbipd on Windows). Docker does not support USB through alloy-host. See USB & Target Boards.

Quick reference

Command What it does
alloy-host init <name> --blueprint <name:tag> Create environment directory in cwd
alloy-host up [name] Start backend and provision
alloy-host ssh [name] Shell inside the environment
alloy-host provision [name] Re-run blueprint at frozen tag
alloy-host stop [name] Stop the environment
alloy-host destroy [name] Tear down instance
alloy-host destroy [name] --all Stronger cleanup where supported
alloy-host list Registered environments
alloy-host validate [path] Validate blueprint YAML
alloy-host check-health Host dependency check (VM tools today)

alloy-host resolve exists but fails in a plain authoring folder (no VMs found in registry); generating alloy.lock.yml for catalog refs is documented in Catalog with limitations until a public resolve workflow ships.

Full details: Command Reference

Next steps