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

Architecture

scitex-container/
├── src/scitex_container/
│   ├── __init__.py              # apptainer, docker, host, env_snapshot + MCP-parity re-exports
│   ├── apptainer/
│   │   ├── _build.py            # build SIF / sandbox from .def (pinned hash)
│   │   ├── _config.py           # reproducible-build config (retain, require_verified)
│   │   ├── _freeze.py           # extract pip/dpkg/npm lock files from built SIF
│   │   ├── _lockgen.py          # lock capture, locked-def generation, version-set comparison
│   │   ├── _reproducible.py     # self-verifying reproducible-build round-trip + use-time verify gate
│   │   ├── _store.py            # timestamped (sif, lock) artifact store
│   │   ├── _versioning.py       # list / switch / rollback / deploy SIF versions
│   │   ├── _sandbox.py          # sandbox create / maintain / update / to-sif
│   │   ├── _sandbox_versioning.py # sandbox list / switch / rollback / cleanup
│   │   ├── _status.py           # list available containers and build status
│   │   ├── _utils.py            # shared utilities (detect container cmd, find containers dir)
│   │   └── _verify.py           # SIF + lock-file integrity
│   ├── docker/                  # rebuild / restart compose services
│   │   ├── _compose.py          # compose helpers
│   │   └── _mounts.py           # bind mount helpers
│   ├── host/                    # TeX Live, ImageMagick, bind mounts
│   │   ├── _mounts.py           # mount configuration
│   │   └── _packages.py         # install / check host packages
│   ├── _snapshot.py             # env_snapshot(): container + host + git + lock files
│   ├── _mcp/                    # MCP handler implementations
│   │   └── handlers.py          # async handlers: build, list, switch, rollback, deploy, etc.
│   ├── _cli/                    # scitex-container CLI entrypoint
│   │   ├── __init__.py          # main click group with all subcommands
│   │   ├── _apptainer.py        # apptainer sub-commands (build, freeze, list, switch, etc.)
│   │   ├── _docker.py           # docker sub-commands (rebuild, restart)
│   │   ├── _host.py             # host sub-commands (install, check, show-mounts)
│   │   ├── _sandbox.py          # sandbox sub-commands (create, maintain, list, switch, etc.)
│   │   ├── _status.py           # show-status dashboard
│   │   ├── _env_snapshot.py     # save-env-snapshot command
│   │   ├── _mcp.py              # mcp sub-commands (start, doctor, list-tools, install)
│   │   └── _skills.py           # skills list / get / install
│   ├── _compat.py               # compatibility shim for optional scitex-dev dependency
│   ├── mcp_server.py            # MCP server (optional, via fastmcp)
│   └── _skills/scitex-container/# bundled agent skill files
└── 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 show-status

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

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

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

Four Interfaces

import scitex_container as ctr

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

# Reproducible build round-trip (rough build + freeze + lock + verify)
result = ctr.apptainer.build_reproducible(
    layer="sac-base",
    root="/opt/containers",
    def_path="recipes/apptainer-base.def",
)
print(f"Verified: {result.verified}")

# Use-time verify gate
status = ctr.apptainer.check_verified("/opt/containers/sac-base.sif")
print(f"State: {status.state}")

# Host package management
ctr.host.check_packages()

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

# Environment reproducibility snapshot
snapshot = ctr.env_snapshot()

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}

# Full reproducible round-trip
rt_result = scitex_container.apptainer.build_reproducible(
    layer="sac-base",
    root="/opt/containers",
    def_name="apptainer-base",
    verify=True,
    keep=False,
)
# rt_result.verified is True/None; rt_result.diff shows any drift

# Use-time gate
status = scitex_container.apptainer.check_verified(
    "/opt/containers/sac-base.sif",
    require_verified=True,
)

scitex-container show-status              # Unified dashboard
scitex-container apptainer build           # Build SIF from .def
scitex-container apptainer freeze          # Extract pip/dpkg/npm lock files
scitex-container apptainer list            # List versioned SIFs
scitex-container apptainer switch VERSION  # Switch active SIF version
scitex-container apptainer rollback        # Revert to previous version
scitex-container apptainer deploy          # Copy active SIF to production
scitex-container apptainer clean           # Remove old versions
scitex-container apptainer verify          # Verify SIF integrity
scitex-container save-env-snapshot         # Reproducibility snapshot

scitex-container sandbox create --source scitex-final.sif
scitex-container sandbox maintain -s scitex-sandbox/ -- apt-get update
scitex-container sandbox list -d ./containers
scitex-container sandbox switch 20260301_120000
scitex-container sandbox rollback
scitex-container sandbox clean --keep 3
scitex-container sandbox update -s scitex-sandbox/

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

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

# Start MCP server
scitex-container-mcp

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

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

Demo

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

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.