conda-ship 0.1.0

Conda plugin entry point for the conda-ship runtime builder.

conda-ship

Build ready-to-run conda runtimes from solved conda environments.

conda-ship is a generic builder for single-binary conda runtimes. It provides the cs builder CLI, the cs-template generic runtime template, a composite GitHub Action, and an optional Python adapter that exposes conda ship inside conda.

The project is currently alpha and pre-1.0. The split from conda-express is now explicit: conda-ship owns the reusable build/runtime machinery, while downstream distributions own their package sets, runtime names, release channels, installer wrappers, and user documentation. conda-express is one downstream distribution maintained by Jannis Leidel; it uses conda-ship to publish the cx and cxz runtimes.

What It Builds

conda-ship stages a runtime binary plus release metadata:

• .runtime.lock: the lockfile stamped into the runtime
• .packages.txt: tab-separated package records for quick inspection
• .info.json: artifact metadata for release tooling
• .sha256: checksums for staged files
• optional .bundle.tar.zst: compressed package archives for offline builds

The runtime itself has a small management surface: bootstrap, status, shell, and uninstall. Other commands pass through to the configured delegate executable after bootstrap, usually conda.

Artifact Layouts

Layout	Output	Bootstrap behavior
online	<runtime>	Downloads packages from the stamped runtime lock.
external	<runtime> plus <runtime>.bundle.tar.zst	Uses a separate package bundle for offline-capable installs.
embedded	<runtime>z	Embeds the compressed package bundle in one binary.

Project Input

conda-ship builds from an already solved source environment. It does not solve loose matchspecs in the GitHub Action and it does not define a package set of its own.

Supported manifest and lockfile pairs:

• conda.toml plus conda.lock
• pyproject.toml with [tool.conda] plus conda.lock
• pixi.toml plus pixi.lock
• pyproject.toml with [tool.pixi] plus pixi.lock

The package and channel intent lives in the selected source environment. [tool.conda-ship] only records conda-ship build policy:

[tool.conda-ship]
runtime = "demo"
delegate = "conda"
layout = "online"
source-environment = "ship"
exclude = ["conda-libmamba-solver"]

The selected source environment must include the runtime contract packages: conda, conda-rattler-solver, and conda-spawn.

Local Workflow

Packaged builds find cs-template next to the installed cs executable. Use --template only for an explicit template path, custom packaging, or cross-builds.

cs inspect
cs build --dry-run
cs build
cs build --layout embedded
cs run -- --path /tmp/demo-smoke bootstrap

cs inspect is the preflight command. It derives the runtime lock, validates the selected source environment, applies package exclusions, and prints the package set without writing artifacts.

GitHub Actions

The repository root is also a composite GitHub Action for downstream release jobs:

- uses: jezdez/conda-ship@0.1.0
  id: cs
  with:
    layout: embedded

The action expects a committed manifest and matching lockfile. It downloads the tagged cs, cs-template, and SHA256SUMS release assets for the runner, verifies their GitHub Artifact Attestations, checks the release checksums, runs cs build --dry-run, and then stages the runtime into a dist-path output.

Use release tags for release builds. Branch refs do not have matching conda-ship release assets.

Packaging

conda-ship is not an OS installer generator. It does not target .sh, .pkg, or .msi output directly. It produces runtimes that can be distributed as GitHub Release assets or wrapped by Homebrew, constructor, Docker, enterprise packaging systems, and other release tooling.

The PyPI package and conda package install the cs builder, the cs-template runtime template, and the Python adapter together. The adapter makes conda ship a shortcut for the same builder when installed in a conda environment; it does not make conda-ship part of conda itself.

What Belongs Downstream

Downstream distributions decide:

• runtime names and delegates
• package sets and channels
• package exclusions
• install schemes and install names
• documentation URLs
• release channels and installers
• signing, SBOM, and in-toto provenance for final artifacts

conda-ship verifies the inputs it consumes and the package archives it stages or installs, but downstream release systems should sign and attest the final runtime artifacts after cs build.

Documentation

Full documentation is available at jezdez.github.io/conda-ship.

Useful starting points:

• Build your first runtime
• Build in GitHub Actions
• Configuration reference
• Project boundaries

Development

pixi install
pixi run test
pixi run lint
pixi run -e test pytest
pixi run docs

Run cargo generate-lockfile after changing Cargo metadata and pixi lock after changing pixi metadata.

License

BSD-3-Clause