Skip to main content
Glama
mkmeral

Containerized Strands Agents

by mkmeral
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Containerized Strands Agents

An MCP server that hosts isolated Strands AI agents in Docker containers. Each agent runs independently with its own workspace, persists conversation history, and can be restored after reboots.

Features

  • Async/Non-blocking: send_message returns immediately (fire-and-forget)

  • Isolated Agents: Each agent runs in its own Docker container

  • Session Persistence: Conversation history saved and restored across container restarts

  • Custom System Prompts: Configure per-agent system prompts via text or file

  • MCP Server Support: Connect agents to external tools via Model Context Protocol

  • GitHub Integration: Agents can push to repositories with scoped access tokens

  • AWS Profile Support: Pass different AWS profiles for different agents

  • Retry Logic: Automatic retry with exponential backoff for transient errors

  • Idle Timeout: Containers automatically stop after configurable inactivity period

  • Web UI: Browser-based interface for managing agents and chatting

Prerequisites

  • Python 3.11+

  • Docker (running)

  • AWS credentials configured in ~/.aws/ with access to Amazon Bedrock (Claude models)

Quick Start

# Clone the repository git clone <repo-url> cd containerized-strands-agents # Install with web UI support pip install -e ".[webui]" # Start the web UI containerized-strands-agents-webui

