containerized-strands-agents: Instructions file for Codex

Project Overview

Containerized Strands Agents is an MCP (Model Context Protocol) server that hosts isolated Strands AI agents in Docker containers. Each agent runs independently with its own workspace, persists conversation history across restarts, and supports custom system prompts, per-agent tools, and GitHub integration. The fire-and-forget architecture enables autonomous background task execution while the host manages container lifecycle, idle timeouts, and session persistence.

Repository Structure

• src/containerized_strands_agents/ — Core package:
  • server.py — MCP server (FastMCP tools)
  • agent_manager.py — Docker orchestration, container lifecycle
  • agent.py — Shared agent logic (create_agent, run_agent)
  • cli.py — CLI commands (snapshot, restore, run)
  • config.py — Configuration constants
• docker/ — Docker image: FastAPI runner, GitHub tools, requirements
• ui/ — Optional web UI: FastAPI REST wrapper and HTML interface
• scripts/ — Shell scripts for building Docker image and running the server
• tests/ — Unit, integration, and end-to-end tests using pytest
• templates/ — GitHub Actions workflow template for running agents in CI
• .github/workflows/ — CI and PyPI publishing workflows
• data/ — Runtime persistence (gitignored): agent workspaces, sessions, task registry

Build & Development Commands

# Install in development mode
pip install -e ".[dev]"

# Install with web UI support
pip install -e ".[webui]"

# Or use Makefile
make dev              # Install with all dependencies
make test             # Run unit tests
make test-all         # Run all tests (requires Docker)
make build            # Build wheel and sdist
make docker           # Build Docker image

# Build Docker image (auto-built on first use, or manually)
./scripts/build_docker.sh

# Run MCP server (for use with Kiro, Claude Desktop, etc.)
containerized-strands-agents-server
# or
python -m containerized_strands_agents.server

# Run web UI (finds free port 8000-8100)
containerized-strands-agents-webui

# Run tests
python -m pytest tests/ -v