CondaTainer Manual

πŸ“¦ CondaTainer is a CLI tool designed to streamline the management of Apptainer (Singularity) containers backed by Conda environments and SquashFS overlays.

Table of Contents

Overall Command Structure

CondaTainer: Use Apptainer/Conda/Overlays/SquashFS to manage tools/data/env for HPC users.

Usage:
  condatainer [command]

Available Commands:
  avail       Check available build scripts (local and remote)
  check       Check if the dependencies of a script are installed
  completion  Generate shell completion script
  config      Manage condatainer configuration
  create      Create a new SquashFS overlay
  e           Quick shortcut for executing commands with overlays
  exec        Execute a command using overlays (explicit -o flag)
  helper      Manage and run helper scripts
  info        Show information about a specific overlay
  instance    Manage Apptainer instances
  list        List installed overlays matching search terms
  o           Shortcut for 'overlay create'
  overlay     Manage persistent overlay images (create, resize, check, info)
  remove      Remove installed overlays matching search terms
  proxy       Manage the shared SOCKS5 proxy tunnel for compute nodes
  run         Run a script and auto-solve the dependencies by #DEP tags
  scheduler   Display scheduler information
  search      Search conda packages via anaconda.org API
  self-update Update condatainer to the latest version from GitHub
  update      Update build script metadata cache or the base image

Flags:
      --debug     Enable debug mode with verbose output
  -h, --help      help for condatainer
      --local     Disable job submission (run locally)
  -q, --quiet     Suppress messages (warnings/errors are still shown)
  -v, --version   version for condatainer
  -y, --yes       Automatically answer yes to all prompts

Use "condatainer [command] --help" for more information about a command.

Naming Convention

CondaTainer classifies overlays into three distinct categories based on their naming structure.

System Applications (OS)

Used for system-level applications that do not follow the standard application or reference naming conventions.

Like text editors, IDEs, build-essential tools, etc.

  • Format: name

  • Constraints:

    • Must not contain slashes (/) or double-dash sequences (--).

    • Unless <distro>/<application>

  • Example: rstudio-server, texlive, code-server

You can also create these system apps using the -n, --name flag with the create command.

Custom Environments (Bundle/Workspace)

Used when creating a custom environment with a user-defined name (create -p, or overlay action).

  • Format: custom_name

  • Constraints:

    • Must not contain the double-dash sequence (--).

    • Should not conflict with common application names (to avoid ambiguity with app overlays).

  • Example: my_analysis_env, project_x_utils

[!NOTE] Use -n to install system apps only (e.g., nvim). To create an environment .sqf, use -p to specify a prefix/path.

Application Overlays (Module)

Used for standard software packages and tools managed by CondaTainer build scripts.

  • Format: name/version

  • Structure:

    • name: The software package or tool name (e.g., bcftools).

    • version: The specific version of the software (e.g., 1.22).

  • Example: cellranger/9.0.1

Reference Overlays (Module)

Used for reference datasets, genome assemblies, or indices.

  • Format: assembly/data-type/version

  • Structure:

    • assembly: The genome assembly or project (e.g., grch38).

    • data-type: The type of data (e.g., gtf-gencode).

    • version: The release or build version (e.g., 47).

  • Example: grch38/gtf-gencode/47

[!NOTE] -- is reserved for separating components in overlays. For example, bcftools/1.22 overlay will be located at images/bcftools--1.22.sqf.

Rename or not to Rename?

TL;DR: Do not rename sqf files. img files can be renamed.

CondaTainer relies on the overlay names to determine mount points and environment variable settings. Renaming .sqf files can lead to inconsistencies and runtime errors.

e.g.

  • bcftools/1.22 is mounted at /cnt/bcftools/1.22

  • grch38/gtf-gencode/47 is mounted at /cnt/grch38/gtf-gencode/47

  • my_analysis_env.sqf is mounted at /cnt/my_analysis_env

For .img files, the mount point is always /ext3/env, so renaming is allowed.

Mount Points

CondaTainer uses clear terminology for overlay types and purposes. Read-only overlays use the .sqf extension (SquashFS) and writable overlays use the .img extension (ext3).

Overlay Terminology

Term

Extension

R/W

Content Path

Purpose

OS

.sqf

R/O

/bin, /lib, /usr

System Foundation β€” minimal system root that can run standalone or serve as a base for Modules/Bundles.

Module

.sqf

R/O

/cnt/<name>/<version>

Individual tool overlay (single package) mounted under /cnt and layered on top of an OS or Bundle.

Bundle

.sqf

R/O

/cnt/<env_name>

Frozen Conda environment (prebuilt collection of packages) mounted under /cnt as a named environment.

Workspace

.img

R/W

/ext3/env

Writable Conda environment (ext3 image) for interactive work and runtime package changes.

Read-only .sqf overlays are ideal for distributing immutable software and reference data. Writable .img overlays are for live development or when packages must be changed at runtime.

Mount points and examples

  • Read-only overlays (.sqf) are mounted under /cnt following their naming convention.

    • Module example: bcftools/1.22 β†’ mounted at /cnt/bcftools/1.22.

    • Bundle example: my_project_env.sqf β†’ mounted at /cnt/my_project_env.

    • OS overlays present system directories (e.g., binaries under /bin) inside the container filesystem exposed by the overlay.

  • Writable images (.img) mount at /ext3/env and expose a full ext3 filesystem where packages may be installed or modified.

Writability: .sqf overlays are read-only. To enable write access for a .img overlay use the -w / --writable flag with exec or run.

Overlay

Manage overlay writable ext3 images:

  • create: Create an image with a conda environment inside.

  • info: Display disk usage and filesystem statistics.

  • check: Verify filesystem integrity.

  • chown: Change ownership of files inside the image.

  • resize: Resize the image file.

  • export: Export a conda environment spec from an overlay.

Overlay Create

Create an ext3 .img with a conda environment inside. This is useful for creating writable conda environments.

Usage:

condatainer overlay create [OPTIONS] [NAME]

Options:

  • -s, --size [SIZE]: Size of the overlay image (default: 10G). Supports units like 20G, 2048M.

  • -t, --type [TYPE]: Overlay profile: small, balanced, or large (default: balanced).

  • -f, --file [FILE]: Initialize with a Conda environment file (.yml or .yaml).

  • --fakeroot: Create image compatible with fakeroot (owned by root, must use with --fakeroot later).

  • --sparse: Create a sparse image file (no pre-allocation). (Short form: -S available on the o shortcut only.)

  • --no-tmp: Create the overlay directly at the target path instead of staging at a local tmp directory first. By default CondaTainer creates the image on a fast local filesystem (e.g. /tmp) and moves it to the destination once ready β€” this is significantly faster on HPC network filesystems (LustreFS). Use --no-tmp only when the target is already on local storage.

  • -- [packages...] [-c channel...]: Initialize with inline conda packages instead of a YAML file. Mutually exclusive with -f. Channels passed with -c are saved in .condarc inside the overlay for reuse by mm-install, mm-update, and mm-search. Default channels when no -c is given: conda-forge + bioconda. conda-forge is always appended if not explicitly listed.

  • NAME: Name of the overlay image (env.img by default if not specified).

