scitex_agent_container API Reference

Top-level package surface re-exported from scitex_agent_container. Use scitex-agent-container list-python-apis for the authoritative runtime enumeration.

SciTeX Agent Container – Declarative agent management.

Provides a YAML-based framework for defining, managing, and orchestrating AI coding agent instances across container runtimes.

Public surface — CLI-tree-shaped noun submodules:

import scitex_agent_container as sac

sac.agent.list()                  # `sac agent list`
sac.agent.start("head-nas")       # `sac agent start head-nas`
sac.db.query(table="instances")   # `sac db query --table=instances`
sac.host.list()                   # `sac host list`
sac.skills.get("02_quick-start")  # `sac skills get 02_quick-start`

Each noun submodule (agent, db, host, image, template, account, skills, mcp) re-exports its verbs under bare names that mirror the CLI subcommand tree. The same function objects power both the Python API and the MCP server (per scitex MCP §6 parity).

Lifecycle helpers that take a shared Registry instance live at scitex_agent_container._lifecycle.lifecycle for callers that need them. The submodule verbs go through the CLI for JSON-friendly input/output.

Config

YAML config loading and validation for agent definitions.

Public API:

AgentConfig, load_config, validate_config, resolve_config ContainerSpec, ClaudeSpec, HealthSpec, WatchdogSpec, RestartSpec, SkillsSpec, StartupCommand

RemoteSpec and the spec.remote field were deleted in WI-6 (handoff §6, 2026-05-20). Cross-host placement is via spec.host; the old SSH-dispatch path is retired.

class scitex_agent_container.config.AgentConfig(name, runtime='apptainer', image='', model='sonnet', workdir='', python_venv='', env=<factory>, env_files=<factory>, screen_name='', labels=<factory>, container=<factory>, claude=<factory>, health=<factory>, watchdog=<factory>, restart=<factory>, autonomous=<factory>, apptainer=<factory>, hooks=<factory>, listen=<factory>, extensions=<factory>, skills=<factory>, context_management=<factory>, startup_commands=<factory>, startup_prompts=<factory>, mcp_servers=<factory>, multiplexer='tmux', hosts_spec=<factory>, scheduling=<factory>, config_path='', mounts=<factory>, user='', a2a=<factory>, comms=<factory>, lineage=<factory>, kind='Agent', proxy=None, to_home='./to_home')

Bases: object

Parsed agent configuration from a YAML definition file.

name: str

runtime: str = 'apptainer'

image: str = ''

model: str = 'sonnet'

workdir: str = ''

python_venv: str = ''

env: dict[str, str]

env_files: list[str]

screen_name: str = ''

labels: dict[str, str]

container: ContainerSpec

claude: ClaudeSpec

health: HealthSpec

watchdog: WatchdogSpec

restart: RestartSpec

autonomous: AutonomousSpec

apptainer: ApptainerSpec

hooks: dict[str, list[str]]

listen: list[ListenPort]

extensions: Dict[str, Any]

skills: SkillsSpec

context_management: ContextManagementConfig

startup_commands: list[StartupCommand]

__init__(name, runtime='apptainer', image='', model='sonnet', workdir='', python_venv='', env=<factory>, env_files=<factory>, screen_name='', labels=<factory>, container=<factory>, claude=<factory>, health=<factory>, watchdog=<factory>, restart=<factory>, autonomous=<factory>, apptainer=<factory>, hooks=<factory>, listen=<factory>, extensions=<factory>, skills=<factory>, context_management=<factory>, startup_commands=<factory>, startup_prompts=<factory>, mcp_servers=<factory>, multiplexer='tmux', hosts_spec=<factory>, scheduling=<factory>, config_path='', mounts=<factory>, user='', a2a=<factory>, comms=<factory>, lineage=<factory>, kind='Agent', proxy=None, to_home='./to_home')

startup_prompts: list[str]

mcp_servers: dict[str, dict]

multiplexer: str = 'tmux'

hosts_spec: HostsSpec

scheduling: SchedulingSpec

config_path: str = ''

mounts: list[dict]

user: str = ''

a2a: A2ASpec

comms: CommsSpec

lineage: LineageSpec

kind: str = 'Agent'

proxy: Any = None

to_home: str = './to_home'

property expanded_workdir: str

class scitex_agent_container.config.ClaudeSpec(model='', channels=<factory>, flags=<factory>, raw_options=<factory>, session='continue', continue_max_age_minutes=None, resume_id='', auto_accept=True, account='', provider=None)

