redmare

<div align="center"> # RedMare <img src="Readme-image.png" alt="RedMare" width="900" /> **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. [](https://github.com/faramesh/redmare/actions/workflows/ci.yml) [](https://github.com/faramesh/redmare) [](https://pypi.org/project/redmare/) [](LICENSE) </div> --- ## 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 ```bash pip install redmare ``` Verify the installation: ```bash mairzy --help ``` ### Create an agent Create a minimal FastAPI agent in an empty directory: **`main.py`** ```python 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 ```bash 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 ```bash 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 ```bash 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 ```bash # Edit your agent code, then: mairzy deploy ``` ### Open a shell in the running task ```bash 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 ```bash mairzy logs # last 100 lines mairzy logs --follow # stream in real time ``` ### Check status ```bash mairzy status ``` ### Destroy ```bash 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`: ```bash 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: ```bash 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: ```bash 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: ```yaml 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: ```bash 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 ```bash pip install redmare ``` ### Uninstall ```bash 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: ```bash pip uninstall redmare ``` ### Upgrade ```bash pip install --upgrade redmare ``` --- ## agentfile.yml Reference ```yaml 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: ```powershell git config --global core.autocrlf input ``` - The `Makefile` requires a Unix-like shell (Git Bash, WSL, MSYS2). For Windows-native workflows, use Python directly: ```powershell 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 ```bash # 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`](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>