scitex-agent-container 0.3.1

Declarative YAML-based framework for defining, managing, and orchestrating AI coding agent instances

scitex-agent-container

Declarative YAML-based AI agent lifecycle management

pip install scitex-agent-container

---

Problem

Managing AI coding agents (Claude Code, Cursor, Aider) in production requires manual script-writing, environment setup, and process monitoring for each agent instance. Scaling from one agent to a fleet means duplicating fragile shell scripts with no health checks, restart policies, or lifecycle management.

Solution

scitex-agent-container provides declarative YAML definitions that fully specify an agent -- runtime, model, channels, environment, health checks -- started with a single command:

• YAML-first configuration -- one file defines runtime, model, watchdog, health checks, restart policy, and hooks
• Pluggable runtimes -- run agents bare on screen, inside Docker, or inside Apptainer (HPC clusters)
• Built-in watchdog -- auto-responds to Claude Code's permission prompts so agents run unattended
• Health checks and restart policies -- agents self-heal with configurable backoff

YAML manifest --> scitex-agent-container start --> screen session
                                                   + watchdog
                                                   + health monitor
                                                   + restart policy

Installation

Requires Python >= 3.10.

pip install scitex-agent-container

# With Telegram integration
pip install scitex-agent-container[telegram]

# Development
pip install scitex-agent-container[dev]

Quickstart

1. Write a YAML manifest:

apiVersion: cld-agent/v1
kind: Agent
metadata:
  name: telegram-master
  labels:
    role: telegram
    team: core
spec:
  runtime: claude-code
  model: opus[1m]
  workdir: ~/proj

  claude:
    channels:
      - plugin:telegram@claude-plugins-official
    flags:
      - --dangerously-skip-permissions
    session: continue

  env:
    CLAUDE_AGENT_ROLE: telegram
    CLAUDE_AGENT_ID: telegram-master

  screen:
    name: cld-telegram

  watchdog:
    enabled: true
    interval: 1.5
    responses:
      y_n: "1"
      y_y_n: "2"
      waiting: "/speak-and-call"

  health:
    enabled: true
    interval: 30
    method: screen-alive

  restart:
    policy: on-failure
    max_retries: 3
    backoff:
      initial: 30
      max: 300
      multiplier: 2

2. Start and monitor:

scitex-agent-container start config/examples/telegram-master.yaml
scitex-agent-container status telegram-master
scitex-agent-container logs telegram-master -n 100
scitex-agent-container attach telegram-master   # Ctrl-A D to detach

Four Interfaces

Python API

from scitex_agent_container import (
    AgentConfig, load_config, validate_config,
    agent_start, agent_stop, agent_restart, agent_status, agent_logs,
    Registry,
)

config = load_config("agent.yaml")      # Parse YAML manifest
agent_start("agent.yaml")               # Launch agent
info = agent_status("telegram-master")   # Query status
agent_stop("telegram-master")            # Stop agent
agent_restart("telegram-master")         # Restart agent
output = agent_logs("telegram-master")   # Read logs
registry = Registry()                    # Access agent registry

CLI Commands

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

# Lifecycle
scitex-agent-container start <config.yaml>       # Start an agent
scitex-agent-container stop <name>               # Stop an agent
scitex-agent-container restart <name>            # Restart an agent
scitex-agent-container attach <name>             # Attach to screen session

# Inspection
scitex-agent-container status [name] [--json]    # Show agent status
scitex-agent-container list [--json]             # List all agents
scitex-agent-container ps [--json]               # Alias for list
scitex-agent-container logs <name> [-n LINES]    # Show recent output
scitex-agent-container health <name> [--json]    # Run health check

# Configuration
scitex-agent-container validate <config.yaml>    # Validate YAML config
scitex-agent-container build [--runtime docker|apptainer]

# Maintenance
scitex-agent-container cleanup                   # Remove stale entries
scitex-agent-container list-python-apis [-v]     # List public API tree
scitex-agent-container version                   # Show version

MCP Server -- for AI Agents

Not yet implemented. Planned for a future release.

Skills -- for AI Agent Discovery

Skills are planned for a future release. They will be available under _skills/ and via the CLI.

Part of SciTeX

scitex-agent-container is part of SciTeX. It depends on scitex-container for container runtime abstractions and is used by scitex-orochi for multi-machine agent orchestration.

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.

---