Bases: object

model: str = ''

channels: list[str]

flags: list[str]

raw_options: dict

session: str = 'continue'

continue_max_age_minutes: int | None = None

resume_id: str = ''

auto_accept: bool = True

account: str = ''

provider: ProviderSpec | None = None

__init__(model='', channels=<factory>, flags=<factory>, raw_options=<factory>, session='continue', continue_max_age_minutes=None, resume_id='', auto_accept=True, account='', provider=None)

class scitex_agent_container.config.ContainerSpec(runtime='none', image='scitex-agent-container:latest', volumes=<factory>, network='host', mount_host_claude=False)

Bases: object

runtime: str = 'none'

image: str = 'scitex-agent-container:latest'

volumes: list[str]

network: str = 'host'

mount_host_claude: bool = False

__init__(runtime='none', image='scitex-agent-container:latest', volumes=<factory>, network='host', mount_host_claude=False)

class scitex_agent_container.config.ContextManagementConfig(trigger_at_percent=70.0, strategy='noop', warn_before_n_checks=0, check_interval_seconds=300, state_file='~/.scitex/agent-container/state/<agent>.json')

Bases: object

Context-lifecycle policy for an agent.

Defaults mirror strategy="noop" so absence of the context_management block preserves existing behavior (sensor disabled).

trigger_at_percent: float = 70.0

strategy: str = 'noop'

warn_before_n_checks: int = 0

check_interval_seconds: int = 300

state_file: str = '~/.scitex/agent-container/state/<agent>.json'

property enabled: bool

__init__(trigger_at_percent=70.0, strategy='noop', warn_before_n_checks=0, check_interval_seconds=300, state_file='~/.scitex/agent-container/state/<agent>.json')

class scitex_agent_container.config.HealthSpec(enabled=False, interval=30, timeout=5, method='multiplexer-alive')

Bases: object

enabled: bool = False

interval: int = 30

timeout: int = 5

method: str = 'multiplexer-alive'

__init__(enabled=False, interval=30, timeout=5, method='multiplexer-alive')

class scitex_agent_container.config.HookSpec(pre_start=<factory>, post_start=<factory>, pre_stop=<factory>, post_stop=<factory>, on_compact=<factory>, on_restart=<factory>, on_diff=<factory>)

Bases: object

All hook points supported by the container.

Each entry is a list of opaque commands — shell strings or http(s) URLs. The container executes them fire-and-forget; errors are logged but never raised to the caller. Absent keys default to empty lists (feature disabled).

pre_start: list[str]

post_start: list[str]

pre_stop: list[str]

post_stop: list[str]

on_compact: list[str]

on_restart: list[str]

on_diff: list[str]

counts()

Return type:

dict[str, int]

__init__(pre_start=<factory>, post_start=<factory>, pre_stop=<factory>, post_stop=<factory>, on_compact=<factory>, on_restart=<factory>, on_diff=<factory>)

class scitex_agent_container.config.HostsSpec(host='', hosts=<factory>)

Bases: object

Where an agent should run, in either singleton or multi-instance form.

Mutually exclusive — exactly one of host or hosts may be set:

• host (singular) — exactly one instance runs:

  • empty / absent: local singleton (runs wherever sac is invoked)

  • string: pinned to that host

  • list: priority order; first available host wins (fallback chain)

• hosts (plural) — multiple instances run, one per host:

  • “all”: one per fleet host (replaces the old per-host mode)

  • list of host names: one per listed host (subset)

Validator (in _validation.py) enforces mutual exclusion + types. Loader composes effective ids: hosts triggers the <name>-<HOST> suffix; host keeps the bare name.

host: str | list[str] = ''

hosts: str | list[str]

__init__(host='', hosts=<factory>)

class scitex_agent_container.config.ListenPort(port=0, proto='tcp', path='', name='', owner='')

Bases: object

Declaration of a port/socket an external tool binds on behalf of an agent.

The container NEVER binds these — it just validates the shape and echoes them in status --json so orchestrators can see what sidecars are expected to exist. owner is free-form (e.g. "orochi") to identify the plugin that actually listens.

port: int = 0

proto: str = 'tcp'

path: str = ''

name: str = ''

owner: str = ''

__init__(port=0, proto='tcp', path='', name='', owner='')

class scitex_agent_container.config.ProviderSpec(base_url='', auth_token_env='')

Bases: object

Vendor-agnostic backend override for the Claude SDK session.

