RedMare

One-command agent deployment to AWS Fargate, EC2 and Azure.

mairzy deploy — from agent.py to a live HTTPS URL in minutes. No AWS Console. No Terraform. No CDK.

---

Quickstart

Prerequisites

• Python 3.9+ (3.11+ recommended)
• Docker CLI — docker --version must work. Docker Desktop is not required, just the CLI and a running daemon (docker info must succeed).
• AWS credentials — aws configure or set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars.
• An API key for your model provider — set as environment variable, e.g. export ANTHROPIC_API_KEY=sk-...
• An AWS VPC. RedMare uses the default VPC by default, but you can also set deploy.vpc_id and deploy.subnet_ids in agentfile.yml for a custom network.

Agent requirements

Your agent must be an HTTP server. RedMare deploys it behind an ALB, so the agent needs to:

• Expose an HTTP server on the configured port (default 8000).
• Have a /health endpoint returning HTTP 200 (configurable via health_check_path in agentfile.yml).
• Accept POST requests on the path your app handles (e.g. /invoke).

A simple FastAPI app (see example below) satisfies all requirements. A script that just prints to stdout will not work — it will get 503 errors from the ALB with no indication why.

Install

pip install redmare

Verify the installation:

mairzy --help

Create an agent

Create a minimal FastAPI agent in an empty directory:

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/invoke")
def invoke(payload: dict):
    return {"output": f"Echo: {payload.get('input', '')}"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

requirements.txt

fastapi
uvicorn

Initialize

mairzy init

Follow the prompts to set your agent name, model provider, AWS region, and API key env var. This creates an agentfile.yml in your project.

Deploy

mairzy deploy

The tool will (in order):

1. Build a Docker container (auto cross-compiles ARM64 → AMD64 if needed, auto-detects agent framework)
2. Push the image to Amazon ECR (with scanOnPush enabled)
3. Provision AWS infrastructure: ECR, IAM roles, Secrets Manager, VPC, ALB, DynamoDB tables (for runs/sessions), ECS Fargate
4. Verify the deployment is healthy (exponential backoff, phases tracked for recovery)

Each phase is tracked in .redmare/state.json. If a deploy fails partway, re-running skips completed phases.

After 4–8 minutes you'll see:

🌐 Agent URL: http://my-agent-alb-1234567890.us-east-1.elb.amazonaws.com

Test the endpoint

curl http://my-agent-alb-...us-east-1.elb.amazonaws.com/health
curl -X POST http://my-agent-alb-...us-east-1.elb.amazonaws.com/invoke \
  -H "Content-Type: application/json" \
  -d '{"input":"hello"}'

Redeploy after code changes

# Edit your agent code, then:
mairzy deploy

Open a shell in the running task

mairzy ssh
mairzy ssh test-agent "whoami"

Set deploy.ssh.enabled: true in agentfile.yml to enable ECS Exec for the service.

RedMare reuses existing infrastructure and only updates the ECS service with the new image.

View logs

mairzy logs          # last 100 lines
mairzy logs --follow # stream in real time

Check status

mairzy status

Destroy

mairzy destroy

Removes all created AWS resources. Pass --keep-ecr to preserve the ECR repository, or --auto-approve to skip the confirmation prompt.

---

v0.2 Features

mairzy plan — Preview before deploying

See what AWS resources will be created, modified, or destroyed before running deploy:

mairzy plan

Output is a color-coded table (Resource, Current, Desired, Action) for 10 resource types (ECR, IAM, Secrets, VPC, ALB, ECS, DynamoDB).

Framework auto-detection

RedMare detects your agent framework from source code (AST-based) and generates an appropriate wrapper:

mairzy deploy  # auto-detects langgraph, crewai, strands, google_adk, openai_agents, semantic_kernel

Set framework: auto in agentfile.yml (default) or pin a specific framework. When a framework is detected, the generated wrapper handles request routing, session isolation, and MCP injection automatically.

Environment overlays

Manage multiple environments (dev/staging/prod) with Kustomize-style YAML overlays:

mairzy deploy --env staging         # loads overlays/staging.yml
mairzy deploy --overlay patch.yml   # apply arbitrary overlay file
mairzy plan --env production        # preview production changes

Overlays deep-merge into agentfile.yml: dicts merge, arrays replace, scalars override.

Session isolation & multi-tenancy

Configure per-tenant or per-user session isolation:

memory:
  session:
    isolation: per_tenant
    tenant_id_key: "tenant_id"

DynamoDB session tables are provisioned automatically when isolation is enabled. IAM policies are scoped to the table prefix.

mairzy dashboard — Local web UI

Monitor deployed agents from your browser:

pip install redmare[dashboard]   # install optional deps
mairzy dashboard                 # starts on localhost:8080
mairzy dashboard --port 9090     # custom port
mairzy dashboard --open          # auto-open browser

The dashboard shows agent status, recent invocations, and CloudWatch logs — all in a single-page HTML UI.

Production wrapper (async job pattern)

The generated wrapper for deployed agents implements:

• Async job pattern: POST /invoke returns 202 Accepted with run_id; polling via GET /runs/{run_id}
• DynamoDB runs table: stores run state, results, errors
• MCP sidecar injection: MCP server URLs passed via MCP_SERVER_* env vars
• Guardrails: configurable max_iterations and max_cost limits
• Session state: isolation per tenant/user using DynamoDB

---

Commands

Command	Description
mairzy init	Create agentfile.yml interactively
mairzy plan	Preview infrastructure changes (Terraform-style diff)
mairzy deploy	Build, push, and deploy to AWS Fargate
mairzy destroy	Remove all AWS resources
mairzy logs	Show CloudWatch logs (-f to follow)
mairzy status	Show deployment status
mairzy dashboard	Local web UI for monitoring deployed agents
mairzy uninstall	Uninstall the RedMare package and clean up local state

Global flags

Flag	Applies to	Description
--env <name>	deploy, plan	Load environment overlay (e.g. --env staging loads overlays/staging.yml)
--overlay <file>	deploy, plan	Apply overlay file on top of agentfile.yml
--dry-run	deploy	Build and validate without provisioning AWS resources

---

Package

Install from PyPI

pip install redmare

Uninstall

mairzy uninstall

This will:

1. Prompt to remove the .redmare/ local state directory.
2. Run pip uninstall redmare -y to remove the package.
3. Remind you to manually delete the mairzy entry point script if pip left it behind.

Or directly with pip:

pip uninstall redmare

Upgrade

pip install --upgrade redmare

---

agentfile.yml Reference

name: my-agent                         # 3-40 chars, lowercase alnum + hyphens
version: "1.0.0"                      # semver
entrypoint: main.py                    # relative path from agentfile
requirements: requirements.txt         # or pyproject.toml

model:
  provider: anthropic                  # anthropic | openai | bedrock
  api_key_secret: ANTHROPIC_API_KEY   # env var name

deploy:
  cloud: aws                           # only aws in v0.2
  region: us-east-1
  regions:                             # multi-region (experimental)
    - us-east-1
  failover: active-passive             # active-passive | active-active
  vpc_id: ""                           # custom VPC (default: auto-detect)
  subnet_ids: []
  ssl_certificate_arn: ""              # HTTPS certificate
  min_capacity: 1
  max_capacity: 5
  desired_count: 1
  egress_strict: false                 # restrict egress to HTTPS(443) + DNS(53/UDP)
  ssh:
    enabled: false                     # enable ECS Exec for debugging
    command: /bin/bash                 # default shell command

framework: auto                        # auto (AST) | langgraph | crewai | strands
                                       # google_adk | openai_agents | semantic_kernel | fallback
invoke_function: handle_request        # function name for framework-based agents
invoke_is_async: false                 # true if invoke_function is async

memory:
  session:
    isolation: none                    # none | per_tenant | per_user
    tenant_id_key: "tenant_id"         # JSON key for tenant/user ID

secrets:                               # additional ECS secret env vars
  - name: OTHER_API_KEY
    valueFrom: arn:aws:secretsmanager:...:secret:my-secret

port: 8000                             # default: 8000
timeout_seconds: 300                   # default: 300
memory_mb: 2048                        # default: 2048
cpu: 1.0                               # default: 1.0 (0.25, 0.5, 1, 2, 4)
health_check_path: /health             # default: /health
environment:                           # non-secret env vars
  LOG_LEVEL: INFO

---

Cross-platform Support

RedMare runs on macOS, Linux, and Windows (via PowerShell, cmd, or WSL).

Windows notes

• The mairzy CLI works in PowerShell, cmd, and Git Bash.
• Docker commands require the Docker CLI (docker.exe) on your PATH — Docker Desktop or Docker Engine.
• Git (optional) provides short SHA tagging; falls back to nosha if unavailable.
• Line endings: Ensure Git is configured with core.autocrlf=input to avoid CRLF issues inside the container:

  git config --global core.autocrlf input

• The Makefile requires a Unix-like shell (Git Bash, WSL, MSYS2). For Windows-native workflows, use Python directly:

  python -m pytest tests/unit/
  python -m ruff check .

---

Known Limitations (v0.2)

• Multi-region is experimental: The schema accepts deploy.regions but only the first region is deployed to. Active-active failover across regions is not yet implemented.
• Dashboard: mairzy dashboard is a local web UI for monitoring. Requires optional dependencies (pip install redmare[dashboard]). Not a replacement for CloudWatch.
• PyPI publication: Package builds cleanly. Pending PyPI API token for pip install redmare availability.

---

Development

# Clone and install
git clone https://github.com/faramesh/redmare.git
cd redmare
make install

# Run tests
make test          # unit + mocked AWS tests
make test-unit     # unit tests only
make test-mocked   # mocked AWS tests (moto)
make test-integration  # LocalStack integration tests
make test-e2e      # real AWS E2E tests

# Build package
make build

# Lint
make lint

See CONTRIBUTING.md for full details.

---

Links

• Docs: https://redmare.faramesh.dev
• GitHub: https://github.com/faramesh/redmare
• PyPI: https://pypi.org/project/redmare/
• Issues: https://github.com/faramesh/redmare/issues