xcrunner 0.1.3__tar.gz

xcrunner-0.1.3/.github/release-notes/v0.1.2.md

@@ -0,0 +1,36 @@
+First release on PyPI. The package is `xc-xrunner`, and the command is `xrunner`.
+
+xrunner is a rootless container runtime for Docker images. It runs the images that coala and coala-runtime use on hosts with no Docker and no root.
+
+## Install
+
+    pip install xc-xrunner
+    xrunner info
+
+Add the `zstd` extra for zstd-compressed image layers: `pip install 'xc-xrunner[zstd]'`.
+
+## Changes since v0.1.1
+
+- The package is renamed from `xcodon-runtime` to `xc-xrunner`, its name on PyPI. The Python module is still `xcodon_runtime`. If an older copy is installed, uninstall `xcodon-runtime` before installing `xc-xrunner`.
+- v0.1.1 was published on GitHub only, under the old name.
+
+## What it does
+
+- **Two engines, picked at startup.** The ns engine uses user namespaces and overlayfs at native speed. The proot engine uses a bundled PRoot and works on any Linux.
+- **Images.** Pulls anonymously from Docker Hub, quay.io and ghcr.io. Reuses images from a local Docker daemon.
+- **Docker-style commands.** `run`, `create`, `start`, `exec`, `stop`, `rm`, `pull`, `rmi`, `tag`, `logs` and `prune`.
+- **Build and commit without a daemon.** `xrunner build` runs a Dockerfile subset. `xrunner commit` snapshots a container.
+- **Docker shim.** A `docker` command that sends supported calls to xrunner, for tools such as cwltool.
+- **Conda shim.** `conda`, `mamba` and `micromamba` commands over a pinned micromamba, kept apart from the user's own conda.
+- **Env folders.** `--env-dir` and `XRUNNER_ENV_DIR` keep installed tools across containers.
+- **Environment record.** Each project gets a record of the images and packages it used.
+- **Sandbox activation.** `xrunner sandbox activate` sets up a project's shims and prints the settings a shell needs.
+- **Clusters.** `XRUNNER_CONTAINER_DIR` keeps container folders on a node-local disk while images stay on shared storage.
+- **Integrations.** Works with coala through cwltool, and with coala-runtime as a container engine.
+
+## Known limits
+
+- One user id inside a container.
+- Host network only.
+- No cgroups and no GPU passthrough.
+- The conda shim and the bundled PRoot are for x86_64 only.

xcrunner-0.1.3/.github/release-notes/v0.1.3.md

@@ -0,0 +1,34 @@
+xrunner is now **xcrunner**: the command, the PyPI package, the settings and the folders. This release also adds experimental macOS support and three features that help on every platform.
+
+    pip install xcrunner
+
+## The rename
+
+This is a clean break. Nothing reads the old names.
+
+- The command is `xcrunner`. The PyPI package is `xcrunner`; `xc-xrunner` gets no more releases. Uninstall it first: `pip uninstall xc-xrunner`.
+- Every `XRUNNER_*` setting is now `XCRUNNER_*`, for example `XCRUNNER_ENV_DIR`.
+- A project's env folder is now `.xcrunner-env`. An existing `.xrunner-env` is not used; rename it, or let xcrunner start a new one.
+- The engine value in coala and coala-runtime is `xcrunner`, and coala-runtime's extra is `[xcrunner]`.
+- The repository is `xcodon-ai/xcrunner`. The Python module is still `xcodon_runtime`, and the `XCODON_*` settings keep their names.
+
+## macOS (experimental)
+
+xcrunner now runs on Apple silicon Macs with macOS 26 or newer. It runs the Linux xcrunner inside one Lima VM.
+
+    brew install lima
+    pip install xcrunner
+    xcrunner machine start
+    xcrunner run --rm alpine echo hi
+
+- The first `xcrunner machine start` creates an Ubuntu 24.04 VM with Rosetta. Your home folder, `/private/var/folders` and `/private/tmp` are shared into it at the same paths.
+- `conda`, `shim`, `sandbox` and `machine` run on the Mac. Every other command runs in the VM, with the same exit code and output.
+- `xcrunner machine start|stop|status|shell|rm` manage the VM. The `XCRUNNER_MACHINE_*` settings set its size and extra shared folders.
+- This release was tested on Linux against a fake Lima only. It has not run on a real Mac yet. `scripts/mac_smoke.sh` runs the end-to-end checks on a Mac; please report what fails.
+
+## All platforms
+
+- **`XCRUNNER_ENV_LAYER_DIR`** keeps env folder layers on another disk, while the environment record stays in the project. On a cluster, point it at node-local disk.
+- **x86_64 images on ARM hosts.** With a Rosetta or qemu-x86_64 handler registered, an image list without an ARM image falls back to x86_64.
+- **Pull-time architecture check.** An image the host cannot run now fails at pull time with a clear message, instead of failing later with "exec format error". An explicit `--platform` skips the check.
+- **Conda shim on macOS ARM.** The shim pins micromamba 2.9.0 for `osx-arm64` as well as `linux-64`. A failed install on a Mac suggests `--platform osx-64`.

