# scitex-agent-container - Declarative AI Agent Lifecycle Management

scitex-agent-container is a declarative YAML-based framework for defining, managing, and orchestrating AI coding agent instances. Part of SciTeX.

Getting Started

- Installation
  - From PyPI
  - From Source
  - Requirements
- Quickstart
- Templates and Examples
  - Pattern Templates
  - Instantiating a Template
  - Examples
- Status and Hook Integration
  - Rich Status
  - Claude Code Hook Integration
  - Zero Coupling Design

Architecture & Reference

- How sac works
  - Launch flow
  - What each piece does
  - Restart / health
  - See also
- YAML Spec Reference (v3)
  - Quick links
  - Top-level shape
  - Field reference
  - Lifetime / session selection
  - `kind: AgentProxy` — HTTP forwarder agents
  - Examples
- Talking to a Running Agent
  - 1. A2A sidecar — `POST /v1/sac/agents/<name>/turn`
  - 2. CLI — `sac agents send` / `sac agents tail`
  - 3. `sac listen` — host-level HTTP control plane
  - Cross-host: `sac --on <peer>`
  - Forwarding to external A2A (`kind: AgentProxy`)
  - Picking a transport
  - See also
- Container Isolation in sac
  - Apptainer’s default leak paths (10 categories)
  - sac’s hardened defaults
  - Roadmap for sac’s isolation surface
  - One-line summary for papers / READMEs
  - See also
- Configuration and Runtime Directories
  - Layout
  - Configuration cascade
- Claude Code credential & settings files
  - Files
  - Fleet hosts
  - What NOT to emit
  - Safe metadata fields (whitelist)
- Apptainer Images
  - Builtin layers
  - Build
  - Sandbox / freeze workflow
  - Pinning a custom image

Ecosystem

- sac and orochi
  - Architecture
  - Responsibility split
  - How orochi consumes sac
  - Standalone use
  - Live instance

API Reference

- scitex_agent_container API Reference
  - Config
  - Runtimes

## Key Features

- YAML Definitions: Declarative agent configuration via YAML files

- Lifecycle Management: Create, start, stop, and destroy agent instances

- Rich Status: `status --json` emits pane state, workspace files, hook-captured tool history, and `last_tool_at` / `last_mcp_tool_at` functional-heartbeat shortcuts for dashboards

- Claude Code Hook Integration: `hook-event` ingests Claude Code `PreToolUse` / `PostToolUse` / `UserPromptSubmit` / `Stop` events into a per-agent ring buffer

- Zero Coupling: No knowledge of any downstream orchestrator; consumers (e.g. scitex-orochi) wrap `status --json` to post to their own hubs

## Quick Example

    # Create and launch an agent from YAML definition
    scitex-agent-container start my-agent.yaml

    # List running agents
    scitex-agent-container list

    # Inspect live pane state / rich status
    scitex-agent-container show-status my-agent --json

    # Stop an agent
    scitex-agent-container stop my-agent

# Indices and tables

- Index

- Module Index

- Search Page