When set under spec.claude.provider, the agent’s SDK session talks to an Anthropic-SDK-compatible backend OTHER than Anthropic (DeepSeek, a self-hosted gateway, etc.) using a never-expiring, login-free API key instead of Anthropic OAuth. Lets bulk fleet work run on a cheap backend without burning Max-plan quota.

The runtime injects three env vars into the container at start (see runtimes/_apptainer_provider.py):

• ANTHROPIC_BASE_URL ← base_url

• SAC_ANTHROPIC_API_KEY ← the host value of $<auth_token_env> (bridged to ANTHROPIC_API_KEY for the SDK by sac’s existing auth handoff). Fails loud at start if the env var is unset.

• CLAUDE_CONFIG_DIR ← a clean per-agent dir — the conflict-breaker so the OAuth .credentials.json bind cannot win (apptainer --env is last-wins).

The model id is the provider’s own (e.g. deepseek-chat); the claude-* regex in config._validation is relaxed whenever a provider is declared.

Mutually exclusive with ClaudeSpec.account (OAuth pin) — an API-key backend needs no OAuth, so declaring both is a config error the runtime rejects loudly.

base_url: str = ''

Anthropic-compatible base URL, e.g. https://api.deepseek.com/anthropic. Required when the provider block is present.

__init__(base_url='', auth_token_env='')

auth_token_env: str = ''

NAME of the host env var holding the API key (e.g. DEEPSEEK_API_KEY) — NOT the key value. The operator sources the secret file; sac reads the env var’s value at start and never logs it. Required when the provider block is present.

class scitex_agent_container.config.ProxySpec(upstream='', trust='untrusted', redact=<factory>, timeout_s=30.0)

Bases: object

Configuration for kind: AgentProxy agents.

upstream: str = ''

REQUIRED. Full URL to the upstream A2A AgentCard endpoint. Either an explicit .well-known path or a base URL (we’ll fetch <base>/.well-known/agent-card.json if a base is given).

trust: str = 'untrusted'

One of untrusted (default — operator must opt in to anything more permissive), local-mesh (peers on the same private network you control), trusted (cryptographically verified — reserved for future mTLS work). Surfaced on the AgentCard’s x-scitex-agent-container.trust field.

redact: list[str]

Substring tokens; any inbound text field containing one is refused with HTTP 400. Cheap defense-in-depth against accidentally forwarding secrets to an untrusted upstream — NOT a substitute for proper output filtering at the source.

__init__(upstream='', trust='untrusted', redact=<factory>, timeout_s=30.0)

timeout_s: float = 30.0

Per-turn upstream HTTP timeout. Forwarded turns that take longer than this surface as 504 to the caller.

class scitex_agent_container.config.RestartSpec(policy='never', max_retries=3, backoff_initial=30, backoff_max=300, backoff_multiplier=2)

Bases: object

policy: str = 'never'

max_retries: int = 3

backoff_initial: int = 30

backoff_max: int = 300

backoff_multiplier: int = 2

__init__(policy='never', max_retries=3, backoff_initial=30, backoff_max=300, backoff_multiplier=2)

class scitex_agent_container.config.SchedulingSpec(mode='per-host', preferred_host='', fallback_hosts=<factory>)

Bases: object

Fleet-wide scheduling policy for an agent (shared-host layout).

mode controls effective-id composition and launch-skip behavior:

• per-host (default): agent is started on every host that runs sac agent start <name>; the effective id is <metadata.name>-<HOST> unless the name already ends with -<HOST>.

• singleton: exactly one instance fleet-wide. The effective id stays as the bare <metadata.name>. Only launched on preferred-host; on other hosts the launch is a no-op.

fallback-hosts is recorded for observability but not acted on automatically — manual failover today.

mode: str = 'per-host'

preferred_host: str = ''

fallback_hosts: list[str]

__init__(mode='per-host', preferred_host='', fallback_hosts=<factory>)

class scitex_agent_container.config.SkillsSpec(required=<factory>, available=<factory>, injection_mode='at-import', match_by=<factory>, match_style='exact')

Bases: object

required: list[str]

available: list[str]

injection_mode: str = 'at-import'

match_by: list[str]

match_style: str = 'exact'

__init__(required=<factory>, available=<factory>, injection_mode='at-import', match_by=<factory>, match_style='exact')

class scitex_agent_container.config.StartupCommand(delay=0, command='')

Bases: object

delay: int = 0

command: str = ''

__init__(delay=0, command='')

