Cloudwright

Describe a cloud architecture in English. Get Terraform, costs, and a compliance check.

pip install 'cloudwright-ai[cli]'
export ANTHROPIC_API_KEY=sk-ant-...
cloudwright design "HIPAA healthcare API on AWS with Postgres and Redis"

Cloudwright takes a one-line description of a cloud system and produces a structured architecture spec, a per-component cost breakdown, a compliance report, and ready-to-apply Terraform, Pulumi (TypeScript or Python), or CloudFormation. It works across AWS, GCP, Azure, and Databricks. Version 1.4 adds live AWS import (cloudwright import-live), the Pulumi exporter, two-stage prompting with first-class network boundaries, and a drop-in GitHub Action that posts arch-diff plus cost-delta on every infra PR.

Try it - What's new in v1.4 - Docs - MCP server

What you get

• Architecture spec (typed YAML, version-controlled, the single source of truth)

• Cost breakdown across AWS, GCP, Azure, Databricks (multi-region, per-component, four pricing tiers)

• Compliance report covering HIPAA, SOC 2, PCI-DSS, FedRAMP Moderate, GDPR, and Well-Architected

• Terraform and CloudFormation export with safe defaults (encryption, IMDSv2, locked-down S3, sensible RDS settings)

• Diagrams in ASCII, Mermaid, D2, and a fully editable web canvas

• MCP server for AI agents (Claude Desktop, Cursor, Cline, and any MCP-compatible client)

Quickstart

cloudwright design "HIPAA healthcare API on AWS with Postgres and Redis"
cloudwright cost spec.yaml --workload-profile medium
cloudwright validate spec.yaml --compliance hipaa,soc2
cloudwright export spec.yaml --format terraform -o ./infra
cloudwright chat --web                                # browser canvas at http://localhost:8765

All commands except design, modify, chat, and adr work fully offline. Set ANTHROPIC_API_KEY (preferred) or OPENAI_API_KEY to enable the LLM-powered ones. Drop --json on any command for machine-readable output.

Smart Canvas + Module Catalog (v1.2)

The web diagram is a fully editable architecture canvas. Edits (add, drag, connect, edit fields, delete) are deterministic frontend mutations, so they are instant, free, and reproducible. They do not call the LLM.

A left-side Catalog drawer has three tabs:

• Resources - the full catalog for the active provider, served by /api/catalog/services (case-insensitive ?provider=).

• Modules - approved multi-resource patterns from /api/modules. Bundled: AWS Three-Tier Web, AWS Serverless API, AWS Data Lake, GCP Serverless API, Azure Three-Tier Web.

• Standards - runs POST /api/canvas/validate and surfaces orphan connections, partial modules, unapproved modules, naming-prefix violations, and missing required tags.

When a module instance is intact, the Terraform exporter emits a single module "<id>" block with the catalog's pinned source and version. Modified modules fall back to per-component resource rendering. Mixed specs work: catalog modules render as modules, ad-hoc resources as resources, side by side.

cloudwright chat --web
# Open http://localhost:8765, use the Catalog drawer, then Export -> Terraform

MCP server (Claude / Cursor / Cline)

Expose Cloudwright as Model Context Protocol tools so AI agents can design, cost, validate, and export architectures directly. 18 tools across 6 groups (design, cost, validate, analyze, export, session).

pip install cloudwright-ai-mcp
cloudwright mcp                              # all tools, stdio
cloudwright mcp --tools design,cost          # subset
cloudwright mcp --transport sse              # SSE for HTTP clients

claude_desktop_config.json (same shape works for Cursor and Cline):

{
  "mcpServers": {
    "cloudwright": {
      "command": "cloudwright",
      "args": ["mcp"]
    }
  }
}

Analysis

cloudwright lint (10 anti-pattern checks), cloudwright score (5-dimension quality grade), cloudwright analyze (blast radius and SPOF), cloudwright drift <spec> <tfstate> (design vs deployed), cloudwright policy --rules policy.yaml (policy-as-code with 9 built-in checks), and cloudwright security (security anti-patterns; also scans exported Terraform HCL). Every command supports --json. See docs/ and the examples/ directory for end-to-end samples.

Python API

from cloudwright import ArchSpec
from cloudwright.cost import CostEngine
from cloudwright.validator import Validator
from cloudwright.exporter import export_spec

spec = ArchSpec.from_file("spec.yaml")
priced = CostEngine().estimate(spec, workload_profile="medium")
results = Validator().validate(spec, compliance=["hipaa", "pci-dss"])
hcl = export_spec(spec, "terraform", output_dir="./infra")

What's new in v1.4.0

• Pulumi exporter (TypeScript + Python). cloudwright export spec.yaml --format pulumi-ts -o ./infra writes a complete Pulumi TypeScript project (index.ts, Pulumi.yaml, package.json, tsconfig.json). --format pulumi-python writes the Python equivalent. AWS, GCP, and Azure coverage matches the Terraform exporter, with the same safe-by-default posture (S3 public-access block + AES256 + versioning, RDS encryption + 7-day backups + deletion protection, EC2 IMDSv2, DynamoDB SSE + PITR, CloudFront TLSv1.2_2021, CloudTrail log-file validation). Aliases pulumi-typescript and pulumi-py also work.

