SciTeX Container

Unified container management for Apptainer and Docker

Full Documentation · pip install scitex-container

---

Problem and Solution

#	Problem	Solution
1	"Reproducible" containers drift -- Dockerfile builds a different image each time because apt-get install python3 floats	Versioned SIF -- scitex-container build pins the image content hash; switch-version 2.19.5 is an atomic symlink flip
2	Rollback requires docker tags + manual surgery -- something breaks in prod; reverting to yesterday's container is 15 minutes of yak-shaving	rollback is one command -- previous active SIF restored; sandbox state preserved
3	Paper "env" is pip freeze -- useless without the python version, OS libs, CUDA driver	env_snapshot() -- full reproducibility capsule: container tag + pip freeze + conda env + apt packages + git commits, serialized as a single file for manuscript attachments

Problem

Research computing environments depend on containers (Apptainer/Singularity for High-Performance Computing (HPC), Docker for cloud services), yet managing them involves disparate tools, manual version tracking, and no simple way to verify reproducibility. Switching between container runtimes, managing sandbox development, and keeping host-side dependencies aligned with container expectations are recurring pain points.

Solution

scitex-container provides a single Python package with four interfaces — Python API, Command-Line Interface (CLI), Model Context Protocol (MCP) server, and Skills — to manage Apptainer and Docker containers uniformly. It handles building, versioning, sandboxing, host-package verification, and environment snapshots for reproducibility, all through one consistent interface.

Installation

Requires Python >= 3.10.

pip install scitex-container

With MCP server support (for AI agent integration):

pip install scitex-container[mcp]

Full installation:

pip install scitex-container[all]

Quick Start

# Unified status dashboard
scitex-container status

# Build Apptainer SIF from definition file
scitex-container build --def-name scitex-final

# Version management
scitex-container list
scitex-container switch 2.19.5
scitex-container rollback

# Show all commands
scitex-container --help-recursive

Four Interfaces

Python API

import scitex_container

# Apptainer container management
scitex_container.apptainer.build(def_name="scitex-final", sandbox=True)
scitex_container.apptainer.list_versions(containers_dir="/opt/containers")
scitex_container.apptainer.switch_version("2.19.5", containers_dir="/opt/containers")
scitex_container.apptainer.rollback(containers_dir="/opt/containers")

# Host package management
scitex_container.host.check_packages()

# Docker operations
scitex_container.docker.rebuild(env="prod")
scitex_container.docker.restart(env="prod")

# Environment reproducibility snapshot
snapshot = scitex_container.env_snapshot()

Verification API

from pathlib import Path
import scitex_container

# Verify container integrity
result = scitex_container.apptainer.verify(sif_path="/opt/containers/scitex-final.sif")
# Returns: {sif, def_origin, pip_lock, dpkg_lock, overall}

# Command builder for scitex-cloud terminal integration
args = scitex_container.apptainer.build_exec_args(
    container_path="/opt/containers/scitex-final.sif",
    username="user01",
    host_user_dir=Path("/data/users/user01"),
    host_project_dir=Path("/data/projects/proj01"),
    project_slug="proj01",
    texlive_prefix="/usr",
)

CLI Commands

scitex-container status                 # Unified dashboard
scitex-container build scitex-final     # Build SIF
scitex-container list                   # List versions
scitex-container switch 2.19.5         # Switch version
scitex-container rollback              # Revert to previous
scitex-container verify                # Verify SIF integrity
scitex-container env-snapshot          # Reproducibility snapshot

Sandbox Operations

scitex-container sandbox create --sif scitex-final.sif
scitex-container sandbox maintain --sandbox scitex-sandbox/

Host Package Management

scitex-container host install          # Install TeX Live + ImageMagick
scitex-container host check            # Verify host packages
scitex-container host mounts           # Show configured bind mounts

Docker Operations

scitex-container docker rebuild        # Rebuild Compose services
scitex-container docker restart        # Restart services

MCP Server

scitex-container exposes an MCP server so AI agents (Claude, etc.) can manage containers autonomously.

# Start MCP server
scitex-container-mcp

# Diagnostics and tool listing
scitex-container mcp doctor
scitex-container mcp list-tools -vv

Tool	Description
status	Unified container/host status dashboard
build	Build SIF from definition file
list	List available container versions
switch	Switch active container version
rollback	Roll back to previous version
sandbox_create	Create writable sandbox from SIF
docker_rebuild	Rebuild Docker Compose services
host_install	Install host-side packages
env_snapshot	Capture reproducibility snapshot
verify	Verify SIF integrity against lock files

Skills — for AI Agent Discovery

Skills provide workflow-oriented guides that AI agents query to discover capabilities and usage patterns.

scitex-container skills list              # List available skill pages
scitex-container skills get SKILL         # Show main skill page
scitex-dev skills export --package scitex-container  # Export to Claude Code

Skill	Content
quick-start	Install and first-use examples
python-api	Full Python API with signatures
cli-reference	CLI commands reference
mcp-tools	MCP tools for AI agents
environment	Environment variables

Part of SciTeX

scitex-container is part of SciTeX. When used inside the orchestrator package scitex, container operations integrate with the broader ecosystem — for example, scitex-clew can consume environment snapshots produced by scitex-container to track reproducibility provenance across experiments.

import scitex_container

# Capture snapshot for Clew integration
snapshot = scitex_container.env_snapshot()
# snapshot includes: container version, SIF hash, lock files, host packages

The SciTeX ecosystem follows the Four Freedoms for researchers, inspired by the Free Software Definition:

• Freedom 0 — Run your research without restriction
• Freedom 1 — Study and adapt the tools you depend on
• Freedom 2 — Share your work and its infrastructure with colleagues
• Freedom 3 — Improve the tools and share improvements with the community

---

AGPL-3.0 — because research infrastructure deserves the same freedoms as the software it runs on.