class scitex_agent_container.config.WatchdogSpec(enabled=False, interval=1.5, resp_y_n='1', resp_y_y_n='2', resp_waiting='/speak-and-call')

Bases: object

enabled: bool = False

interval: float = 1.5

resp_y_n: str = '1'

resp_y_y_n: str = '2'

resp_waiting: str = '/speak-and-call'

__init__(enabled=False, interval=1.5, resp_y_n='1', resp_y_y_n='2', resp_waiting='/speak-and-call')

scitex_agent_container.config.compose_effective_name(raw_name, hosts_spec, hostname)

Return the effective agent id given dir-derived name + host/hosts + host.

Return type:

str

Rules:

• If hosts: is set (multi-instance), append -<hostname> so each host’s instance has a unique id. Idempotent — names that already end with -<hostname> are not double-suffixed.

• Otherwise (host: set, or both empty = local singleton): keep the bare raw_name. Singleton id stays stable across hosts.

scitex_agent_container.config.load_config(path)

Load and validate a YAML config, returning an AgentConfig.

Only scitex-agent-container/v3 is accepted. Older apiVersions (v1, v2) raise loud validation errors — no backward compatibility.

Return type:

AgentConfig

scitex_agent_container.config.resolve_config(name_or_path)

Resolve agent name or path to a config file path.

Every agent lives in its own directory; the config file is always named spec.yaml (or spec.yml). The flat-form <base>/<name>.yaml and the legacy <base>/<name>/<name>.yaml are no longer accepted — sac is dir-as-SSoT.

Search order for short names (no slash, no .yaml/.yml suffix):

0. Project-local — first .scitex/agent-container/agents/ found walking upward from cwd. Highest priority so checked-in test agents and CI fixtures override globals.

1. ~/.scitex/agent-container/agents/<name>/spec.yaml (sac install root).

2. $SCITEX_AGENT_CONTAINER_YAML_DIRS (colon-separated extra dirs, each searched as <dir>/<name>/spec.yaml). Plugin port for downstream orchestrators to inject extra paths without sac knowing about them.

Pass an explicit path (with / or .yaml/.yml) to bypass the search entirely.

Return type:

str

scitex_agent_container.config.resolve_hostname(gethostname=<built-in function gethostname>)

Return the canonical host label for this machine.

Resolution order (first non-empty wins):

1. SCITEX_AGENT_CONTAINER_HOSTNAME env var (manual override).

2. SCITEX_AGENT_CONTAINER_HOSTNAME env var.

3. hostname_aliases[short hostname] from shared/config.yaml or ~/.scitex/agent-container/config.yaml.

4. socket.gethostname() short form (identity fallback).

Parameters:

gethostname (Callable[[], str]) – Callable returning the raw OS hostname. Defaults to socket.gethostname (production). Tests inject a callable returning a fixed string instead of patching socket.

Raises:

RuntimeError – If none of the sources produces a non-empty value. This should be practically impossible (gethostname() returns something on any configured box) but is handled loudly rather than returning the empty string.

Return type:

str

scitex_agent_container.config.substitute_hostnames(obj, hostname=None)

Recursively walk a dict/list/str and substitute hostname placeholders.

Non-string leaves (int, bool, None) are returned unchanged. The walk is pure-functional — the input is not mutated; a new structure is returned.

Parameters:

• obj (Any) – YAML-parsed structure (dict/list/scalar).

• hostname (str | None) – Override hostname (for tests). If None, calls resolve_hostname().

Return type:

Any

scitex_agent_container.config.validate_config(path)

Validate a config file and return list of errors (empty = valid).

Return type:

list[str]

Runtimes

Modular TUI prompt detection and response for Claude Code.

Each prompt handler defines: - name: identifier for logging - detect(content) -> bool: whether this prompt is visible - respond(send_keys) -> None: keystrokes to accept the prompt - priority: lower = checked first (default 10)

Add new handlers by appending to PROMPT_HANDLERS or calling register_prompt().

class scitex_agent_container.runtimes.prompts.PromptHandler(name, detect, keys=<factory>, priority=10)

Bases: object

A single TUI prompt detector and responder.

name: str

detect: Callable[[str], bool]

keys: list[str]

priority: int = 10

__init__(name, detect, keys=<factory>, priority=10)

scitex_agent_container.runtimes.prompts._detect_bypass_permissions(content)

Bypass Permissions mode prompt with radio selector.

Return type:

bool

Matches:

“1. No, exit” “2. Yes, I accept” “Bypass Permissions” “Enter to confirm”

