Generated Runtime Reference#

Every conda-ship artifact is a stamped copy of the generic runtime template. In this page, RUNTIME stands for the staged executable name and DELEGATE stands for the configured executable inside the managed prefix.

The generated runtime does not expose a conda-ship CLI. It owns the bootstrap boundary needed to make the delegate available. When executable updates are configured, it also exposes a process-local helper for a downstream transaction coordinator. Normal command arguments still belong to the delegate.

First Invocation#

When the managed prefix is absent, the first invocation automatically installs the stamped package set and then executes the delegate with the original arguments:

RUNTIME info

For a conda delegate, that invocation bootstraps the prefix and then runs conda info. For a Python delegate, this invocation bootstraps the prefix and then runs python --version:

RUNTIME --version

A bare invocation also bootstraps and then invokes the delegate without arguments.

The same behavior applies to online, external, and embedded artifacts. Online artifacts download packages from the stamped runtime lock. External artifacts read archives from the configured bundle directory. Embedded artifacts automatically extract their built-in bundle.

During bootstrap, the runtime writes conda-ship ownership metadata and the prefix metadata expected by conda tools in conda-meta/history and conda-meta/initial-state.explicit.txt. It writes .condarc only when the build configured condarc-file, and writes the CEP 22 frozen marker only when the build configured freeze-base = true.

Bootstrap is serialized with a process lock next to the managed prefix. An internal installing marker identifies an incomplete prefix owned by this runtime. The runtime metadata file is written after package installation, post-link scripts, prefix metadata, configured policy, bytecode compilation, and delegate validation finish. Its ready state marks bootstrap complete.

If bootstrap is interrupted, the next invocation automatically retries only when that internal marker belongs to the same stamped runtime. Recovery forces every locked package through Rattler’s reinstall path so post-link scripts run again. It does not delete the prefix, named environments, or unrelated paths. An unknown non-empty prefix is still refused.

Delegate Execution#

After the prefix is available, every argument belongs to the delegate. The runtime does not reserve or rewrite any of these names:

  • --help and --version

  • status and uninstall

  • shell and self

  • activate, deactivate, and init

  • delegate verbosity and quiet options

Standard input, output, and error pass through unchanged, and the runtime preserves the delegate’s signal and exit behavior. It does not filter delegate output or set CONDA_PREFIX, CONDA_DEFAULT_ENV, or CONDA_SHLVL.

For a conda delegate, normal commands therefore look like direct conda commands:

RUNTIME create -n myenv python=3.12 numpy
RUNTIME install -n myenv pandas
RUNTIME list -n myenv
RUNTIME env list
RUNTIME info
RUNTIME --help
RUNTIME --version

RUNTIME info is the normal status command for a conda delegate. If the distribution includes conda-spawn with the alias implemented by conda-spawn PR #59, RUNTIME shell uses the conda-spawn alias for conda spawn.

Use conda doctor and its supported fixes to diagnose and repair an installed prefix. Use the commands supplied by conda-self for installer snapshots and self-management when the distribution includes that plugin.

Executable Updates#

Executable updates are disabled unless the runtime was built with [tool.conda-ship.update]. Runtimes without that table keep the normal bootstrap and delegate behavior. The update engine does not reserve an update, self, or other delegate subcommand.

The stamp records the update channel, package, and current build number. Every update-enabled executable contains the direct update engine. The installed metadata has two ownership modes:

direct

A downstream coordinator can check, stage, and apply a native executable update. The executable resolves packages from its stamped conda channel and replaces its recorded stable path only after the coordinator approves the candidate and completes the inner transaction.

external

The check result reports a newer package record and an optional instruction. The executable does not stage or apply that package. A package manager or installer replaces the executable. The next normal invocation validates the new stamp and reconciles the existing .RUNTIME_NAME.json record.

Every normal invocation recovers an interrupted replacement before starting the delegate. A directly owned executable that changes outside the coordinated flow is rejected. An externally owned executable can be reconciled when its stamp and recorded identity are valid.

Resolution And Verification#

The runtime reads native repodata.json for the current platform and selects the newest .conda package whose (version, build number) pair sorts after the stamped executable. A higher version can therefore use a lower build number. The runtime does not solve an environment and it does not install the update package into the managed prefix.

Direct staging verifies the repodata size and SHA256, conda package metadata, payload size and SHA256, executable stamp, runtime and artifact identity, platform, version, build number, and update source. A candidate cannot rotate its update channel or package.

Update channels must use https:// or file://. Stamped URLs cannot contain credentials, a query, or a fragment. HTTPS requests can read credentials from the explicit JSON file selected with RATTLER_AUTH_FILE. The runtime does not enable keyring, netrc, or default auth-file discovery. It does not provide an interactive login or a provider-specific API.

Online requests cache repodata and verified package content. Offline HTTPS checks require cached repodata and offline staging requires the selected package content to be cached. A file:// channel reads local repodata and packages directly.

Version-One Coordinator Contract#

The helper is a compatibility contract for downstream transaction coordinators and installers. It is not a user-facing command. The coordinator invokes the stamped executable as a child process with CONDA_SHIP_PREFIX set to the managed prefix when it needs to override the runtime’s stamped install location.

Before invoking check, stage, or apply, the coordinator opens <prefix>/.RUNTIME_NAME.update.lock and holds an exclusive operating-system file lock. The runtime creates this one-byte regular file during update initialization. The coordinator must hold it through check, stage, the inner transaction, and apply. Each version-one action fails when the lock is not held.

