Pinned Node, npm, pnpm and Python versions

Published November 10, 2026 · by the AQ team

AQ cloud machines run the versions your repository pins, for each work item, with no sudo. A repository without pins gets the machine's own tools, exactly as before.

What AQ reads

• .node-version or .nvmrc: an exact version such as 24.16.0, or a major such as 22. Node comes from nodejs.org, checked against its published checksums.
• packageManager in package.json: [email protected] installs that npm; [email protected] or yarn@... runs through corepack when the machine has no pnpm or yarn of its own (an installed pnpm already follows the field).
• .python-version: an exact version such as 3.12.13, or 3.12. Python is installed with uv, and comes with pip and venv.

The nearest file to the directory a command runs in wins, up to the top of the checkout.

Where they apply

When a work item's dependencies are installed, AQ fills one directory for it, ~/.aq-runtime/toolchains/<work item>/bin, and puts it first on PATH for the setup command, the preview, services, terminals and commands you run from the composer. Each version is downloaded once per person and reused by every later work item. Agents are told where the directory is and use it for the commands they run.

A pin AQ cannot honor (offline, an end-of-life Node, a value that is not a version) leaves the machine's tool in place, with one line in the Log tab saying why.

On every machine

python3 -m venv and pip work for every Python 3 on the machine. A virtual environment you activate still comes first. Background: runners and infrastructure.