scitex_agent_container.runtimes.prompts._detect_dev_channels(content)

Development channels loading confirmation.

Return type:

bool

Matches:

“1. I am using this for local development” “2. Exit” “development channels” or “dangerously-load-development-channels” “Enter to confirm”

scitex_agent_container.runtimes.prompts._detect_thinking_effort(content)

Thinking effort level selector.

Return type:

bool

Matches:

“1. * Medium (recommended)” or similar “thinking” in various casings “Enter to confirm”

scitex_agent_container.runtimes.prompts._detect_skip_permissions_yn(content)

Legacy y/n text prompt for skip-permissions (older Claude Code).

Matches text-based y/n prompts without radio selector.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_mcp_json_edit(content)

Permission prompt when Claude tries to edit .mcp.json (runtime).

Matches “1. Yes” / “1. Proceed” / “1. Allow” + “.mcp.json” + “Enter to confirm”.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_press_enter_continue(content)

Generic ‘Press Enter to continue’ runtime pause (context-window warning, etc).

Uses a strict last-5-lines window to avoid scrollback false positives (per pane-state-patterns.md: classify against last 5 visible lines only). Excluded: active tool calls and numbered radio selectors.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_file_trust(content)

‘Do you trust the files in this folder?’ prompt (first-run or new cwd).

May appear when –dangerously-skip-permissions was not propagated to a subshell. Matches the LEGACY y/n text variant; the new radio-selector variant is handled by _detect_file_trust_radio().

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_file_trust_radio(content)

Radio-selector variant of the file-trust prompt.

Claude Code (>= ~2.1.x) asks “Is this a project you created or one you trust?” with numbered options instead of the legacy y/n text prompt. Appears on the first launch in any un-trusted workdir — including every throwaway tempdir the Haiku integration test uses.

Matches the exact option strings to avoid firing on the bypass-permissions dialog (which also says “Enter to confirm”).

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_external_imports(content)

External CLAUDE.md file imports prompt.

Appears when CLAUDE.md (or .claude/CLAUDE.md) contains @<absolute-path> imports pointing OUTSIDE the agent’s workdir. Triggered by the at-import skill-injection mode (sac PR #74) when skills live in ~/.claude/skills/ or the package source trees rather than the workspace itself.

Return type:

bool

Matches:

“Allow external CLAUDE.md file imports?” “1. Yes, allow external imports” “Enter to confirm”

scitex_agent_container.runtimes.prompts._detect_login_method(content)

First-run login-method picker on a fresh HOME.

Appears when Claude Code can’t find OAuth credentials at ~/.claude/.credentials.json. Even with ANTHROPIC_API_KEY set in env, the 2.1.x CLI still asks which auth mode to use before it checks the env var. Blocks startup until dismissed.

Matches the exact option strings to avoid false positives on any user message that happens to say “login method”.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_theme_selection(content)

First-run theme selection prompt.

Appears only on a fresh HOME (no ~/.claude/ saved theme). On dev machines it never shows, but in CI (a clean ubuntu VM) this is the first thing Claude Code asks. Blocks every downstream startup prompt until acknowledged.

Matches the radio variant: “Choose the text style…” + numbered options starting with “1. Auto (match terminal)”.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_compose_pending_unsent(content)

Detect unsent text sitting in the Claude Code compose buffer.

The classifier in agent_meta._classify_pane_state matches ❯[ \t]+\S (non-whitespace after the prompt marker on the same line), meaning the user has typed something but not yet pressed Enter. We mirror that pattern here so the prompts system can submit it via a plain Enter keystroke.

Excluded: lines that are just the decorative separator below an empty prompt — those contain only whitespace after ❯.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_done(content)

Check if claude is at the main input prompt (all TUI prompts done).

The status bar shows “bypass permissions” when ready.

Return type:

bool

scitex_agent_container.runtimes.prompts.register_prompt(handler)

Add a custom prompt handler to the registry.

Return type:

None

scitex_agent_container.runtimes.prompts.detect_and_respond(content, accepted, send_keys_fn)

Check content against all handlers, respond to the first match.

Parameters:

• content (str) – Captured pane content.

• accepted (set[str]) – Set of already-accepted prompt names.

• send_keys_fn (Callable[..., None]) – Callable to send keystrokes (e.g., mux.send_keys).

Return type:

str | None

Returns:

Name of the matched prompt, or None if no match.

scitex_agent_container.runtimes.prompts.is_ready(content)

Check if claude is at the main input prompt (all TUI prompts done).

Return type:

bool