• Live AWS import. cloudwright import-live --provider aws --region us-east-1 [--profile NAME] [--services ec2,rds,s3] [-o spec.yaml] walks boto3 describe-* calls (EC2, VPC + subnets + security groups, RDS, S3, Lambda, ECS, EKS, DynamoDB, ALB / NLB, CloudFront, SQS, API Gateway, CloudTrail) and produces an ArchSpec from running infrastructure. Captures security posture (S3 encryption + versioning + public-access-block, RDS multi-AZ + backup retention, EC2 IMDSv2, SG ingress 0.0.0.0/0). Best-effort connection inference: ALB to EC2 via target groups, CloudFront to S3 via origin domains. Per-service permission denials are non-fatal. Optional dep: pip install 'cloudwright-ai[live-import]'.

• Two-stage prompting plus boundary-aware spec. Architect.design() now runs Stage 1 (free-text architectural reasoning via Sonnet) followed by Stage 2 (strict JSON projection via Haiku). Stage 2 is told the canonical service keys, allowed connection kinds (sync_request | async_event | stream | replication | batch), and boundary kinds (VPC / subnet / security_group / availability_zone / region / account), so it projects faithfully without redesigning. VPCs, subnets, and SGs are now first-class in the LLM contract. Per-stage usage (stage1, stage2, total_cost_usd, two_stage: true) is exposed on /api/design, /api/modify, and their streaming variants. Single-shot path retained as fallback (Architect(two_stage=False)).

• Workload-aware safe defaults. Pre-v1.4, _post_validate forced encryption=true, multi_az=true, backup=true, auto_scaling=true, and count=2 onto every spec, masking Stage 1 reasoning. v1.4 makes these conditional on spec.metadata.workload_profile: sandbox, dev, test, demo, poc keep the LLM's chosen values; production, medium, large, enterprise get safe defaults forced. Compliance frameworks (HIPAA, PCI-DSS, SOC 2, GDPR, FedRAMP, HITRUST, ISO 27001) always force encryption + HA regardless of profile.

• GitHub Action for PR previews. Drop-in workflow posts an idempotent comment with architecture diff (added / removed / changed components), monthly cost delta (head vs. base, with annual rollup), and per-framework compliance changes whenever a PR touches *.tf, *.tfstate, cloudwright.yaml, or spec.yaml. Reusable composite action at .github/actions/cloudwright-pr-comment/. See docs/github-action.md.

• Refreshed Smart Canvas demo GIF (examples/cloudwright-smart-canvas-demo.gif) showing prompt to diagram to catalog drawer to add resource to side-panel edit to cost recomputation against the current UI. Reproducible via python scripts/record_smart_canvas.py.

• Cancel-safe streaming via AsyncAnthropic and AsyncOpenAI. chat/stream and design/stream now use native async clients instead of a threading.Thread + asyncio.Queue bridge. When a client disconnects mid-stream, CancelledError propagates into the SDK's async with block and closes the upstream HTTPX connection, so the LLM call stops billing tokens at disconnect rather than at completion. Eliminates orphan threads and queue-full data loss. Sync send_stream / generate_stream paths are preserved for the CLI; only the web routers switched.

What's new in v1.3.0

• Safe-by-default Terraform. S3 public-access blocks, RDS storage_encrypted and deletion_protection, EC2 IMDSv2, security-group ingress restricted to listed CIDRs.

• HCL injection-safe escaping. All Terraform exporters (AWS, GCP, Azure, Databricks) escape user-supplied config values before interpolation.

• Per-model LLM pricing. Haiku (fast classifier) and Sonnet (designer) billed at their respective rates instead of a single hardcoded rate.

• Anthropic prompt caching. Roughly 70-80% input-token savings on chat follow-ups, with measurable latency improvement.

• Atomic SessionStore writes. No more session corruption on SIGKILL or disk full mid-write.

• Constant-time API key comparison. Web API auth is now timing-attack hardened.

• FedRAMP region allowlist. us-east-1 is no longer flagged as FedRAMP-authorized; the validator now matches the actual GovCloud / FedRAMP-authorized region set.

• Health and version endpoints. /health returns version, configured model, and catalog status. New /api/version.

• Request correlation IDs. Every web request gets an X-Request-Id, plumbed through router logs.

• --debug flag works. Used to be a silent no-op; now prints prompts, timing, and token counts.

• cloudwright chat --web pinned to port 8765 to match docs and MCP/Slack integrations.

• Cost in design responses. /api/design and /api/modify now return cost in the response payload.

• Swagger UI gated. /docs is off in production by default; set CLOUDWRIGHT_DOCS_ENABLED=true to expose it.

Compatibility

• Python 3.12+

• LLM providers: Anthropic (Claude Sonnet, Haiku) and OpenAI (GPT-5+ family). Auto-detected from env.

• Clouds: AWS, GCP, Azure, Databricks. 112 service keys total.

• Install variants: cloudwright-ai[cli], cloudwright-ai[web], cloudwright-ai-mcp.

Contributing, license, changelog

• Contributing guide: CONTRIBUTING.md

• License: MIT - see LICENSE

• Full release history: CHANGELOG.md