Configuration and Runtime Directories

Layout

Configuration is separated into user-scope and project-scope. Project-scope (.scitex/agent-container/ at the git root) takes priority when present.

~/.scitex/agent-container/ or <project>/.scitex/agent-container/
├── config.yaml                ← host identity, host.aliases, peers (F-CS12),
│                                listen.{host,port}, a2a.port_range
├── agents/<name>/             ← per-agent declarations (you write these)
│   ├── spec.yaml              ← v3 Agent definition (the SSoT)
│   └── dot_claude/            ← optional: materialized into <workdir> at start
│       ├── CLAUDE.md           (→ <workdir>/CLAUDE.md, marker-protected)
│       ├── .mcp.json           (→ <workdir>/.mcp.json, per-server merge)
│       ├── .env                (→ <workdir>/.env, mode 0600)
│       ├── state.md            (→ <workdir>/state.md, full overwrite)
│       ├── commands/           (→ <workdir>/.claude/commands/)
│       ├── skills/             (→ <workdir>/.claude/skills/)
│       └── hooks/              (→ <workdir>/.claude/hooks/)
├── accounts/                  ← saved Claude Code accounts (sac account save)
│   ├── <name>/
│   │   ├── account.json        (safe metadata; no tokens)
│   │   └── .credentials.json   (copied into ~/.claude/ on `sac account use`)
│   └── _rotations/
│       └── <email>.ndjson      (OAuth-rotation log, one append per observed rotation)
├── tokens/
│   └── listen-<host>.token    ← `sac listen` bearer tokens (0600)
├── containers/                ← built Apptainer images
│   ├── sac-base.sif    -> sac-base/sac-base.sif        (top-level symlink)
│   ├── sac-scitex.sif  -> sac-scitex/sac-scitex.sif    (top-level symlink)
│   ├── sac-{base,scitex}/                              (dir-per-image)
│   │   ├── sac-{base,scitex}.sif                       (the image; gitignored)
│   │   ├── sac-{base,scitex}.def                       (recipe snapshot)
│   │   ├── sac-{base,scitex}.build-YYYY-MMDD-HHMMSS.log (full build log; gitignored)
│   │   └── .def-hash                                   (skip-rebuild cache)
│   └── {dpkg,node,requirements}-lock.txt               (auto-freeze lock files)
└── runtime/                   ← regenerable per-host state; gitignored
    ├── <agent-name>/           per-agent runner state
    │   ├── pid                  (runner PID)
    │   ├── heartbeat.json       ({ts, pid, state}; refreshed every tick)
    │   ├── session_id           (persisted SDK session id, resume marker)
    │   ├── session.jsonl        (one JSON object per turn event)
    │   └── quota.json           (accumulated per-turn token totals)
    ├── events/                  Claude Code hook event ring-buffer
    │   └── <agent>.jsonl
    └── cache/                   snapshot cache for the dashboard / `sac agents diff`
        └── <agent>.{latest,prev,diff}.json

Configuration cascade

Settings are resolved in this order (first wins):

  1. CLI flag — sac agents start hello --workdir /tmp/x

  2. Env var — SAC_<X> or the long SCITEX_AGENT_CONTAINER_<X> form (setting both with different values raises SacEnvConflict). Copy .env.example to .env and uncomment what you need.

  3. Project config — <proj>/.scitex/agent-container/config.yaml, when you’re inside a git repo that ships one.

  4. User config — ~/.scitex/agent-container/config.yaml (relocatable via $SCITEX_DIR).