Open the URL shown in the terminal (usually http://localhost:8000) to create and chat with agents.

Installation

# Basic installation (MCP server only) pip install -e . # With web UI support pip install -e ".[webui]" # All features including dev tools pip install -e ".[webui,dev]"

The Docker image will be built automatically on first use.

Usage

Web UI

containerized-strands-agents-webui # or python run_web_ui.py

The server finds an available port (starting at 8000) and displays the URL. Use the web interface to:

  • Create new agents with custom system prompts

  • Chat with existing agents

  • View agent status and conversation history

  • Stop idle agents

As an MCP Server (Kiro, Claude Desktop, etc.)

Add to your MCP configuration (e.g., ~/.kiro/settings/mcp.json):

{ "mcpServers": { "containerized-strands-agents": { "command": "containerized-strands-agents-server", "env": { "CONTAINERIZED_AGENTS_GITHUB_TOKEN": "github_pat_xxxx", "CONTAINERIZED_AGENTS_MCP_CONFIG": "/path/to/mcp.json", "AWS_BEARER_TOKEN_BEDROCK": "optional-bearer-token" } } } }

The CONTAINERIZED_AGENTS_MCP_CONFIG env var sets a default mcp.json for all agents spawned by this server. You can point it to your existing Kiro config or a separate one.

MCP Tools

Tool

Description

send_message

Send message to agent (fire-and-forget), creates agent if needed

get_messages

Get conversation history (use on-demand, not for polling)

list_agents

List all agents and their status

stop_agent

Stop an agent's container

send_message Parameters

send_message( agent_id="my-agent", message="Hello!", aws_profile="my-profile", # Optional: AWS profile for Bedrock aws_region="us-west-2", # Optional (default: us-east-1) system_prompt="You are a pirate...", # Optional: custom instructions system_prompt_file="/path/to/prompt", # Optional (takes precedence over system_prompt) tools=["/path/to/tool.py"], # Optional: per-agent tools data_dir="/path/to/project", # Optional: custom data directory mcp_config_file="~/.kiro/settings/mcp.json", # Optional: path to MCP config mcp_config={"mcpServers": {...}}, # Optional: inline MCP config )

CLI Commands for Snapshot/Restore

The CLI provides commands to create and restore agent snapshots (backups):

Create a Snapshot

containerized-strands-agents snapshot --data-dir ./my-agent --output snapshot.zip

Creates a zip archive of an agent's entire data directory, including:

  • Workspace files

  • Session history

  • System prompts

  • Tools

  • Runner files

Restore from Snapshot

containerized-strands-agents restore --snapshot snapshot.zip --data-dir ./restored-agent

Extracts a snapshot to a new (or existing) directory. The restored agent is immediately ready to run.

Examples:

# Backup an agent containerized-strands-agents snapshot \ --data-dir ./data/agents/my-project \ --output backups/my-project-2024-01-01.zip # Restore to a new location containerized-strands-agents restore \ --snapshot backups/my-project-2024-01-01.zip \ --data-dir ./data/agents/my-project-restored # Use with custom data directories containerized-strands-agents snapshot \ --data-dir ~/projects/agent-workspace \ --output ~/backups/agent-snapshot.zip

Notes:

  • Snapshots work with both default data directories (./data/agents/{id}) and custom ones

  • The CLI validates the directory structure before creating snapshots

  • Restoring to an existing directory will prompt for confirmation

  • Restored agents can be started immediately using the MCP server or Web UI

Pull from GitHub Actions

containerized-strands-agents pull --repo owner/repo --run-id 12345 --data-dir ./my-agent

Downloads agent state from a GitHub Actions artifact. Useful for continuing work started in CI.

Options:

  • --repo (required): Repository in owner/repo format

  • --run-id: Download artifacts from a specific workflow run

  • --artifact: Download a specific artifact by name

  • --data-dir: Target directory (default: ./agent-data)

  • --token: GitHub token (uses GITHUB_TOKEN env var if not provided)

Examples:

# Pull from a specific run containerized-strands-agents pull \ --repo myorg/my-repo \ --run-id 12345678 \ --data-dir ./data/agents/from-gha # Pull a specific artifact by name containerized-strands-agents pull \ --repo myorg/my-repo \ --artifact agent-data-default-agent-42 \ --data-dir ./restored-agent # Uses gh CLI if available, otherwise GitHub API with token export GITHUB_TOKEN="ghp_xxxx" containerized-strands-agents pull --repo myorg/my-repo --run-id 12345

GitHub Actions Workflow

A workflow template is provided at templates/gha-agent-workflow.yml for running agents in GitHub Actions:

# Copy to your repo cp templates/gha-agent-workflow.yml .github/workflows/run-agent.yml

The workflow:

  1. Restores agent state from a previous artifact (optional)

  2. Runs the agent with your message

  3. Uploads updated state as an artifact

Trigger via workflow_dispatch with a message input. See the template for required secrets (AWS credentials).

Configuration

Environment Variables

These variables configure the MCP server. Set them either in your mcp.json (under env) or export them in your shell before running the web UI.

Server Configuration:

Variable

Default

Description

CONTAINERIZED_STRANDS_DATA_DIR

./data

Base directory for persistence

AGENT_HOST_IDLE_TIMEOUT

720

Minutes before idle container stops (12 hrs)

CONTAINERIZED_AGENTS_SYSTEM_PROMPTS

-

Comma-separated paths to prompt files

CONTAINERIZED_AGENTS_TOOLS

-

Path to global tools directory

CONTAINERIZED_AGENTS_MCP_CONFIG

-

Path to default mcp.json for all agents

Passed to Containers (agents can use these):

Variable

Description

CONTAINERIZED_AGENTS_GITHUB_TOKEN

GitHub PAT for git push access

OPENAI_API_KEY

OpenAI API key (for OpenAI models)

GOOGLE_API_KEY

Google/Gemini API key

AWS_BEARER_TOKEN_BEDROCK

AWS bearer token for Bedrock authentication

Example for web UI:

export CONTAINERIZED_AGENTS_GITHUB_TOKEN="github_pat_xxxx" export AWS_BEARER_TOKEN_BEDROCK="your-token" # Optional: alternative Bedrock auth containerized-strands-agents-webui

AWS Setup

Agents use Amazon Bedrock with Claude models by default. You have two options:

Option 1: AWS Credentials (default)

Your ~/.aws/credentials are mounted read-only into containers. Ensure your profile has Bedrock access.

# Verify AWS credentials aws sts get-caller-identity # Check Bedrock model access (us-east-1) aws bedrock list-foundation-models --region us-east-1 --query "modelSummaries[?contains(modelId, 'claude')]"

Option 2: Bearer Token

Set AWS_BEARER_TOKEN_BEDROCK as an alternative authentication method for Bedrock.

GitHub Token Setup (Optional)

For agents that need to push to GitHub repositories:

  1. Create a Fine-Grained Personal Access Token

  2. Select "Only select repositories" and choose your repos

  3. Grant "Contents: Read and write" permission

  4. Set CONTAINERIZED_AGENTS_GITHUB_TOKEN environment variable

Agent Capabilities

Each agent has access to:

  • file_read, file_write, editor - File operations

  • shell - Execute shell commands

  • python_repl - Run Python code

  • use_agent - Spawn sub-agents

  • load_tool - Dynamically load additional tools

  • GitHub tools - Create/update issues and PRs

  • MCP tools - Any tools from configured MCP servers

Important: Agents work in /data/workspace inside the container. This directory persists across container restarts.

MCP Server Support

Agents can connect to external MCP (Model Context Protocol) servers for additional tools. This uses the same config format as Kiro/Claude Desktop.

Quick Setup: Use Your Existing Config

Point agents to your existing Kiro mcp.json:

# Set as default for all agents export CONTAINERIZED_AGENTS_MCP_CONFIG="~/.kiro/settings/mcp.json" containerized-strands-agents-webui

Or per-agent via MCP tool:

send_message( agent_id="researcher", message="Search AWS docs for Lambda limits", mcp_config_file="~/.kiro/settings/mcp.json" )

Inline MCP Config

send_message( agent_id="docs-agent", message="What is Amazon S3?", mcp_config={ "mcpServers": { "aws-docs": { "command": "uvx", "args": ["awslabs.aws-documentation-mcp-server@latest"] }, "perplexity": { "command": "npx", "args": ["-y", "@anthropic-ai/mcp-server-perplexity"], "env": {"PERPLEXITY_API_KEY": "pplx-xxx"} } } } )

Config Format

Same as Kiro/Claude Desktop:

{ "mcpServers": { "server-name": { "command": "uvx", "args": ["package-name@latest"], "env": {"API_KEY": "..."}, "disabled": false } } }

Configuration Precedence

  1. mcp_config_file param (path to mcp.json)

  2. mcp_config param (inline dict)

  3. Agent's persisted config (.agent/mcp.json)

  4. CONTAINERIZED_AGENTS_MCP_CONFIG env var (global default)

MCP config is persisted per-agent, so you only need to set it once. Subsequent messages to the same agent will use the saved config.

Supported Transports

  • stdio (default): Local command-line MCP servers via uvx or npx

  • SSE: Remote HTTP-based MCP servers

Notes

  • uvx and npx are pre-installed in containers - no need to install individual MCP servers

  • Environment variables in config (like ${GITHUB_TOKEN}) are expanded at runtime

  • Disabled servers ("disabled": true) are skipped

  • Fails open: If an MCP server fails to connect, the agent still starts with other tools. Check container logs for connection errors.

Data Persistence

data/ ├── tasks.json # Agent registry └── agents/{agent_id}/ ├── workspace/ # Agent's persistent files └── .agent/ ├── session/ # Conversation history (FileSessionManager) ├── system_prompt.txt # Custom system prompt ├── tools/ # Per-agent tools └── runner/ # Agent code for standalone execution

Development

# Install dev dependencies pip install -e ".[dev]" # Run tests python -m pytest tests/ -v # Run only unit tests (no Docker required) python -m pytest tests/test_agent_manager.py -v # Rebuild Docker image after changes ./scripts/build_docker.sh

Troubleshooting

Docker image not found: Run ./scripts/build_docker.sh manually

Bedrock access denied: Ensure your AWS credentials have Bedrock permissions and the model is enabled in your region

Agent stuck processing: Check container logs with docker logs agent-<agent-id>

Port already in use: The web UI automatically finds an available port; check the terminal output for the actual URL

License

MIT

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mkmeral/containerized-strands-agents'

If you have feedback or need assistance with the MCP directory API, please join our Discord server