scitex-container 0.2.1

Unified container management for Apptainer and Docker

SciTeX Container

Unified container management for Apptainer/Singularity and Docker — versioned SIFs, atomic switch/rollback, and reproducible env snapshots.

Full Documentation · uv pip install scitex-container[all]

---

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

Architecture

scitex-container/
├── src/scitex_container/
│   ├── __init__.py              # apptainer, docker, host, env_snapshot
│   ├── apptainer/
│   │   ├── _build.py            # build SIF from def file (pinned hash)
│   │   ├── _versions.py         # list / switch / rollback (atomic symlink)
│   │   ├── _verify.py           # SIF + lock-file integrity
│   │   └── _exec.py             # build_exec_args for cloud terminal
│   ├── docker/                  # rebuild / restart compose services
│   ├── host/                    # TeX Live, ImageMagick, bind mounts
│   ├── _snapshot.py             # env_snapshot(): pip + conda + apt + git
│   ├── _cli/                    # scitex-container entrypoint
│   └── _mcp_tools/              # MCP server (opt-in)
└── tests/

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

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

Demo

sequenceDiagram
    participant U as user
    participant SC as scitex-container
    participant FS as /opt/containers
    U->>SC: build --def-name scitex-final
    SC->>FS: scitex-final-2.19.6.sif (pinned)
    U->>SC: switch 2.19.5
    SC->>FS: active.sif -> scitex-final-2.19.5.sif
    U->>SC: rollback
    SC->>FS: active.sif -> scitex-final-2.19.6.sif
    U->>SC: env-snapshot
    SC-->>U: snapshot.json (SIF hash + pip + conda + apt + git)

Part of SciTeX

scitex-container is part of SciTeX. Install via the umbrella with pip install scitex[container] to use as scitex.container (Python) or scitex container ... (CLI).

import scitex_container

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

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

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