Examples:

# Create a 20GB overlay img with a custom name
condatainer overlay create -s 20G my_analysis_env

# Create with a specific profile (small/balanced/large)
condatainer overlay create -t large data_env.img

# o is a shortcut for 'overlay create'
condatainer o -f environment.yml project_env.img

# Create a fakeroot-compatible sparse overlay
condatainer o --fakeroot --sparse

# Initialize with inline conda packages (faster than writing a YAML)
condatainer o -- python=3.11 numpy pandas
condatainer o myenv.img -- python=3.11

# Specify channels with -c; conda-forge is always appended if not listed
condatainer o -- pytorch torchvision torchaudio pytorch-cuda=12.4 -c pytorch -c nvidia

Then you can use the mm-<operation> helper commands to create/install/update/remove conda packages inside the writable container.

# install more packages (uses channels saved during creation)
mm-install numpy pandas
mm-install pytorch-cuda=12.4 -c pytorch -c nvidia  # extra channels merged with saved ones

# manage channels
mm-channels get              # show configured channels
mm-channels prepend pytorch  # move/add channel to highest priority
mm-channels append bioconda  # move/add channel to lowest priority
mm-channels remove nvidia    # remove a channel

# search for packages (uses saved channels)
mm-search pytorch-cuda

# pin the package version
mm-pin numpy # after installation
mm-pin -d numpy # to unpin
mm-pin -l # list pinned packages

# update packages
mm-update

# remove packages
mm-remove pandas

# list installed packages
mm-list

# clean all conda cache
mm-clean -ay

# export the env
mm-export --no-builds > my_env.yaml

Overlay Info

Alias for condatainer info scoped to ext3 .img overlays. Produces identical output.

condatainer overlay info [image_path]

condatainer overlay info env.img
# same as:
condatainer info env.img

Overlay Check

Verify filesystem integrity of an ext3 .img overlay.

Usage:

condatainer overlay check [image_path]

Options:

  • -f, --force: Force check even if filesystem appears clean.

Example:

condatainer overlay check env.img
condatainer overlay check -f env.img

Overlay Chown

Change the ownership of files inside an ext3 .img overlay. This is useful when sharing a writable overlay with other users: the recipient can reset ownership to their UID/GID so files are writable with their account.

Usage:

condatainer overlay chown [OPTIONS] [image]

Options:

  • -u, --uid UID : Set the owner UID (default: current user’s UID).

  • -g, --gid GID : Set the group GID (default: current user’s GID).

  • --root : Set UID/GID to 0 (root); overrides -u and -g.

  • -p, --path PATH : Path inside the overlay to change (can specify multiple, default: /).

  • image : Path to the overlay img file.

Examples:

# Set ownership inside env.img to the current user (entire overlay by default)
condatainer overlay chown env.img

# Explicitly set UID and GID
condatainer overlay chown -u 1001 -g 1001 env.img

# Set ownership to root
condatainer overlay chown --root env.img

# Set entire image to root
condatainer overlay chown --root -p / env.img

# Chown only /ext3 path
condatainer overlay chown -p /ext3 env.img

# Chown multiple specific paths
condatainer overlay chown -p /ext3 -p /data env.img

Overlay Resize

Resize an ext3 .img overlay to a new size. Supports both expanding and shrinking.

Usage:

condatainer overlay resize -s SIZE [image]

Options:

  • -s, --size SIZE : New size for the overlay image (e.g., 20G, 2048M). Required.

  • image : Path to the overlay img file.

Examples:

# Resize env.img to 20GB
condatainer overlay resize -s 20G env.img

Overlay Export

Export a Micromamba/Conda environment spec from an overlay. The output is printed to stdout and can be redirected to a YAML or text file.

  • For .img workspace overlays the environment prefix is /ext3/env.

  • For .sqf module overlays the environment prefix is /cnt/<name>/<version>.

Requires conda-meta to be present at the expected prefix β€” i.e., the overlay must contain an actual conda environment.

Usage:

condatainer overlay export [OPTIONS] [overlay_path]

Options:

  • -e, --explicit: Use explicit (URL-pinned) format.

  • --no-md5: Disable MD5 checksums in explicit output.

  • --no-build, --no-builds: Strip build strings from the spec.

  • --channel-subdir: Include channel and subdir in the spec.

  • --from-history: Reconstruct spec from install history only.

  • --json: Output as JSON.

Examples:

# Export environment from a workspace overlay
condatainer overlay export env.img > environment.yml

# Export from a module overlay (sqf)
condatainer overlay export salmon/1.10.2.sqf > environment.yml

# Export without build strings (more portable)
condatainer overlay export env.img --no-builds > environment.yml

# Export as explicit (URL-pinned, fully reproducible)
condatainer overlay export env.img -e > explicit.txt

# Export from history (only user-requested packages)
condatainer overlay export env.img --from-history > minimal.yml

Create

Initialize and build a new CondaTainer SquashFS overlay. You can build from existing recipes (local/remote), a Conda environment file, or a remote container source.

Usage:

condatainer create [OPTIONS] [packages...]

Aliases: install, i

