Quickstart
==========

1. Install the package:

.. code-block:: bash

    pip install scitex-agent-container

   The fastest path is to copy a pattern template from
   ``examples/agent-templates/`` (``local``, ``docker``, ``apptainer``, ``ssh``,
   ``ssh-slurm``, ``mcp``). See :doc:`templates` for the full matrix.

2. Create an agent definition directory with a YAML manifest plus
   sibling ``src_CLAUDE.md`` and ``src_mcp.json``:

.. code-block:: yaml

    # my-agent/my-agent.yaml
    apiVersion: scitex-agent-container/v2
    kind: Agent
    metadata:
      name: my-agent
      labels:
        role: worker
    spec:
      runtime: claude-code
      model: sonnet
      multiplexer: tmux
      claude:
        flags:
          - --dangerously-skip-permissions
        session: continue-or-new
      health:
        enabled: true
        interval: 60
        method: multiplexer-alive
      restart:
        policy: on-failure
        max_retries: 3

3. Start and inspect the agent:

.. code-block:: bash

    scitex-agent-container start my-agent/my-agent.yaml
    scitex-agent-container inspect my-agent
    scitex-agent-container show-status my-agent --json
    scitex-agent-container show-logs my-agent -n 100
    scitex-agent-container attach my-agent      # Ctrl-B D to detach (tmux)

4. (Optional) Wire Claude Code hooks so ``status --json`` can surface
   recent tool calls, prompts, and sub-agent launches. See
   :doc:`status_and_hooks` for the full ``.claude/settings.local.json``
   snippet.

5. Run your first pane action. The nonce probe types
   ``Repeat <nonce>`` into the pane and confirms the model echoes it
   back -- a true functional-liveness check, not just "process alive":

.. code-block:: bash

    scitex-agent-container actions run nonce-probe my-agent
    scitex-agent-container actions query --agent my-agent --limit 5
    scitex-agent-container actions stats --agent my-agent --since 1h

   Every attempt is recorded in ``~/.scitex/agent-container/actions.db``
   and the most recent one is reflected in ``status --json`` under
   ``last_action_at`` / ``last_action_name`` / ``last_action_outcome``.
   See :doc:`actions` for the full subsystem.