xcrunner-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: sudo apt-get update && sudo apt-get install -y busybox-static
+      - run: pip install -e ".[dev,zstd]"
+      - run: ruff check src tests
+      - run: xcrunner info
+      # cwltool is not installed in this job, so the cwltool-marked tests skip by design.
+      - run: pytest -q -rs
+      - run: XCODON_TEST_NETWORK=1 pytest -q -rs -m network
+  # The Mac side only: no VM on GitHub's macOS runners. Catches Linux-only imports
+  # and runs the tests that do not need Linux (spec 16.10).
+  macos:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev,zstd]"
+      - run: python -c "import xcodon_runtime.cli, xcodon_runtime.macvm, xcodon_runtime.forwarded"
+      - run: xcrunner --version
+      - run: pytest -q -rs tests/test_macvm.py tests/test_macvm_forward.py tests/test_forwarded.py tests/test_micromamba_platforms.py

xcrunner-0.1.3/.github/workflows/release.yml

@@ -0,0 +1,113 @@
+name: Release
+
+# A pushed v* tag builds the package, creates the GitHub release with the wheel
+# and sdist attached, and publishes to PyPI. For a tag pushed before this
+# workflow existed, run it by hand: gh workflow run release.yml -f tag=v0.1.1
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to build and release, for example v0.1.1"
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ inputs.tag || github.ref_name }}
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+    steps:
+      - name: Pick the tag
+        id: tag
+        env:
+          TAG: ${{ inputs.tag || github.ref_name }}
+        run: echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.11"
+
+      - name: Check the tag matches the package version
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          test "${TAG#v}" = "$version" || { echo "tag $TAG does not match version $version"; exit 1; }
+
+      - name: Build package
+        run: uv build
+
+      - name: Check the wheel carries the PRoot binary
+        run: unzip -l dist/*.whl | grep -q 'xcodon_runtime/_bin/proot-x86_64'
+
+      - name: Keep the files
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    name: GitHub release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Checkout the tag, for its release notes
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.build.outputs.tag }}
+          path: src
+
+      # .github/release-notes/<tag>.md in the tagged commit becomes the release
+      # body; without one, GitHub generates the notes.
+      - name: Create the release, or add the files to it
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.build.outputs.tag }}
+        run: |
+          notes=(--generate-notes)
+          if [ -f "src/.github/release-notes/$TAG.md" ]; then notes=(--notes-file "src/.github/release-notes/$TAG.md"); fi
+          if gh release view "$TAG" -R "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber -R "$GITHUB_REPOSITORY"
+          else
+            gh release create "$TAG" dist/* --title "$TAG" "${notes[@]}" --verify-tag -R "$GITHUB_REPOSITORY"
+          fi
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

xcrunner-0.1.3/.gitignore

@@ -0,0 +1,8 @@
+.superpowers/
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+docs/superpowers/

xcrunner-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qiang Hu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xcrunner-0.1.3/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.5
+Name: xcrunner
+Version: 0.1.3
+Summary: Rootless container runtime for Docker images, built for coala
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: zstd
+Requires-Dist: zstandard>=0.21; extra == 'zstd'
+Description-Content-Type: text/markdown
+
+# xcrunner
+
+A rootless container runtime for Docker images. It runs the images that
+coala and coala-runtime use on hosts without Docker and without root.
+
+Two engines, chosen automatically:
+
+- **ns**: kernel user namespaces plus overlayfs, no helper binary. Native
+  speed. Needs a Linux kernel 5.11 or newer with unprivileged user namespaces
+  enabled. Most workstations, cloud VMs, and current HPC nodes qualify.
+- **proot**: a vendored static PRoot runs the container under ptrace. Works
+  on any Linux, slower, and creation copies the image rootfs.
+
+## Install
+
+    pip install xcrunner                # or: uv pip install xcrunner
+    xcrunner info                            # shows the engine and probe results
+
+Optional: `pip install 'xcrunner[zstd]'` for zstd-compressed layers.
+On aarch64 hosts without user namespaces, provide a PRoot binary with
+`XCODON_PROOT=/path/to/proot`. The command is `xcrunner`. The package on PyPI is `xcrunner`, and the Python module is `xcodon_runtime`.
+## Use
+
+    xcrunner pull python:3.12-slim
+    xcrunner run --rm -v $PWD:/work -w /work python:3.12-slim python -c 'print("hi")'
+    xcrunner create --name dev python:3.12-slim
+    xcrunner start dev
+    xcrunner exec dev pip install numpy      # persists in the container's writable layer
+    xcrunner exec dev python -c 'import numpy'
+    xcrunner stop dev && xcrunner rm dev
+    xcrunner logs dev                        # the ns engine's keeper log
+    xcrunner rmi python:3.12-slim            # drop a tag, and the image with its last tag
+    xcrunner prune                           # leftovers: half-built dirs and orphan blobs
+    xcrunner prune --all                     # also unused layers and day-old exited containers
+
+    xcrunner run --rm --env-dir $PWD/.xcrunner-env python:3.12-slim pip install numpy
+    xcrunner run --rm --env-dir $PWD/.xcrunner-env python:3.12-slim python -c 'import numpy'
+
+`--env-dir` keeps the container's writable layer in a host folder, keyed by
+image id, so tools installed in one container are there for the next one.
+Delete `<env-dir>/<image-id>` to reset. coala-runtime uses this through the
+`XCRUNNER_ENV_DIR` variable.
+
+Two global flags come before the subcommand: `--engine ns|proot` forces an
+engine, and `--home DIR` picks the state directory for this one command.
+
+Images already in a local Docker daemon are reused through `docker save`, so
+locally built images work without a registry. xcrunner records the daemon's
+image id at import. When the daemon's tag later points at another image
+(for example after a `docker build` there), the next `run`, `create`, or
+`build` that uses the tag imports it again. `--pull never` and image ids
+skip this check.
+
+## Build and commit
+
+    xcrunner build -t myapp:1 .                          # runs a Dockerfile subset
+    xcrunner commit -m "installed numpy" dev myapp:2      # snapshot a stopped container
+    xcrunner tag myapp:2 myapp:latest
+
+`xcrunner build` runs each Dockerfile instruction in its own container and
+commits one image per step, so unchanged steps are cached. The cache lives
+in `<home>/build-cache.json`. The step images are untagged, and
+`xcrunner prune --all` removes untagged images, which empties the cache in
+effect. `xcrunner commit` also works on an `--env-dir` folder instead of a
+container: `xcrunner commit --env-dir $PWD/.xcrunner-env --image myapp:1 myapp:2`.
+
+Docker-style names work too:
+
+    xcrunner image inspect myapp:1                       # also: image ls, image rm
+    xcrunner docker build -t myapp:1 .                   # any docker verb xcrunner supports
+    xcrunner docker image inspect --format '{{.Id}}' myapp:1
+
+`xcrunner docker VERB ...` takes docker's own verbs and flags for `build`,
+`image inspect|ls|rm`, `images`, `rmi`, `tag`, `pull`, `run`, `create`,
+`start`, `exec`, `stop`, `rm`, `ps`, `logs`, `commit`, `inspect`, `version`, and
+`info`. Other verbs exit with code 125 and a message.
+
+For tools that shell out to a real `docker` binary directly — running
+`docker build` or `docker image inspect` as a subprocess, rather than going
+through cwltool's `--user-space-docker-cmd` — `xcrunner shim install` writes
+a `docker` script that forwards every call to `xcrunner docker`:
+
+    xcrunner shim install --dir ~/.local/bin
+    export PATH="$HOME/.local/bin:$PATH"
+    docker build -t myapp:1 .
+    docker image inspect myapp:1
+
+The shim refuses to install while any real `docker` is anywhere on PATH,
+even outside DIR, unless you pass `--force`. It also refuses to replace a
+`DIR/docker` that is not an xcrunner shim unless you pass `--force`, and it
+never replaces a directory. xcrunner also never mistakes its own shim for a
+real Docker daemon: image pulls that would reuse a local `docker save` skip
+a shim.
+
+Limits on the Dockerfile subset: no multi-stage builds (a second `FROM`, or
+`--from=`), no `.dockerignore`, and no remote `ADD`/`COPY` from a URL.
+
+## Tools without conda
+
+Agents often install command-line tools with `conda create`, `conda install` and
+`conda run`. On a host with no conda, xcrunner can answer those calls itself:
+
+    xcrunner shim install conda --dir ~/.xcodon/shim
+    export PATH="$HOME/.xcodon/shim:$PATH"
+
+This downloads a pinned micromamba (2.9.0, from conda-forge, checksum-verified) to
+`<xcrunner home>/bin/micromamba-2.9.0/micromamba` and writes `conda`, `mamba` and
+`micromamba` scripts that forward to `xcrunner conda`.
+Offline, pass `--micromamba PATH` to use a binary you already have.
+
+- Environments live in the project's `.xcrunner-env/conda` (found from the working
+  directory, or from `XCRUNNER_ENV_DIR`), else under the xcrunner home. Downloads are
+  cached once under the xcrunner home. A `.xcrunner-env` found by searching upward is
+  used only when you own it and no one else can write to it.
+- Launchers should export `XCRUNNER_ENV_DIR=<project>/.xcrunner-env`, or create
+  `<project>/.xcrunner-env`, before the agent starts. Otherwise an early conda call
+  falls back to the xcrunner home: its envs land outside the project, `conda env
+  list` in the project does not show them, and the agent's `run_shell` guardrail
+  refuses their paths.
+- A relative `-p PATH` is always a folder under the working directory, even
+  without a `/`.
+- Your own `~/.conda` and `~/.condarc` are never read or written.
+- `conda run -n NAME CMD` runs CMD with the env on PATH; `conda activate` is not
+  supported, because it changes the calling shell.
+- Each env gets `conda-explicit.txt`, listing every package URL and checksum, so it
+  can be rebuilt with `conda create -p PATH --file conda-explicit.txt`.
+- The shim refuses to install while a real conda, mamba or micromamba is on PATH,
+  unless you pass `--force`.
+- The shims use the default xcrunner home, or `XCODON_RUNTIME_HOME` when it is set;
+  they do not remember an `xcrunner --home H` given at install time. After
+  `xcrunner --home H shim install conda ...`, also export `XCODON_RUNTIME_HOME=H`
+  wherever the shims run, or they will look for micromamba in the default home
+  instead.
+
+## Sandbox activation
+
+`xcrunner sandbox activate /abs/project/.xcrunner-env` writes `docker`, `conda`,
+`mamba` and `micromamba` shims into the project's `.xcrunner-env/bin` and prints
+the two `export` lines (PATH first, then `XCRUNNER_ENV_DIR`) that send a shell's
+docker and conda calls to xcrunner. The Python API is
+`xcodon_runtime.sandbox.activate(env_dir)`. opencodon calls it by itself when
+its container engine is `xcrunner`, so `--container-engine xcrunner` is enough.
+
+## Environment record
+
+xcrunner keeps `.xcrunner-env/environment.json`, a per-project record of the images a
+project used (id, source, registry digests, and any build Dockerfile) and the
+packages each install added, changed or removed.
+
+For each image it also keeps the platform, package counts, and for built images
+the packages the build added. `.xcrunner-env/packages/<image id>.json` holds the full
+package list of each image the project used, not only the changes.
+
+The record updates automatically after conda changes and when containers stop.
+`xcrunner env show` prints it, `xcrunner env show --json` prints the file, and
+`xcrunner env record` rebuilds it from what is on disk. Images keep their entries as
+history; `env record` never removes one.
+
+It is a record, not a restore mechanism: it does not recreate images or packages,
+only describes what happened. Images built before this feature have no Dockerfile
+on record. On the proot engine each container stop rescans the rootfs copy, which
+takes about 3-4 s on large images.
+
+## Hosts without docker
+
+On a host with no docker daemon, a `FROM` name that only ever existed in a
+local daemon, such as `coala-runtime-python:latest`, is looked up on Docker
+Hub and not found there. Seed such base images once: pull the published
+image and give it the local name.
+
+    xcrunner pull hubentu/coala-runtime-python:latest
+    xcrunner tag hubentu/coala-runtime-python:latest coala-runtime-python:latest
+    xcrunner pull hubentu/coala-runtime-r:latest
+    xcrunner tag hubentu/coala-runtime-r:latest coala-runtime-r:latest
+
+After that, `FROM coala-runtime-python:latest` uses the stored image and
+never goes to the network. xcrunner does not map image names itself.
+
+## Clusters with shared storage
+
+Overlayfs cannot write its upper layer to NFS, Lustre or GPFS. When the home is on
+shared storage, the overlay probe fails and xcrunner falls back to the slower proot
+engine. Keep the image store on shared storage and put container folders on a
+node-local disk:
+
+    export XCODON_RUNTIME_HOME=/shared/$USER/xcrunner
+    export XCRUNNER_CONTAINER_DIR=${TMPDIR:-/tmp}/xcrunner-containers
+
+Images are pulled once into the shared home and read from there. Each container's
+writable layer, its keeper log and its locks live under `XCRUNNER_CONTAINER_DIR`.
+Containers are then local to one node: `xcrunner ps` on another node does not list
+them. `xcrunner info` shows both folders and the engine the probes chose.
+
+The setting does not move an env folder's layers. On the ns engine they must also be
+on a local disk. Set `XCRUNNER_ENV_LAYER_DIR` to node-local storage: the record stays
+in the project's env folder, and each node keeps its own layers for as long as that
+disk lasts. Or set `XCODON_ENGINE=proot` to keep the layers on shared storage.
+
+## macOS
+
+On an Apple silicon Mac with macOS 26 or newer, xcrunner runs the Linux xcrunner
+inside one Lima VM. Install Lima first:
+
+    brew install lima
+    pip install xcrunner
+    xcrunner machine start        # the first start creates the VM and takes a few minutes
+    xcrunner run --rm alpine echo hi
+
+- The VM is a Lima `vz` VM named `xcrunner` with Ubuntu 24.04 and Rosetta. Images,
+  layers and containers live on its own disk.
+- Your home folder, `/private/var/folders` and `/private/tmp` are shared into the VM
+  at the same paths, so bind mounts and cwltool's temp folders work unchanged. Work
+  in one of those folders, or add more with `XCRUNNER_MACHINE_MOUNTS` before the VM is
+  created.
+- `conda`, `shim`, `sandbox` and `machine` run on the Mac. Every other command runs
+  in the VM. The conda shim installs macOS programs with a macOS micromamba.
+- Env folder layers live on the VM disk; the record in `.xcrunner-env` stays with the
+  project. `xcrunner info` shows where the layers are.
+- x86_64-only images, such as most biocontainers, run through Rosetta.
+- `xcrunner machine status|stop|shell|rm` manage the VM. `rm` deletes its disk,
+  with all images and env layers.
+
+`scripts/mac_smoke.sh` runs the end-to-end checks on a Mac and writes a report to
+`~/xcrunner-mac-smoke.txt`.
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `XCODON_RUNTIME_HOME` | State directory. Default `~/.xcodon/runtime`. |
+| `XCRUNNER_CONTAINER_DIR` | Container folders. Default `<home>/containers`. |
+| `XCRUNNER_ENV_LAYER_DIR` | Env folder layers on another disk. Default: in the env folder. On a cluster, a node-local disk gives each node its own layers. |
+| `XCRUNNER_MACHINE_NAME` | macOS: the Lima VM's name. Default `xcrunner`. |
+| `XCRUNNER_MACHINE_CPUS`, `XCRUNNER_MACHINE_MEMORY`, `XCRUNNER_MACHINE_DISK` | macOS: VM size when it is created. Defaults `4`, `4GiB`, `100GiB`. |
+| `XCRUNNER_MACHINE_MOUNTS` | macOS: extra Mac folders to share, separated by `:`. |
+| `XCODON_ENGINE` | `ns` or `proot`. Skips probing. |
+| `XCODON_PROOT` | Path to a PRoot binary. |
+| `XCODON_PROOT_ARGS` | Extra PRoot flags, for example `-k 5.15.0`. |
+| `XCODON_LOG` | `info` or `debug`. |
+
+## Limits
+
+- One uid inside the container. Every image file is owned by that uid.
+  `chown` to another user fails. Setuid binaries do not elevate.
+- Host network only. No `--net=none`, no port mapping.
+- No cgroups. `--memory` and `--cpus` are accepted and ignored with a warning.
+- No GPU passthrough.
+- macOS: Apple silicon and macOS 26 or newer only, through a Lima VM.
+- Read-only binds apply to the top mount only; submounts under a bound host
+  path stay writable.
+
+## coala
+
+In coala, add one branch to `configure_container_runner`:
+
+```python
+    if container_runner == "xcrunner":
+        runtime_context.user_space_docker_cmd = shutil.which("xcrunner") or "xcrunner"
+```
+
+cwltool then calls `xcrunner inspect`, `xcrunner pull`, and `xcrunner run` with
+docker-style flags.
+
+## coala-runtime
+
+xcodon-runtime ships `xcodon_runtime.coala_adapter.XcodonContainerManager`,
+which implements coala-runtime's `ContainerManager` interface. In
+coala-runtime, add `XCRUNNER = "xcrunner"` to `ContainerEngine`, return the
+adapter from `make_container_manager` for that value, and try it in
+autodetection after Docker and Podman and before Apptainer.
+
+## Development
+
+    uv venv .venv && . .venv/bin/activate
+    uv pip install -e ".[dev,zstd]"
+    python scripts/fetch_proot.py          # only if _bin/ is missing
+    pytest -q                              # unit + ns + proot on a capable host
+    XCODON_TEST_NETWORK=1 pytest -m network