Options:

  • -n, --name [NAME]: Custom name for the resulting overlay file. If used, all specified packages are bundled into one overlay.

  • -p, --prefix [PATH]: Custom prefix path for the overlay file. When -f is used, this can be omitted β€” the prefix is inferred from the file name.

  • -f, --file [FILE]: Path to definition file (.yaml, .sh, .def).

  • -s, --source [URI]: Remote source URI (e.g., docker://ubuntu:22.04).

  • -c, --channel [CHANNEL]: Conda channel to use, overriding config channels. Repeatable: -c conda-forge -c bioconda. Also accepts channel-annotated packages like bioconda::star=2.7.11b directly as package arguments (see below).

  • --temp-size [SIZE]: Size of temporary overlay (default: 20G).

  • --block-size [SIZE]: SquashFS block size for app/env/external overlays (e.g. 128k, 512k; default: 128k). Must be a power of two between 4k and 1m.

  • --data-block-size [SIZE]: SquashFS block size for data/reference overlays (e.g. 512k, 1m; default: 1m). Must be a power of two between 4k and 1m.

  • --use-tmp-overlay: Use a temporary ext3 overlay during builds instead of host directories. Equivalent to setting build.use_tmp_overlay = true in config.

  • -u, --update: Rebuild overlays even if they already exist (atomic .new swap). Useful for refreshing a package to the latest version.

  • --remote: Remote build scripts take precedence over local.

  • packages: List of packages to install (e.g., bcftools/1.22 or samtools=1.10 or grch38/genome/gencode). Supports conda channel annotations: bioconda::star=2.7.11b (version required in default mode; optional with -n/-p).

Compression Options:

  • --lz4: Use LZ4 compression (default).

  • --zstd-fast: Use Zstandard compression level 3.

  • --zstd-medium: Use Zstandard compression level 8.

  • --zstd: Use Zstandard compression level 14.

  • --zstd-high: Use Zstandard compression level 19.

  • --gzip: Use Gzip compression.

Build Modes:

  • Default: Each package gets its own .sqf via the build system. Build script lookup is skipped when a package uses channel annotation (bioconda::star=2.7.11b).

  • --name: Create a single .sqf with multiple packages bundled together.

  • --prefix + packages: Create a conda env .sqf at a custom path, like conda create -p.

  • --file only: Create .sqf from external source file; prefix inferred from file name (e.g. condatainer create -f r-collect.sh β†’ r-collect.sqf).

  • --prefix + --file: Create .sqf from external source file at a custom path.

  • --source: Create .sqf from a remote container source URI.

System level Examples

Conda environment:

# Single package module overlay (conda fallback)
condatainer create bcftools/1.22

# Multiple package module overlays at once
condatainer create samtools/1.16 bcftools/1.15

# Create a conda env sqf with packages at a custom path (like conda create -p)
condatainer create python=3.11 numpy -p /scratch/myenv

# Create from a yaml file (prefix inferred from filename)
condatainer create -f environment.yml

# Create from a yaml file with a custom prefix
condatainer create -p my_analysis_env -f environment.yml

# Create a custom env with multiple packages bundled together
condatainer create -n tools samtools=1.16 bcftools=1.15

# Rebuild an existing conda overlay (force update)
condatainer create -n nvim nvim nodejs -u

# Override channels for this build only
condatainer create python=3.11 -n myenv -c conda-forge -c bioconda

# Channel-annotated package: skips build script lookup, goes direct to conda
# (version required in default mode)
condatainer create bioconda::star=2.7.11b

# Channel annotation in bundled env (version optional with -n/-p)
condatainer create -n rnaseq bioconda::star bioconda::salmon=1.10.0

Build script:

# App overlay via build script
condatainer create cellranger/9.0.1

# Bare package name is expanded using default_distro (e.g. ubuntu24/igv)
condatainer create igv

# Data overlay
condatainer create grch38/gtf-gencode/47

# From a remote container source
condatainer create --source docker://ubuntu:22.04 -n myubuntu

# Template script β€” prompts for each placeholder interactively
condatainer create grch38/salmon-gencode
# [CNT] Placeholder template: grch38/salmon-gencode
# [CNT] Salmon GRCh38 GENCODE{gencode_version} index for transcript quantification
#   Target: grch38/salmon/{salmon_version}/gencode{gencode_version}
#   salmon_version [1.0.0-1.11.4] (default: 1.11.4): 1.10.2
#   gencode_version [23-49] (default: 49):
#   β†’ Creating grch38/salmon/1.10.2/gencode49

# Template script β€” skip prompts by specifying the resolved target name directly
condatainer create grch38/salmon/1.10.2/gencode49

Features:

  • Automatic Fetching: If a build script is not found locally, CondaTainer attempts to fetch it from the remote repository.

  • Conda Fallback: If no build script exists, CondaTainer attempts to create the module by installing the package with the requested name and version from conda-forge or bioconda.

  • Metadata Parsing: Parses #ENV and #ENVNOTE tags from build scripts to inject environment variables and help text into the generated modulefile.

  • Template Resolution: If the name matches a template script (#PL: / #TARGET:), CondaTainer prompts for each placeholder interactively, then builds the resolved concrete overlay. You can also bypass prompts by specifying the resolved target name directly.

Project level Examples

Create a read-only overlay with a Conda environment using a Conda YAML file. The prefix can be omitted β€” it is inferred from the file name.

# Prefix inferred: generates environment.sqf in the current directory
condatainer create -f environment.yml

# Custom prefix: generates my_project_env.sqf
condatainer create -p my_project_env -f environment.yml

Create a read-only overlay using a custom Apptainer definition file. See Custom OS Overlays for more details.

condatainer create -f custom_def.def

Create a read-only overlay using a shell script that installs packages. See Custom Build Script using Build Scripts for more details.

condatainer create -f install_packages.sh

Exit Codes (script and job-submission behavior) βš οΈοƒ

CondaTainer uses specific exit codes so automation and downstream tooling can detect special states:

  • 0 β€” Success (all requested builds completed locally or nothing to do)

  • 1 β€” Generic error (build failures, runtime errors, or other fatal errors)

  • 2 β€” Wrong or missing arguments (misuse of command, invalid flag values)

  • 3 β€” Jobs submitted to scheduler β€” overlays will be created asynchronously by scheduler jobs

Commands that may return exit code 3 when scheduler jobs were submitted include:

  • condatainer create ...

  • condatainer check -a ... (auto-install missing deps)

  • condatainer avail -i ... (install from search results)

Quick example for shell scripts that detect the job-submitted state:

condatainer create samtools/1.22
if [ $? -eq 3 ]; then
  echo "Jobs submitted to scheduler β€” overlays will be created asynchronously"
  # Optionally: exit 0 or wait/monitor jobs here
fi

Note: When exit code 3 is returned, CondaTainer prints a message showing the number of jobs submitted (and can be extended to emit JSON or write job metadata for automation).

Disabling Job Submission:

# Run locally even with scheduler specs
condatainer --local run analysis.sh

# Or set in config
condatainer config set submit_job false

Exec

Execute a command inside a containerized environment using explicit overlay specifications.

Usage:

condatainer exec [flags] [command...]

Options:

  • -o, --overlay [OVERLAY]: Overlay file to mount (can be used multiple times).

  • -w, --writable: Mount .img overlays as writable (default: read-only).

  • -b, --base-image [PATH]: Base image to use instead of default.

  • -f, --fakeroot: Run container with fakeroot privileges.

  • --env [KEY=VALUE]: Set environment variable inside the container (can be used multiple times).

  • --bind [HOST:CONTAINER]: Bind mount path into the container (can be used multiple times).

Features:

  • Use -o/--overlay to explicitly specify overlays.

  • All positional arguments are treated as commands.

  • Read-only by default for .img overlays (use -w for writable).

  • Defaults to bash if no command specified.

Environment Variables (inside container):

  • IN_CONDATAINER=1: Set inside the container.

  • CNT_CONDA_PREFIX: Path to the .img default conda path, if -w/--writable is used.

Examples:

# Run bash with samtools overlay
condatainer exec -o samtools/1.22

# Run samtools command with overlay
condatainer exec -o samtools/1.22 samtools view file.bam

# Use writable .img overlay
condatainer exec -w -o env.img bash

# Multiple overlays
condatainer exec -o samtools/1.22 -o bcftools/1.20 bash

# Set environment variables
condatainer exec --env MYVAR=value -o samtools/1.22 bash

# Bind mount directories
condatainer exec --bind /data:/mnt -o env.img bash

# Run with fakeroot privileges (short flag)
condatainer exec -f -o env.img bash

# Pass apptainer flags (use --flag=value format)
condatainer exec --nv --home=/custom -o samtools/1.22 python gpu_script.py

E (Quick Exec)

Quick shortcut for executing commands with overlays using simplified syntax.

Usage:

condatainer e [flags] [overlays...] [--] [command...]

Options:

  • -r, --read-only: Mount .img overlays as read-only (default: writable).

  • -n, --no-autoload: Disable autoloading env.img from current directory.

  • -b, --base-image [PATH]: Base image to use instead of default.

  • -f, --fakeroot: Run container with fakeroot privileges.

  • --env [KEY=VALUE]: Set environment variable inside the container (can be used multiple times).

  • --bind [HOST:CONTAINER]: Bind mount path into the container (can be used multiple times).

Key Differences from exec:

  • Overlays are positional arguments before --.

  • Commands go after --.

  • Writable by default (use -r for read-only).

  • Auto-loads env.img unless -n is specified.

  • Defaults to bash if no command specified.

Environment Variables (inside container):

  • IN_CONDATAINER=1: Set inside the container.

  • CNT_CONDA_PREFIX: Path to the .img default conda path (writable by default).

Examples:

# Auto-load env.img if present, run bash
condatainer e

# Multiple overlays
condatainer e samtools/1.22 bcftools/1.20

# Run specific command
condatainer e samtools/1.22 -- samtools view file.bam

# Read-only .img overlay
condatainer e -r env.img

# Disable env.img auto-loading
condatainer e -n samtools/1.22

# Set environment variables
condatainer e --env MYVAR=value samtools/1.22

# Bind mount directories
condatainer e --bind /data:/mnt env.img

# Run with fakeroot privileges (short flag)
condatainer e -f env.img

# Pass apptainer flags (use --flag=value format)
condatainer e --home=/custom samtools/1.22

Autoload and Shell Completion

  • Autoload local env images: When running condatainer e in a directory that contains env.img, CondaTainer will automatically mount it into the container and open an interactive shell. Use -n / --no-autoload to disable this behavior.

  • Enable shell completion: Generate and install the completion script for your shell. See the Completion section for details.

Instance

Manage persistent Apptainer instances that run in the background. Instances are useful for long-running services or when you need to execute multiple commands in the same containerized environment without restarting the container each time.

Key Features:

  • Persistent background containers

  • State preservation (environment variables, overlays, bind paths)

  • Multiple instances with unique names

  • Pattern-based operations (wildcards supported)

Instance Start

Start a named instance with specified overlays.

Usage:

condatainer instance start [flags] <name>

Options:

  • -o, --overlay [OVERLAY]: Overlay file to mount (can be used multiple times)

  • -w, --writable: Mount .img overlays as writable (default: read-only)

  • -b, --base-image [PATH]: Base image to use instead of default

  • -f, --fakeroot: Run instance with fakeroot privileges

  • --env [KEY=VALUE]: Set environment variable (can be used multiple times)

  • --bind [HOST:CONTAINER]: Bind mount path (can be used multiple times)

Examples:

# Start instance with multiple overlays
condatainer instance start -o samtools/1.22 -o bcftools/1.22 myinstance

# Start with writable .img overlay
condatainer instance start -w -o env.img data_analysis

# Pass apptainer flags
condatainer instance start --home=/custom -o samtools/1.22 pipeline1

State Preservation:

When you start an instance, CondaTainer saves the instance configuration (overlays, environment variables, bind paths) to a state file. This allows instance exec to automatically apply the same environment when executing commands in the instance.

Instance Stop

Stop one or more running instances.

Usage:

condatainer instance stop [flags] [name]

Options:

  • -a, --all: Stop all user’s instances

  • -F, --force: Force kill instance (may corrupt data)

  • -s, --signal [SIGNAL]: Signal to send to instance (e.g., SIGTERM, TERM, 15)

  • -t, --timeout [SECONDS]: Timeout before force kill (seconds; 0 = use apptainer default)

Examples:

# Stop a specific instance
condatainer instance stop myinstance

# Stop all instances matching pattern
condatainer instance stop mysql*

# Stop all instances
condatainer instance stop --all

# Custom timeout before force kill
condatainer instance stop --timeout 30 myinstance

State files are automatically cleaned up for stopped instances.

Instance List

List all running instances.

Usage:

condatainer instance list

Shows all active instances with their names and process information.

Instance Stats

Display resource usage statistics for a running instance.

Usage:

condatainer instance stats <name>

Example:

condatainer instance stats myinstance

Shows CPU, memory, and I/O statistics for the specified instance.

Instance Exec

Execute a command in a running instance.

Usage:

condatainer instance exec [flags] <name> <command> [args...]

Options:

  • --env [KEY=VALUE]: Set additional environment variables (can be used multiple times)

Features:

  • Commands run in the same environment as when the instance was started

  • Automatically applies saved environment variables from instance state

  • Overlays and bind paths from instance start are preserved

  • Defaults to bash if no command specified

  • Unknown apptainer flags can be passed using --flag=value format

Examples:

# Run a command in an instance
condatainer instance exec myinstance samtools view file.bam

# Open interactive shell (default)
condatainer instance exec myinstance

# Set additional environment variables
condatainer instance exec --env VAR1=val1 --env VAR2=val2 myinstance bash

# Pass apptainer flags
condatainer instance exec --home=/custom myinstance bash

State Restoration:

When you use instance exec, CondaTainer automatically loads the saved state from when the instance was started. This includes:

  • Environment variables (#ENV tags from overlays)

  • Overlay mount points

  • Bind paths

  • Base image configuration

Environment variables set during instance exec are added on top of the saved state, allowing you to override or add variables as needed.

Note: Apptainer’s native apptainer exec instance://name does not preserve environment variables from instance start. CondaTainer solves this by storing instance state and reapplying it during exec.

Instance Workflow Example

Here’s a complete workflow showing how to use instances:

# 1. Start an instance with your desired overlays and writable env
condatainer instance start -o xfce4 -o igv -o env.img -w desktop

# 2. Run multiple commands in the same instance
condatainer instance exec desktop websockify --web /usr/share/novnc ...
condatainer instance exec desktop vncserver :1 -geometry 1920x1080 -depth 24 ...
condatainer instance exec desktop igv

# 3. Check instance status
condatainer instance stats desktop

# 4. Stop the instance when done
condatainer instance stop desktop

Runtime (Check, Run)

Utilities for running scripts with automatic dependency handling via #DEP: tags. Parsing of module load / ml lines is disabled by default and can be enabled with --module or parse_module_load: true in config.

Check

Parses scripts for #DEP: tags and checks if the required overlays are installed.

Usage:

condatainer check <script|dir> [script|dir ...] [-a] [--module] [--remote]

Each argument can be:

  • A local .sh file path

  • A directory β€” all .sh files directly inside it are checked (non-recursive)

  • A package name (e.g., grch38/salmon/1.10.2/gencode49) resolved from local or remote build scripts

Options:

  • -a, --auto-install: Automatically attempt to build/install missing dependencies.

  • -i, --install: Alias for --auto-install.

  • --module: Also parse module load / ml lines as dependencies.

  • --remote: Remote build scripts take precedence over local when resolving package names.

Output:

Dependencies are grouped into two sections:

Module Overlays:
  βœ“ samtools/1.22
  βœ— bcftools/1.21

External Overlays:
  βœ“ src/overlay/r-env.sqf
  βœ— src/overlay/r-collect.sqf  (.yml found)
  βœ— src/overlay/custom.sqf     (.sh found, but has #DEP - create manually)

Auto-install (-a):

  • Module overlays: resolved via build scripts or conda, same as condatainer create.

  • External overlays: auto-created from the sibling source file if found and has no #DEP: tags.

    • .yml / .yaml β†’ conda environment

    • .def β†’ Apptainer build and extract the squashfs

    • .sh (no #DEP:) β†’ shell build (cannot have #DEP: tags)

Run

Executes a script inside the CondaTainer environment, mounting dependencies defined in the script. Autosolves dependencies based on #DEP: tags within the script.

condatainer run [OPTIONS] SCRIPT [SCRIPT_ARGS...]

Note: All options (-a, -o, --afterok, etc.) must appear before SCRIPT. Arguments after the script name are forwarded to the script.

Options:

  • -w, --writable, --writable-img: Make .img overlays writable (default: read-only).

  • -b, --base-image [PATH]: Use custom base image.

  • --module: Also parse module load / ml lines as dependencies.

  • -n, --name NAME: Override the job name shown in the scheduler queue (e.g. squeue). Takes priority over #SBATCH --job-name and similar directives.

  • -o, --output PATH: Override the job stdout path (creates parent directory if needed). Takes priority over scheduler stdout settings.

  • -e, --error PATH: Override the job stderr path. Takes priority over scheduler stderr settings.

  • --afterok IDS: Submit job that runs only if all listed jobs succeed. Colon-separated IDs: 123:456:789.

  • --afternotok IDS: Submit job that runs only if any listed job fails. Colon-separated IDs.

  • --afterany IDS: Submit job that runs after all listed jobs finish regardless of outcome. Colon-separated IDs.

  • -f, --fakeroot: Run with fakeroot privileges.

  • --bind HOST:CONTAINER: Bind mount a path into the container (repeatable).

  • --env KEY=VALUE: Set an environment variable inside the container (repeatable).

  • --dry-run: Preview what would be submitted without executing anything.

  • --array FILE: Input file for an array job β€” one subjob per line, tokens become positional args.

  • --array-limit N: Max concurrently running subjobs (0 = unlimited).

Resource override flags (apply on top of script scheduler directives; highest priority):

  • -c, --cpu INT: Override CPUs per task (e.g. 4).

  • -m, --mem STRING: Override memory per task (e.g. 4G, 8192M).

  • -t, --time STRING: Override walltime (e.g. 4d12h, 2h30m, 01:30:00).

  • -g, --gpu SPEC: Override GPUs per node. Formats: N (any type), TYPE:N, or TYPE (count=1). E.g. 1, a100:2, a100.

Script Tags:

Scripts can use special comment tags to declare dependencies and configure the container:

Tag

Description

#DEP: package/version

Declare a dependency overlay

#DEP: path.img

Declare a external overlay (.sqf and .img)

#CNT [args]

Additional arguments passed to condatainer

#SBATCH [args]

SLURM scheduler directives (auto-submit as job)

#PBS [args]

PBS scheduler directives (auto-submit as job)

#BSUB [args]

LSF scheduler directives (auto-submit as job)

Available #CNT arguments:

  • -w, --writable: Make .img overlays writable.

  • -b, --base-image PATH: Use custom base image.

  • --env KEY=VALUE: Set environment variable.

  • --bind HOST:CONTAINER: Bind mount path.

  • -f, --fakeroot: Run with fakeroot privileges.

Script Example:

#!/bin/bash
#DEP: bcftools/1.22
#CNT --writable
#CNT --env MYVAR=value
#CNT -f
bcftools view input.vcf | head

Scheduler Integration

If your script contains scheduler directives (#SBATCH, #PBS, or #BSUB), condatainer run will automatically submit it as a scheduler job instead of running it locally. HTCondor uses native .sub submit files instead of in-script directives.

Condition

Behavior

Already inside a running job or container

Always runs locally (no nested submission)

--local flag or submit_job: false in config

Always runs locally

Script has no scheduler specs

Runs locally (prints a note)

Script has #SBATCH/#PBS/#BSUB + scheduler available

Submits as a scheduler job

Script has scheduler specs but scheduler not found/available

Runs locally (prints a note)

Scheduler Script Example:

#!/bin/bash
#SBATCH --cpus-per-task=4
#SBATCH --mem=8G
#SBATCH --time=2:00:00
#DEP: samtools/1.22
#DEP: bcftools/1.22

samtools view -@ 4 input.bam | bcftools call -mv -o output.vcf

Install missing dependencies first:

condatainer check -a salmon_quant.sh

After all dependencies are installed, submit as a job:

condatainer run salmon_quant.sh

Log Files:

  • -o/-e CLI flags take highest priority β€” they override any #SBATCH --output/--error in the script

  • If no CLI flag, the path from the script directive (e.g., #SBATCH --output=...) is used

  • Otherwise, logs are written to the global logs directory (~/logs by default)

  • If only -o is set (no -e), stderr is merged into the same file

  • Job scripts are created in the same directory as the log file

Resource Override Examples:

# Override CPU/memory/time on top of script's #SBATCH directives
condatainer run -c 8 -m 32G -t 4h analysis.sh

# Override GPU spec (any GPU type, count 2)
condatainer run -g 2 gpu_job.sh

# Override with specific GPU type and count
condatainer run -g a100:4 gpu_job.sh

# GPU type only (count defaults to 1)
condatainer run -g h100 gpu_job.sh

Script Arguments

Anything after the script name is passed into the script as $1, $2, …

#!/bin/bash
#SBATCH --cpus-per-task=4
#SBATCH --mem=8G
#SBATCH --time=1:00:00
#DEP: samtools/1.22

# $1 = input BAM, $2 = output directory
mkdir -p "$2"
samtools sort -@ $NCPUS "$1" -o "$2/sorted.bam"

Submit with:

condatainer run sort.sh /data/raw/sample1.bam results/sample1/
# inside sort.sh: $1=/data/raw/sample1.bam  $2=results/sample1/

Array Jobs

Run the same script over a list of inputs with --array. Each non-empty line in the input file becomes one subjob; its space-separated tokens arrive as positional arguments ($1, $2, …) inside the script.

# samples.txt β€” one entry per line; tokens become $1, $2, ...
sample1 condition_A
sample2 condition_B
sample3 condition_C

# quant.sh β€” $1=sample name, $2=condition
salmon quant -i $SALMON_INDEX_DIR -p $NCPUS -l A \
  -r reads/${1}.fq -o quants/${1}_${2}/

condatainer run --array samples.txt quant.sh
condatainer run --array samples.txt --array-limit 4 quant.sh  # max 4 concurrent
condatainer run --dry-run --array samples.txt quant.sh        # preview args

Mixing array args with extra CLI args:

When extra args are provided after the script name alongside --array, array line tokens are prepended before the CLI args inside the script:

condatainer run --array samples.txt quant.sh genome_version
# line "sample1 treated" β†’ $1=sample1  $2=treated  $3=genome_version

Rules:

  • All non-empty lines must have the same number of shell-split tokens (quoted strings count as one).

  • Blank lines are flagged on --dry-run and block submission β€” remove them before submitting.

  • Per-subjob logs go to {logsDir}/{jobname}_{idx}_{tag}.log where {tag} is all args joined, with non-alphanumeric characters replaced by _, capped at 20 characters.

  • Array jobs always require scheduler submission (cannot run locally).

Job Chaining

All [CNT] messages go to stderr, only job ID is printed to stdout, so you can capture it for downstream job submission.

TRIM=$(condatainer run trim.sh sample1)
ALIGN=$(condatainer run --afterok "$TRIM" align.sh sample1)
condatainer run --afterok "$ALIGN" quant.sh sample1

Three dependency flags are available:

Flag

Runs when upstream job…

--afterok IDS

Succeeds

--afternotok IDS

Fails

--afterany IDS

Finishes (any outcome)

Multiple job IDs can be passed as a colon-separated list (e.g. --afterok 123:456:789). All three flags can be combined in a single submission.

Array Jobs + Chaining

--array and --afterok can be combined: each stage submits an array job and waits for the previous stage to succeed before starting. A final single job can collect results after all subjobs complete.

# Stage 1: trim all samples (no dependency)
JOB=$(condatainer run --array samples.txt --array-limit 10 trim.sh)

# Stage 2: align β€” waits for ALL trim subjobs to finish
JOB=$(condatainer run --array samples.txt --array-limit 10 --afterok "$JOB" align.sh)

# Stage 3: quant β€” waits for ALL align subjobs to finish
JOB=$(condatainer run --array samples.txt --array-limit 10 --afterok "$JOB" quant.sh)

# Final: single job collecting results β€” waits for ALL quant subjobs
condatainer run --afterok "$JOB" collect_results.sh samples.txt

Each array stage fans out across all samples in parallel (up to the concurrency limit), and --afterok ensures the next stage only starts once every subjob in the previous stage has succeeded. Use --afterany instead to proceed even if some subjobs failed.

If you don’t like this all-or-nothing behavior, you can chain individual subjobs.

declare -a FINAL_JOBS

while IFS= read -r line; do
  if [[ -z "$line" ]]; then continue; fi  # skip blank lines
  TRIM=$(condatainer run trim.sh $line)
  ALIGN=$(condatainer run --afterok "$TRIM" align.sh $line)
  QUANT=$(condatainer run --afterok "$ALIGN" quant.sh $line)
  FINAL_JOBS+=("$QUANT")
done < samples.txt
JOB_IDS=$(IFS=:; echo "${FINAL_JOBS[*]}")
condatainer run --afterok "$JOB_IDS" collect_results.sh samples.txt

Do not quote the line variable in the loop if you want the tokens to be split into separate arguments.

Usable ENV

When running scripts with scheduler directives, the following environment variables are automatically available inside the container:

Variable

Description

Example

NNODES

Number of compute nodes

2

NTASKS_PER_NODE

Number of MPI tasks per node

4

NTASKS

Total number of MPI tasks

8

NCPUS

CPUs per task

4

MEM

Memory per task in MB

8192

MEM_GB

Memory per task in GB

8

Priority Order (Scheduler ENV > Script > Default):

Environment variables are resolved with the following priority:

  1. Scheduler ENV (highest priority) β€” Environment variables from the scheduler (e.g., $SLURM_CPUS_PER_TASK)

  2. Script β€” Scheduler directives in the script (#SBATCH, #PBS, #BSUB)

  3. Default (lowest priority) β€” Built-in default values in config (scheduler.*)

MPI Auto-Detection

When a scheduler script requests more than one task (--ntasks-per-node, --ntasks, or PBS/LSF equivalents), condatainer run automatically detects the host MPI and wraps the job command with mpiexec:

Detection: mpiexec must be available in PATH at submission time. If it is not found, condatainer run exits with an error.

Generated job command:

mpiexec condatainer run script.sh

MPI Script Example:

#!/bin/bash
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=3
#SBATCH --mem=1G
#SBATCH --time=00:30:00

#DEP: mpi.img

python my_mpi_script.py

Run with:

# ml openmpi # or other MPI module to ensure mpiexec is in PATH
condatainer run mpi_job.sh

CondaTainer detects ntasks = 6, finds mpiexec, and submits:

mpiexec condatainer run mpi_job.sh

Each MPI rank launches its own container, all sharing the same MPI communicator via SLURM’s process management interface.

Important

You need to have the same major and minor version of OpenMPI installed inside the container as on the host.

ml av openmpi
# openmpi/4.1.5
condatainer e mpi.img -- mm-install mpi4py openmpi=4.1 -y

CondaTainer is compatible with module systems

CondaTainer can scan your script for module load or ml commands and mount the corresponding overlays automatically. This is disabled by default; enable it with --module or by setting parse_module_load: true in your config.

Example:

#!/bin/bash
module load bcftools/1.22
bcftools --version

Use --module with check or run to handle these dependencies:

# Install missing dependencies (including module load lines)
condatainer check my_script.sh --module -a

# Run the script with automatic dependency resolution
condatainer run my_script.sh --module

To enable it permanently:

condatainer config set parse_module_load true

Info

Display detailed metadata about an installed overlay or an external overlay file. Accepts an installed overlay name (name/version) or a direct file path (.sqf / .img).

Usage:

condatainer info [OVERLAY]

Examples:

condatainer info samtools/1.22
condatainer info env.img
condatainer info ./ubuntu--22.04.sqf

SquashFS (.sqf) output

Section

Fields

File

Name, Path, file Size, Type (OS Overlay / Module Overlay / Bundle Overlay, Read-Only), Created timestamp

SquashFS

Compression algorithm (with level if set), Block Size, Inode count, Fragment count, Deduplication flag

Mount

/cnt/<name>/<version> β€” shown for Module and Bundle Overlays

Environment

Variables from the .env sidecar file, with inline #ENVNOTE annotations

ext3 (.img) output

Section

Fields

File

Name, Path, file Size, Type (Workspace Overlay, Writable; sparse images also show actual on-disk size)

Filesystem

Format, State, Block Size, Created, Modified, Last Mounted

Ownership

Inner UID/GID of files inside the image (or root for fakeroot-compatible images)

Disk Usage

Used / Total (%), Reserved blocks, Free

Inode Usage

Used / Total (%), Free

Mount

/ext3/env

Environment

Variables from the .env sidecar file, with inline #ENVNOTE annotations

Helper

Download and manage small helper scripts stored in the helper-scripts/ folder inside the CondaTainer repository.

Note

Helper commands are not available inside a container or a scheduler job (except --path and --list).

Usage:

condatainer helper [FLAGS] [SCRIPT_NAME] [SCRIPT_ARGS...]

Options:

  • -u, --update: Update helper scripts from remote metadata.

  • -p, --path: Show all helper script search paths and the writable directory. If a SCRIPT_NAME is given, print the absolute path of that specific helper script and exit.

  • -l, --list: List available helper scripts with their descriptions (from #WHATIS tags).

  • SCRIPT_NAME: Name of the helper script to run (optional).

  • SCRIPT_ARGS...: Remaining arguments are passed directly to the helper script when running it.

Examples

# List all available helper scripts with descriptions
condatainer helper --list

# Print helper script search paths
condatainer helper --path

# Print path to a specific helper script
condatainer helper --path code-server

# Download/Update all helper scripts (auto selects sbatch or headless based on availability)
condatainer helper --update
# Force update headless scripts version
condatainer --local helper --update

# Run a helper script with arguments
condatainer helper code-server -p 18230

Config

Manage CondaTainer configuration settings.

Config Show

Display current configuration including file paths, settings, and environment variable overrides. (including available distros)

condatainer config show [--path]

  • --path: Show only the config file path.

Config Get

Get a specific configuration value.

condatainer config get <key>

Examples:

condatainer config get apptainer_bin
condatainer config get build.ncpus
condatainer config get submit_job

Config Set

Set a scalar configuration value and save to the active config file. For a full list of supported keys, see the Configuration manual.

condatainer config set <key> <value>

Examples:

condatainer config set apptainer_bin /usr/bin/apptainer
condatainer config set submit_job false
condatainer config set build.ncpus 8
condatainer config set build.time 4h

Time formats: 2h, 30m, 1h30m, 90s, 02:00:00, HH:MM:SS

Config Append / Prepend / Remove

Manage array config keys (extra_image_dirs, extra_build_dirs, extra_helper_dirs, extra_scripts_links, channels) from the CLI.

condatainer config append  <key> <value>
condatainer config prepend <key> <value>
condatainer config remove  <key> <value>

  • append β€” add a value to the end of the array (lower priority).

  • prepend β€” add a value to the beginning of the array (higher priority).

  • remove β€” delete all occurrences of a value from the array.

Examples:

# Explicit image directory (search-only shared store)
condatainer config append extra_image_dirs /shared/lab/images:ro

# Explicit image directory (writable personal store)
condatainer config append extra_image_dirs /fast/scratch/images

# Add an institutional scripts source (takes priority over the default)
condatainer config prepend extra_scripts_links https://raw.githubusercontent.com/MyOrg/my-scripts/main

# Remove entries
condatainer config remove extra_image_dirs /shared/lab/images:ro

# Show result
condatainer config show
condatainer config get extra_image_dirs

Config Init

Create a config file with auto-detected defaults.

condatainer config init [-l|--location user|root|extra-root|system]

  • -l, --location: Config location (default: auto-detect).

Auto-detects:

  • Apptainer binary

  • Scheduler binary

  • Compression support (zstd vs lz4)

Config Paths

Show data search paths for images, build scripts, and helper scripts.

condatainer config paths

Config Validate

Validate the current configuration.

condatainer config validate

Checks:

  • Apptainer binary accessibility

  • Scheduler binary accessibility

  • Build configuration (CPUs > 0, Memory > 0)

  • default_distro is one of the supported distro names

Configuration Priority

Configuration is loaded in the following order (highest to lowest priority):

  1. Command-line flags

  2. Environment variables (CNT_*)

  3. User config file (~/.config/condatainer/config.yaml)

  4. Extra-root config ($CNT_EXTRA_ROOT/config.yaml, group/lab layer)

  5. App-root config ($CNT_ROOT/config.yaml or <install-dir>/config.yaml)

  6. System config (/etc/condatainer/config.yaml)

  7. Built-in defaults

Configuration File Example

See the Configuration manual for a full reference of all available keys.

# Binary paths (scheduler type is auto-detected from binary)
apptainer_bin: /usr/bin/apptainer
scheduler_bin: /usr/bin/sbatch

# Submission settings
submit_job: true

# Base OS distro: ubuntu20, ubuntu22, or ubuntu24 (default: ubuntu24)
default_distro: ubuntu24

# Remote build/helper script source (base URL)
scripts_link: https://raw.githubusercontent.com/Justype/cnt-scripts/main

# Additional remote sources (higher priority than scripts_link; first entry wins on conflict)
# extra_scripts_links:
#   - https://raw.githubusercontent.com/MyOrg/my-scripts/main

# Days to cache remote metadata (default: 7, set 0 to always fetch live)
metadata_cache_ttl: 7

# Build configuration
build:
  ncpus: 8
  mem: 16g
  time: 4h
  # compress_args options (gzip, lz4, zstd, zstd-fast, zstd-medium, zstd-high)
  compress_args: "-comp zstd -Xcompression-level 8"
# Explicit image directories (:ro = search-only, :rw = writable default)
extra_image_dirs:
  - /shared/lab/images:ro
  - /fast/scratch/images
# For a group/lab root with standard layout, set in module file:
# export CNT_EXTRA_ROOT=/project/shared/condatainer

Scheduler

Display information about the configured job scheduler.

Usage:

condatainer scheduler [FLAGS]

Options:

  • -p, --partitions: Show per-partition resource limits.

  • -Q, --queue: Show per-queue resource limits (alias for -p).

  • --cpu: Show only CPU-only partitions (no GPUs); automatically enables -p.

  • --gpu: Show only GPU partitions; automatically enables -p.

Output includes:

  • Scheduler type (SLURM, PBS, LSF, HTCondor)

  • Binary path

  • Version

  • Availability status

  • Max resource limits across all partitions (CPUs, memory, time)

  • GPUs (type, total)

Examples:

# Show scheduler information
condatainer scheduler

# Show per-partition/queue resource limits
condatainer scheduler -p

# Show only GPU partitions
condatainer scheduler --gpu

# Show per-partition limits for CPU-only partitions
condatainer scheduler -p --cpu

Update

Refreshes the remote build script and helper script metadata caches, or updates the base image.

Usage:

condatainer update [FLAGS]

Options:

  • --build: Refresh the build script metadata cache.

  • --helper: Refresh the helper script metadata cache.

  • --base: Update the base Apptainer image only.

By default (no flags), both --build and --helper are enabled.

Features:

  • Prints each remote URL as it fetches metadata.

  • Downloads and caches metadata locally per remote URL (default TTL: 7 days).

  • Cached metadata is reused by avail and create without a network round-trip.

  • Supports multiple remote sources (extra_scripts_links); each gets its own cache file.

  • Removes cache files for remotes no longer configured (orphan cleanup).

Examples:

# Refresh build + helper metadata (default)
condatainer update

# Build script metadata only
condatainer update --build

# Helper script metadata only
condatainer update --helper

# Update the base image only
condatainer update --base

Self-Update

Updates the CondaTainer binary to the latest version from GitHub releases.

Usage:

condatainer self-update [FLAGS]

Options:

  • -y, --yes: Skip confirmation prompt and auto-update.

  • -f, --force: Force update even if already on the latest version.

  • --dev: Include pre-release versions.

  • --base: Update the base image only, without updating the condatainer binary.

Features:

  • Downloads latest binary from GitHub releases.

  • Detects current OS and architecture.

  • Compares versions before updating.

  • Automatically updates the base image when the minor or major version changes.

  • If the base image update fails, prints a warning and suggests running condatainer self-update --base to retry later.

  • Supports symlink resolution.

Examples:

# Update to latest stable version
condatainer self-update

# Update without confirmation
condatainer self-update --yes

# Force update even if already on latest version
condatainer self-update -f

# Include pre-release versions
condatainer self-update --dev

# Update the base image only (without updating the binary)
condatainer self-update --base

Proxy

SSH tunnel + dual-protocol (HTTP CONNECT + SOCKS5) proxy so compute node jobs can reach the internet through the login node.

The daemon automatically selects the best available SSH tunnel method:

  1. Go SSH library β€” pure Go, uses hostbased auth (no user keys needed), SSH agent, or key files

  2. ssh -D Unix socket β€” delegates to the system ssh binary

  3. ssh -D TCP port β€” fallback for older OpenSSH (< 6.7)

condatainer proxy start|stop|status|show

Two modes

Shared

Per-job

Started on

Login node

Compute node (inside job)

Bind

0.0.0.0:PORT

127.0.0.1:PORT

Scope

All compute nodes

This node only

PID file

~/.local/share/condatainer/proxy.pid (NFS)

$SLURM_TMPDIR/cnt-$USER/proxy.pid (local)

Lifetime

Until stopped / logout

Until job ends (tmpdir cleaned by scheduler)

Start

condatainer proxy start

condatainer proxy start --via <login-node>

proxy start

condatainer proxy start [--host HOST] [--via VIA] [--port PORT]

Flag

Description

--host HOST

Run the daemon on HOST instead of the current node (login node only; delegates via SSH).

--via VIA

SSH server to tunnel through. Default: current node (shared mode); required for per-job mode inside a job.

--port PORT

Listen port. Default: OS-assigned.

Shared mode attempts loginctl enable-linger so the daemon survives logout. A warning is printed if it fails.

condatainer proxy start                 # shared, OS picks port
condatainer proxy start --port 1080     # shared, fixed port
condatainer proxy start --host login02  # shared, delegate to login02
condatainer proxy start --via gateway   # shared, custom SSH gateway
condatainer proxy start --via login01   # per-job (inside a job)

proxy stop / status / show

condatainer proxy stop      # kill shared proxy (SSH to other login node if needed)
condatainer proxy status    # check per-job then shared; clean stale PID files
condatainer proxy show      # print active URL (per-job first); empty if none

export ALL_PROXY=$(condatainer proxy show)

Automatic injection (inside jobs)

When running inside a scheduler job, condatainer auto-injects the proxy URL into:

  • container env β€” http_proxy, https_proxy, HTTP_PROXY, HTTPS_PROXY, all_proxy, ALL_PROXY

  • condatainer’s HTTP clients β€” script fetching and metadata downloads use the proxy transport directly

Lookup order: per-job proxy β†’ shared proxy.

The proxy port speaks both HTTP CONNECT (http_proxy) and SOCKS5 (all_proxy) β€” compatible with all tools (curl, wget, pip, micromamba, etc.).

proxy_perjob config option

When proxy_perjob: true, condatainer injects condatainer proxy start --via <login-node> at the top of every generated scheduler script (build, run, helper jobs). The per-job proxy starts automatically on the compute node before the job body runs.

proxy_perjob: true   # default: false

CNT_PROXY_PERJOB=1 enables it for a single invocation without changing the config file.

Completion

Generates shell completion scripts for CondaTainer.

Usage:

condatainer completion [SHELL]

  • SHELL: Specify the shell type (bash, zsh, or fish). If not provided, auto-detected from $SHELL.

Bash:

Add the following to your ~/.bashrc:

source <(condatainer completion bash)

Zsh:

Add the following to your ~/.zshrc:

source <(condatainer completion zsh)
# Or generate to fpath:
# condatainer completion zsh > "${fpath[1]}/_condatainer"

Fish:

Run the following command:

condatainer completion fish | source
# Or save to config:
# condatainer completion fish > ~/.config/fish/completions/condatainer.fish