Quickstart

Use pixi-sandbox in two commands

Connected project root:

Connected hosts need Pixi installed. Install the CLI from its canonical package channel and initialise the project:

pixi global install --channel https://prefix.dev/archont561/archont561 --channel conda-forge pixi-sandbox
pixi-sandbox init

After committing the generated files, letting GitHub publish the sandbox branch, and transferring that branch into the airlock:

./restore.sh

The connected-side commands install the native channel package and scaffold configuration, CI, and both restore launchers. The second performs a local git archive and restores without network access.

Develop pixi-sandbox itself

Clone and test

git clone https://github.com/Archont561/pixi-sandbox && cd pixi-sandbox
# Includes the fixture-backed doctor → publish → network-isolated restore lifecycle.
pixi run test
pixi run lint

In your project

Pack

# 1. Inspect helper-tool pins
pixi-sandbox tools list
# Optional org mirror:
# pixi-sandbox tools list --tools-lock /path/to/reviewed-tools.lock.json

# 2. Pack envs + vendored crates + tools
cargo build -p pixi-sandbox --release
pixi-sandbox pack \
  --repo-root . --envs "dev,docs" \
  --output-dir .sandbox-transport \
  --fetch-tools --cargo-vendor \
  --self-bin target/release/pixi-sandbox

# Or use verified release binary:
# pixi-sandbox pack ... --self-bin pixi-sandbox-x86_64-unknown-linux-musl

Verify

# 3. Verify (CI gate, writes nothing)
pixi-sandbox doctor --branch-location .sandbox-transport --verify

Publish

# 4. Publish as orphan branch
pixi-sandbox publish --input-dir .sandbox-transport --branch-name sandbox/dev-linux-64

On the airlock

The normal project branch contains the launchers generated on the connected host. Once a clone or Git bundle containing the sandbox branch crosses the air gap, restoration is one local command:

.\\restore.ps1

cd /path/to/project
./restore.sh

The launcher archives the local platform branch and invokes its manifest-verified binary under .pixi-sandbox/tools/<platform>/. The orphan branch itself has only Markdown at its root.

From CI: generated native workflow

pixi-sandbox init writes .github/workflows/publish-sandbox.yml. Commit that project-owned file; it installs the canonical channel package and invokes the CLI directly for each reviewed bundle × platform matrix entry. The retired composite Actions and reusable publisher are not used.

Shipping the tool (.conda)

pixi publish --path crates/pixi-sandbox --build-dir .pixi/bld --target-dir dist
pixi publish --path crates/pixi-sandbox --build-dir .pixi/bld --target-channel file:///srv/channel
pixi global install -c file:///srv/channel -c conda-forge pixi-sandbox
pixi sandbox doctor --branch-location .sandbox-transport

Measured: 34s to build 594 KB package (1.26 MiB stripped binary), channel write produces repodata.json + .zst + sharded repodata — plain static host (Pages, S3) works as channel. Must combine with -c conda-forge.

Sizes to expect

Measured small project (2 envs, 33 crates, linux-64):

Part	Payload
conda envs (.conda channel)	133 MB
cargo vendor tree (loose)	33 MB
bundled tools (pixi, pixi-unpack, self)	96 MB
transport dir	262 MB
orphan branch after git dedup	~110 MB

Tools dominate small bundles — expected, git stores each tool blob once.