Installation

Scrollcase is a Node.js command line tool. The CLI itself has no native dependencies; building a box for real additionally needs pixi and conda-pack on the machine that builds — and scrollcase init can install those for you, after asking.

Requirements at a glance

You want to…	You need
Run the CLI (init, keygen, audit, verify)	Node.js ≥ 20
Resolve a lock (lock) or build a box (build)	Node.js ≥ 20, pixi at the version the recipe pins, conda-pack 0.9.2 — installable by init
Verify with --self-test	The same OS and architecture the box targets

Locking, auditing, signing, and verifying an existing archive need no toolchain at all — only build and lock invoke pixi, and only build invokes conda-pack.

Install the CLI

npm install -g scrollcase

Check the install:

scrollcase help

Let Scrollcase install the toolchain

scrollcase init scaffolds a project and then offers to install what is missing:

This project needs pixi and conda-pack to build a box.
Install them into /work/my-project/.scrollcase/toolchain? [y/N]

Nothing is downloaded before you answer, and the default is no. Say yes and Scrollcase installs both inside the project, under .scrollcase/toolchain/ — nothing is added to PATH, nothing is installed system-wide, and deleting the directory undoes it. Later commands find the tools there on their own.

What you get is verified, not just fetched:

• the release archive's SHA-256 is checked against the checksum pixi publishes beside it, and a mismatch aborts before anything is installed;
• the verified digest is recorded under toolchain in scrollcase.config.json, so the next machine — a teammate's, a CI runner's — is checked against the value your project committed rather than whatever the server offers that day;
• if the recipe carries no pixiVersion yet, the version that was actually installed is written into it, so lock and build agree with the toolchain sitting next to them.

For unattended setups, answer up front:

scrollcase init --install-toolchain      # install without asking
scrollcase init --no-install-toolchain   # never install; just report what is missing

With no terminal to prompt — CI, a pipe — Scrollcase never installs anything and simply reports what is missing. Silence is not consent.

Pin the version you want

--pixi-version 0.73.0 installs exactly that release. Without it, the newest release is resolved once and then pinned into the recipe, so the choice is still recorded rather than floating.

Install the toolchain yourself

If you would rather manage the toolchain — a shared machine, a company mirror, an existing pixi install — Scrollcase is happy to use it. Install both tools and skip the step above.

pixi

pixi solves and installs the conda-forge environment. Every recipe pins the exact pixi version it was locked with (pixiVersion in recipe.json), and Scrollcase refuses to run lock or build with any other version — a different resolver can select different packages and silently change the box.

Install it following the pixi installation docs, for example:

curl -fsSL https://pixi.sh/install.sh | sh

If you need a specific release to match a recipe's pin, download the matching release from the pixi GitHub releases page, or use the version-pinned form of the install script documented by pixi.

conda-pack

conda-pack turns the installed environment into a relocatable tree. The recommended install is through pixi itself:

pixi global install "conda-pack==0.9.2"

Scrollcase's managed installer uses this exact release. conda-pack --version currently reports 0.0.0 regardless of the installed package release, so Scrollcase can pin what it installs but cannot reliably validate the version of an executable supplied through a flag, environment variable, or PATH.

Point Scrollcase at the toolchain

If pixi and conda-pack are on PATH, nothing more is needed. If they live elsewhere — a dedicated toolchain directory, a CI cache — point Scrollcase at them per invocation:

scrollcase build my-recipe --pixi /opt/toolchain/bin/pixi --conda-pack /opt/toolchain/bin/conda-pack

or once, through the environment:

export SCROLLCASE_PIXI=/opt/toolchain/bin/pixi
export SCROLLCASE_CONDA_PACK=/opt/toolchain/bin/conda-pack

A --pixi / --conda-pack flag wins over the environment variable, which wins over the project-local toolchain, which wins over PATH.

Check the machine

doctor reports whether this machine can build, and says exactly what to do about anything missing. It only reads; it never writes and never touches the network.

scrollcase doctor --pixi-version 0.73.0
# or take the required pixi version from a recipe:
scrollcase doctor --recipe my-recipe

Sample output:

ok    workspace   config /work/my-project/scrollcase.config.json
ok    recipes     /work/my-project/recipes
ok    git         HEAD 3f9c2ab17d42
ok    pixi        pixi at 0.73.0
ok    conda-pack  conda-pack

Every check reports rather than aborting at the first failure, so a machine missing both tools learns both in one run.

Builds are native

A box is always built on the OS and architecture it ships for: macOS arm64 boxes on an Apple Silicon Mac, Linux x86_64 boxes on Linux, Windows boxes on Windows. There is no cross-building — the self-test runs the box's own interpreter, which only proves anything on matching hardware.

Next

Continue with the Quickstart to scaffold a project and build your first box.