Record Installation#

An installer or delivery detector records how this copy of the executable is managed:

CONDA_SHIP_INTERNAL_UPDATE=v1/record-installation
CONDA_SHIP_INTERNAL_UPDATE_OWNERSHIP=external
CONDA_SHIP_INTERNAL_UPDATE_INSTALLATION=homebrew
CONDA_SHIP_INTERNAL_UPDATE_EXECUTABLE=/opt/homebrew/bin/demo

This action completes bootstrap when needed and does not invoke the delegate. The executable path must be absolute and resolve to the running executable. External package managers should pass their stable executable path rather than a versioned target.

Direct installers use direct ownership and an installation label such as standalone or constructor. An external installer should also set CONDA_SHIP_INTERNAL_UPDATE_INSTRUCTION to the final user-facing update instruction when one is available.

Bootstrap metadata created before an installer records this value has no installation label. This compatibility state may reconcile a valid newer executable with the same runtime identity and update source. The installer or delivery detector should record ownership before the first update check.

The action writes one JSON object:

{
  "recorded": true
}

The updated values are persisted in .RUNTIME_NAME.json, which is the source of truth for later checks.

Recording may change a direct installation to external. It cannot make an external installation direct or change an existing external instruction. Changing direct to external may also replace the installation label and stable path, which supports moving an existing standalone runtime under a package manager. Other attempts to change an existing installation label are rejected. The action also rejects pending executable replacement state. An adopting package manager must invoke this action during installation, before the replacement executable is run normally. Post-delegation receipt detection cannot adopt a confirmed direct installation after its executable has already changed.

Check#

Set:

CONDA_SHIP_INTERNAL_UPDATE=v1/check

A successful check writes one JSON object to stdout:

{
  "available": true,
  "current_version": "1.0.0",
  "current_build_number": 0,
  "version": "1.1.0",
  "build_number": 0,
  "package": "demo-runtime",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "ownership": "direct",
  "installation": "standalone",
  "instruction": null
}

When no candidate exists, available is false and the candidate fields are null. Ownership, installation, and instruction come from the installed runtime metadata rather than the executable stamp. External ownership must not continue to stage.

If check completes recovery of an interrupted update, it exits with an error that asks the coordinator to retry. This keeps recovery separate from candidate selection.

Stage#

After the user or non-interactive policy approves a direct candidate, set:

CONDA_SHIP_INTERNAL_UPDATE=v1/stage
CONDA_SHIP_INTERNAL_UPDATE_CANDIDATE=SHA256_FROM_CHECK

Stage resolves the candidate again, rejects a changed selection, downloads and validates the package, and copies the executable next to the stable executable. A successful stage writes:

{"staged":true}

The coordinator then performs the inner transaction while retaining the update lock. If that transaction fails, it must not invoke apply. It releases the lock and leaves the old executable working. The next normal invocation or check discards an unapproved staged candidate.

Apply#

After the inner transaction succeeds, set:

CONDA_SHIP_INTERNAL_UPDATE=v1/apply

On Unix, a successful atomic replacement writes:

{"applied":true}

On Windows, apply can defer replacement until the running executable exits:

{"applied":false,"replacement_pending":true}

The coordinator releases the update lock after apply returns. Helper failures write diagnostics to stderr and exit nonzero. Successful actions write one JSON object to stdout.

Set CONDA_SHIP_INTERNAL_UPDATE_OFFLINE=1 on check and stage to disable network access. Empty, 0, and false leave network access enabled. This flag is separate from the runtime-specific bootstrap offline variable.

All persistent update and recovery state remains inside the existing .RUNTIME_NAME.json prefix metadata file. The helper introduces no daemon, service, receipt, or second metadata record.

Windows Deferred Replacement#

Windows cannot replace the executable while the current process is using it. Apply preserves a verified copy of the old executable as a detached replacement worker, records the replacing state, and returns replacement_pending.

The worker waits up to 30 seconds for the stable executable to close, installs the staged candidate, and leaves the old copy in place until the new stable path is verified. The next invocation completes metadata reconciliation and cleanup. If the worker is interrupted or times out, the old executable remains usable and a later invocation retries recovery.

Bootstrap Controls#

CONDA_SHIP_PREFIX is the universal managed-prefix override. It takes precedence over a runtime-specific prefix variable. Bundle and bootstrap offline controls are derived from the configured runtime name. Non-alphanumeric characters become underscores and letters are uppercased.

For a runtime named demo, the variables are:

DEMO_PREFIX

Compatibility override for the managed prefix path. Runtime names other than conda accept this derived form. A runtime named conda ignores CONDA_PREFIX because it can describe an activated environment. Use CONDA_SHIP_PREFIX for that runtime.

DEMO_BUNDLE

Path to an external directory containing the package archives named in the stamped runtime lock.

DEMO_OFFLINE

Disable network access during bootstrap. Empty, 0, and false disable the flag. Other non-empty values enable it.

Example:

CONDA_SHIP_PREFIX=/opt/demo \
DEMO_BUNDLE=/opt/demo-bundle \
DEMO_OFFLINE=1 \
demo info

The runtime reads these values only to locate and bootstrap the managed prefix. They do not consume or replace delegate arguments.

Embedded artifacts need no bundle or offline override:

CONDA_SHIP_PREFIX=/opt/demo demo info

For local smoke tests through the builder, prefer cs run --install-path PATH instead of setting the prefix variable yourself:

cs run --install-path /tmp/demo-smoke -- info