Skip to content

Get started: build environments

alloy-provisioner is the engine that installs build environments from blueprints. It runs inside any Linux system.

This is the reproduce leg of the loop: the same blueprint that gives your team a consistent toolchain today is what lets you reconstruct the build environment for an affected release years from now. If your job right now is CRA readiness rather than toolchains, start with CRA operations instead.

Choose the path that matches your situation:

  • On Linux (Native)

    You have a Linux machine (PC, laptop, or server, test rack, an existing VM managed by your own tools like Vagrant, VirtualBox, or Proxmox, or a WSL2 distro). Install alloy-provisioner and run blueprints directly.

    Best for: CI servers, test racks, shared build machines, manually provisioning your own VMs.

    Install natively →

  • In a Docker Image

    You want to replace a complex, hard-to-maintain Dockerfile with a declarative blueprint. alloy-provisioner runs inside the Docker build and produces a reproducible image using the same definition used by developers and CI.

    Best for: CI base images, replacing multi-stage Dockerfiles and chains of dependent images.

    Build Docker images →

  • CI/CD Pipelines

    You run GitHub Actions, GitLab CI, Jenkins, or another pipeline and want every job to use the same blueprint-defined environment. alloy-provisioner runs in the runner and provisions the toolchain so builds are identical to local and other CI.

    Best for: GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, reproducible build jobs.

    Set up CI/CD →

  • With Alloy Host

    You are on a developer workstation (Windows, macOS, or Linux) and want isolated environments that don't touch your host machine. alloy-host manages VM and Docker lifecycles for you.

    Best for: local development, quickly testing a blueprint before publishing, switching between project environments.

    Use alloy-host →

Which path should I choose?

Situation Recommended path
CI server or test rack (Linux PC/laptop/server) Native
Existing VM I manage myself Native: run alloy-provisioner inside the VM
Docker CI image or base image Docker
GitHub Actions, GitLab CI, Jenkins, etc. CI/CD
Developer workstation (want isolation) alloy-host
Testing a blueprint before publishing alloy-host
Multiple devs, same environment Any path, all using the same blueprint

New to blueprints?

If you need to create or customize a blueprint for your project, start by cloning an existing one from Alloy Hub rather than writing from scratch. Browse the hub for a blueprint that matches your board or toolchain, clone it locally, and adjust it to fit your needs.

# List available community blueprints
alloy-provisioner clone --list community

# Clone a blueprint to a local directory
alloy-provisioner clone community/nordic/nrf91:1.1.3 --output ./my-blueprint

Clone and customize a blueprint →

Before you start

All paths require a Linux environment with:

  • curl and wget: for downloading alloy-provisioner and toolchains
  • apt: alloy-provisioner targets Debian/Ubuntu-based systems
  • sudo or root access: provisioner tasks install system packages and tools

If you are using alloy-host or Docker, these requirements apply to the guest (the VM or container), not your host machine.

For a full list of provisioner subcommands and flags, see Provisioner CLI.