The development environment: archec env
archec env says which tools a project needs to be worked on, and why. It
reads them from the model: the project's kind, the code it generates, its
boards, its deployments and its handlers. archec env doctor looks each one up
on this computer and says how to install what is missing. archec env init
writes the files that install them: mise.toml with pinned versions, a
Makefile, and package lists for apt, Homebrew and winget.
archec env plan # what the project in this folder needs, and why
archec env doctor # which of them are here, and the fix for each one that is not
archec env init # mise.toml, Makefile, env/apt.txt, env/Brewfile, env/winget.json
mise install && make setup # then: make build, make test
Each command takes the project folder or its main file (archec env doctor my-shop, archec env plan my-shop/main.arche); the default is the current
folder. archec new --env mise,make,packages writes the same files in a new
project.
What a project needs#
archec env plan lists the tools in two groups. The first holds what you need
to build and test the project. The second holds optional tools: a flasher or a
debugger for the board, a step that CI leaves out.
Svc (kind service): main.arche
Needs:
go 1.27 kind service (go build, go vet, go test); target go (archec gen --target go)
node 24 archec (archec itself)
Optional:
arche-cli archec (archec test)
Each tool comes from one of these:
- The kind.
archec new --kindwrites the kind in.archec/kind.json. The kind's build and test steps name the programs they run, such asgo,cmake,colconorpodman. - The code. Each
archec gentarget needs its toolchain:makeand a C compiler forc, Rust forembassy,goforgo, Qt 6 forui-qml. A project without a kind gets its targets from its deployments: a binary'slanguage, a processor that runs Zephyr, an FPGA. - The boards. A microcontroller board adds its tools as optional ones:
arm-none-eabi-gccand OpenOCD for C on an STM32, nRF or RP2040 board;probe-rsfor Rust;esptoolfor an ESP32, andespupfor Rust on its Xtensa cores. The devcontainer then gets the USB devices. - The handlers. Python handlers need Python 3. TypeScript handlers in
.tsfiles addtypescripttopackage.json, fortsc. A step that imports a Python module, such as the robot kind's MuJoCo check, adds that module torequirements.txt. - archec itself needs Node.js.
archec testalso needsarche-cli, Arche's simulator.archec simneeds nothing.
The plan also holds the ports the project serves, the base image for a
devcontainer and the VS Code extensions to recommend. --json prints the
whole plan; the VS Code extension reads the same data.
The doctor#
archec env doctor runs each tool's version command and compares the version
with the pin:
Svc (kind service): darwin, mise on the PATH
✓ go 1.27.4 kind service (go build, go vet, go test); target go (archec gen --target go)
~ node 22.1.0, pinned 24 archec (archec itself)
mise install node@24
brew install node
– arche-cli (optional) missing archec (archec test)
✓ every tool the project needs is here; 1 at another version than its pin
A version matches its pin on the parts the pin gives, up to major.minor. So
1.27 matches 1.27.4, 24 matches 24.22.3, and 3.13 does not match 3.12.
A pin of stable, latest or system matches any version.
The fix comes first from mise, when mise is on the PATH and has the tool:
mise install go@1.27. Then comes the system's package manager: brew install on macOS, sudo apt install on Linux, winget install on Windows.
A tool no package manager has, such as the Zephyr SDK or ESP-IDF, gets a note
that says where to get it.
The doctor exits with 1 when a tool the project needs is missing. A version
other than the pin is shown with ~, but it does not fail: the tool runs, and
the pin may be the one that is out of date.
When archec new makes its first run and a tool is missing, the step is
skipped, and its note gives the same fix: no go on this computer (go missing: brew install go).
The files#
archec env init writes mise, make and packages; --with picks others.
archec env sync writes again the parts the project already has. Add
--dry-run to print the files without writing them, and --json to get them
as data.
| Part | Files | Written again |
|---|---|---|
mise |
mise.toml: [tools] with a pinned version per tool, [tasks] setup, gen, build, test, sim, ci, doctor |
Only what is missing is added. A version you changed and a task you wrote stay as they are. |
make |
Makefile: the same tasks as targets, make help |
Rewritten around your USER CODE regions, which are kept. A Makefile archec did not write is left alone, and the targets go to archec.mk for you to include. |
packages |
env/apt.txt, env/Brewfile, env/winget.json; requirements.txt and package.json when the handlers need packages |
The lists in env/ are written again each time. In requirements.txt and package.json, a missing package is added, and none is changed. |
devcontainer |
.devcontainer/devcontainer.json and its Dockerfile |
In builds that have it; others say devcontainer: not available in this build. |
mise.toml#
[tools]
go = "1.27" # kind service, target go
node = "24" # archec
# "cargo:probe-rs-tools" = "latest" # optional: board nucleo-f446re
[tasks.build]
description = "build the generated code"
run = "cd src/go/svc && go build -o ../../../generated/bin/svc ."
mise installs each tool at its version, for this
project only: mise install (the first time, mise trust lets mise read the
file). An optional tool is written commented out: remove the # to have it.
To pin a version, change it in mise.toml. archec env sync never changes a
version you wrote, and the plan and the doctor read your pin. A tool with no
mise package, such as Qt or a vendor SDK, is not in [tools]. Install it with
the package lists, or as the doctor says.
Makefile#
build: gen ## build the generated code
cd src/go/svc && go build -o ../../../generated/bin/svc .
# USER CODE BEGIN build
@echo your own step, kept
# USER CODE END build
Each target is followed by a region of its own. A line in the region is part
of the target's recipe, so it starts with a tab. The last region, targets,
holds targets of your own. make setup first runs mise install when there
is a mise.toml, then the commands the tools need after they are installed:
rustup target add for the board's Rust target, pip install -r requirements.txt, npm install.
The package lists#
env/apt.txt:sudo apt install -y $(grep -v "^#" env/apt.txt).env/Brewfile:brew bundle --file env/Brewfile.env/winget.json:winget import env/winget.json.
Optional tools are commented out in apt.txt and the Brewfile, and left out
of winget.json.
Dev container#
archec env init --with devcontainer (or archec new --env devcontainer) writes
two files; archec env sync writes them again when the project's needs change:
| file | what it is |
|---|---|
.devcontainer/devcontainer.json |
VS Code's "Reopen in Container", or devcontainer up: the image, the extensions, the forwarded ports, the user |
.devcontainer/Dockerfile |
the image: system packages, mise and the project's pinned tools, archec itself |
Open the project in VS Code, run Dev Containers: Reopen in Container: every
tool the project needs is there, at the versions mise.toml pins, and so is
archec. When the container is made, mise install && archec env doctor runs
(postCreateCommand), so a pin changed since the image was built is installed,
and anything still missing is said.
How each tool gets in the image#
One rule, in this order, so that no tool is installed twice:
- mise: a tool mise knows. The project's
mise.tomlis copied into the image as the user's global mise config andmise installruns: the same versions as on your computer, in any folder of the container. (Nomise.toml:mise use -g tool@versionfor each, at the version archec picked.) - apt: else a tool with Debian/Ubuntu packages: one
apt-get install --no-install-recommends, the package lists removed after. - devcontainer feature: else a tool with a good feature
(
ghcr.io/devcontainers/features/docker-outside-of-docker:1), infeatures. A tool the Dockerfile installs never also gets a feature.
A tool none of them installs (a vendor SDK) is named in a comment of the Dockerfile, with how to get it.
Then each tool's after-install commands (rustup target add …, pip install west), the kind's shell setup (. /opt/ros/jazzy/setup.sh, in
/etc/profile.d/archec-env.sh, read by every bash), and archec.
mise is its release binary, pinned (ARG MISE_VERSION) and checked against
its SHA-256 — not the install script, nor the apt repository (which gives
whatever is newest): the same bytes on every build. To move to another mise,
change MISE_VERSION and the two sums.
archec is the arche-lang CLI from https://arche-lang.xyz/downloads:
arche-lang-<version>.tgz, installed with npm install -g on a node from mise
(the project's, or node 22). The version is the one the project was made with
(archec in .archec/kind.json, else in generated/.archegen.json), in ARG ARCHEC_VERSION; empty means the latest. Only the latest release is served: when
the recorded one is gone, the latest is installed, with a warning in the build
log. The latest is checked against the SHA-256 in latest.json.
The user#
The container runs as vscode (uid 1000), not root, so that what you build in
the bind-mounted project belongs to you on a Linux host.
mcr.microsoft.com/devcontainers/base:bookworm(most kinds) has that user.ros:jazzy-ros-base(ROS 2) runs as root and has anubuntuuser with uid 1000: the Dockerfile renames itvscode(any other image without the user gets it made), with passwordlesssudo.
What is yours#
- Dockerfile: archec's, except two
# USER CODEregions it keeps on everyarchec env sync(regeneration):devcontainer.root(run as root, after the packages: more packages, udev rules) anddevcontainer.user(asvscode, at the end). - devcontainer.json (JSON with comments): archec writes again
name,build,features,forwardPorts,portsAttributes,postCreateCommand,remoteUser, and its own entries ofcontainerEnvandcustomizations.vscode.extensions. Every other key (runArgs,mounts, settings, more extensions or variables) is kept. Your comments are not: the file is read, then written again.
Boards over USB#
A project that flashes or reads a board gets the user in the dialout and
plugdev groups, and two runArgs lines in devcontainer.json, commented
out — archec never makes a container privileged on its own:
// "runArgs": ["--device=/dev/ttyACM0"]
// "runArgs": ["--privileged", "-v", "/dev/bus/usb:/dev/bus/usb"]
Uncomment one (prefer --device with your board's device). It works on a Linux
host only: Docker Desktop and Podman on macOS cannot pass USB to a container
(flash from the host there); on Windows, attach the board to WSL first with
usbipd (usbipd bind --busid <id>, then
usbipd attach --wsl --busid <id>).
CI in the same image#
With a dev container, the CI files archec new writes run the code job in its
image — the same tools, the same versions as yours:
- GitHub (
.github/workflows/archec.yml):devcontainers/ci@v0.3builds the image and runs, asvscode,archec genfor each target, then the kind's build and test commands (after its setup line, for ROS 2). The model's job is unchanged. - GitLab (
.gitlab-ci.yml):docker:27with thedocker:27-dindservice builds.devcontainer/Dockerfileand runs the same commands in it, as root (the runner's checkout belongs to root; mise's folders are fixed in the image, so root finds the same tools). The runner needs privileged mode for docker-in-docker.
Without a dev container the CI files are as before: each tool set up on the
runner (actions/setup-go, …), or the kind's own image (ROS 2).
Limits#
- The build context is the project folder: add a
.dockerignorethere whengenerated/or build outputs make it large. - mise tools that come from GitHub releases (
ubi:,aqua:) may meet GitHub's rate limit on a busy CI runner; give the build aGITHUB_TOKEN. - Language packages for your own code (
pip,npm,cargo, Go modules) are not installed in the image: your project's usual install step does that.
In VS Code#
The arche-lang extension shows the same plan and doctor, and writes the same files.
- The Environment view (in the Arche side bar): one row per tool. ✓ found,
✗ missing, ⚠ at another version than the pin; an optional tool is dimmed. The
description is the version found and the one pinned; the tooltip says why
the project needs it and how to install it. The title bar has Set Up…,
Run Doctor in Terminal (
archec env doctorin a terminal namedarche env) and Refresh. On a row, Install Tool… asks "Runbrew install goin a terminal?" and only then types the command in thearche envterminal; Copy Fix Command copies it. - The status bar:
env ✓when every tool the project needs is here,env: 2 missingotherwise. A click shows the view. - Arche: Set Up Development Environment… asks which parts to write
(
mise.toml,Makefile, dev container, package lists; the ones the project has are ticked), shows each file that would change in the diff editor, and writes them after a "Write N files" confirmation that lists the tools and their pins. When it wrote a dev container, it offers Reopen in Container (or shows the Dev Containers extension, when it is not installed: the extension never installs anything). A second run with nothing new writes nothing. - Once per project, when a tool it needs is missing: "This project needs go, cmake — not found. Set up the environment?" with Show Environment, Set Up… and Don't Ask Again for This Project.
The doctor runs its probes in the background, in parallel, each with a
time-out, once there is a project; the report is kept until you save
mise.toml, .archec/kind.json or a .arche file, close the arche env
terminal, or click Refresh. In a dev container the extension runs inside the
container, so the view and the status bar say what the container has: env ✓
when its Dockerfile installed everything. arche-cli counts as here when the
extension carries it (or arche.paths.appCli names one).
The catalogue#
The tools archec knows are in src/env/catalog.ts. Each one has a version
command, a default version and its names for mise, apt, Homebrew and winget.
It can also have a devcontainer feature, commands to run after the install,
and a note for a vendor SDK. Each word a kind's steps name is in it.
| Area | Tools |
|---|---|
| archec, handlers | node, python3, uv, arche-cli |
| C, C++ | make, cc, cmake, ctest, ninja, qmake6 (Qt 6), lcov, gcovr |
| Go, Rust | go, rustup, cargo, probe-rs, espup |
| Microcontrollers | arm-none-eabi-gcc, openocd, esptool, west, zephyr-sdk, esp-idf, platformio, renode |
| FPGA | ghdl |
| Containers | podman, docker-compose, kubectl |
| ROS 2 | ros2, colcon, gazebo |
| Others | protoc, bash, git |
A tool a step names that the catalogue does not have is still listed, with a note: install it as its own project says.
Windows#
On Windows, the doctor's fixes are winget install --id … -e, and
env/winget.json installs the whole list. Some toolchains do not run natively
on Windows: a C compiler named cc, make in the shell, ROS 2. For these,
there are two ways:
- WSL. Install Ubuntu with
wsl --install, open the project from there, and use the Linux commands (env/apt.txt). - Dev Containers. VS Code's Dev Containers extension runs the project's
.devcontainer/in Docker Desktop or Podman, through WSL 2. The tools are then the container's, the same as on Linux and macOS.
mise runs on Windows too. It installs Go, Node.js, Python, CMake and the other tools it has.
Limits#
- archec does not install anything itself. It says what to run and writes the files that run it.
- The doctor checks each program and its version. It does not check a Rust
target, a Python module, or that a daemon (podman, Docker) is running; the
first run of
archec newandmake testfind those. - Vendor SDKs (the Zephyr SDK, ESP-IDF, Espressif's Rust, Renode) have no package and no pin: their notes say where to get them.
- The package names were checked for Debian bookworm, Ubuntu 24.04, Homebrew and mise. Some tools are only in another apt repository: ROS 2, Kubernetes, and Docker's own Compose. kubectl has no Debian package: mise or the Kubernetes repository installs it.
- A task archec added to
mise.tomlis not changed when the model changes, because it may be yours now. Delete it, andarchec env syncwrites it again.