Sample Cloud Native Nanoclaw

English | 中文

Evolved from NanoClaw — a single-user local bot framework — into a fully managed, multi-tenant cloud platform. Each user gets their own Bots with independent memory, conversations, and scheduled tasks.

Architecture

User (Telegram/Discord/Slack)
  │
  ▼ Webhook
ALB ──► ECS Fargate (Control Plane)
         ├── Webhook Handler → SQS FIFO
         ├── SQS Consumer → AgentCore Runtime (microVM)
         │                    └── Claude Agent SDK
         │                        └── Bedrock Claude
         ├── Reply Consumer → Channel API → User
         └── REST API (JWT auth) ◄── Web Console (React SPA on CloudFront)

Data Layer: DynamoDB (state) │ S3 (sessions, memory) │ Secrets Manager (credentials)
Scheduling: EventBridge Scheduler → SQS → Agent
Auth: Cognito User Pool (JWT)
Security: WAF │ ABAC via STS SessionTags │ Per-tenant S3/DynamoDB isolation

Deployment modes: The diagram above shows the default agentcore mode. In ecs mode (for AWS China regions), AgentCore microVMs are replaced by ECS Fargate dedicated tasks (one per botId#groupJid session, with a warm pool for instant dispatch), Cognito is replaced by a self-hosted OIDC auth service, and Bedrock is replaced by Anthropic API. See ECS Mode below.

graph TB
    Users["👤 用户终端<br/>飞书/ Discord / Slack "]

    subgraph Ingress["入口层"]
        CloudFront["CloudFront + S3<br/>Web 控制台"]
        ALB["ALB<br/>/api/* · /webhook/*"]
    end

    subgraph ECS["ECS Fargate (Control Plane)"]
        Fastify["Fastify HTTP Server<br/>REST API · Webhook · 健康检查"]
        SQSConsumer["SQS Consumer<br/>入站 FIFO "]
        Adapters["Channel Adapters"]
    end

    subgraph Agent["Agent Execution Layer"]
        MicroVM["AgentCore microVM<br/>Claude Agent SDK + Bedrock<br/>工具 · MCP · Skills"]
    end

    subgraph Data["Data Layer"]
        DynamoDB[(DynamoDB)]
        S3[(S3)]
        Secrets[(Secrets Mgr)]
        EventBridge[(EventBridge)]
    end

    Users -->|HTTPS / Webhook| Ingress
    CloudFront --> ALB
    ALB --> Fastify
    Fastify --> SQSConsumer
    SQSConsumer -->|InvokeAgent| MicroVM
    MicroVM -->|send_message| SQSConsumer
    SQSConsumer --> Adapters
    Adapters -->|回复| Users

    MicroVM --> DynamoDB
    MicroVM --> S3
    Fastify --> Secrets
    MicroVM --> EventBridge

    style Ingress fill:#E3F2FD,stroke:#1565C0,color:#000
    style ECS fill:#FFF3E0,stroke:#E65100,color:#000
    style Agent fill:#F3E5F5,stroke:#6A1B9A,color:#000
    style Data fill:#FCE4EC,stroke:#C62828,color:#000

Packages

Key Decisions

NanoClaw → Cloud Mapping

Prerequisites

• Node.js >= 20
• Docker (for building ARM64 container images)
• AWS CLI configured (aws configure)
• AWS CDK bootstrapped (cd infra && npx cdk bootstrap)
• jq installed (used by deploy script for JSON parsing)

Deployment

One-Command Deploy

# Full deployment (default stage: dev)
ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=SecurePass123! ./scripts/deploy.sh

# Deploy to a specific stage
CDK_STAGE=prod AWS_REGION=us-east-1 ADMIN_EMAIL=admin@company.com ADMIN_PASSWORD=Pr0d!Pass ./scripts/deploy.sh

ADMIN_EMAIL and ADMIN_PASSWORD are required — the script will abort if not set.

ECS Mode (China Regions)

For deployment in AWS China regions (cn-north-1, cn-northwest-1) where Cognito, Bedrock, and AgentCore are unavailable:

# ECS mode deployment
DEPLOY_MODE=ecs ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=SecurePass123! ./scripts/deploy.sh

# ECS mode uses:
# - Self-hosted OIDC auth service (replaces Cognito)
# - ECS Fargate dedicated task per session (replaces AgentCore microVMs)
#   Each botId#groupJid gets its own Fargate task with warm pool for instant dispatch
# - Anthropic API (replaces Bedrock) — requires per-user API keys

ECS Mode Parameters (CDK context)

These parameters are passed via CDK context and control the ECS dedicated task model:

The warm pool eliminates cold-start latency (~30-90s) for new sessions. When a message arrives for a new session, the control plane claims a warm task instantly from the pool and replenishes it in the background. If the pool is empty, a cold-start fallback launches a new task. Each session (botId#groupJid) gets its own dedicated Fargate task; tasks self-stop after the idle timeout.

The DEPLOY_MODE=ecs flag:

• Builds and pushes an additional auth-service Docker image
• Passes --context mode=ecs to CDK (creates auth ECS service + agent ECS service instead of Cognito + AgentCore)
• Skips AgentCore registration steps (8, 9, 9b, 10, 11)
• Configures web-console for OIDC auth instead of Cognito
• Seeds admin directly in DynamoDB (bcrypt hash generated via Node.js)

The deploy script runs 17 steps in order:

1. Pre-flight checks (aws, docker, node, jq)
2. npm install + build all workspaces
3. ECR login (creates repos if missing)
4. Build & push control-plane Docker image (ARM64)
5. Build & push agent-runtime Docker image (ARM64)
6. CDK deploy all 6 stacks
7. Read stack outputs (Cognito IDs, bucket names, role ARNs, ALB DNS, CDN domain)
8. Register AgentCore runtime (idempotent — skips if already exists)
9. Wait for AgentCore status READY
10. Update ECS task definition with AGENTCORE_RUNTIME_ARN env var
11. Force new ECS deployment
12. Build web-console with Cognito config injected via env vars
13. Sync web-console/dist/ to S3 frontend bucket
14. CloudFront cache invalidation
15. Smoke test (/health endpoint)
16. Seed default admin account (idempotent — skips if already exists)
17. Write AgentCore runtime ARN to SSM Parameter Store

Steps 5b, 8-11, 16-17 behave differently in ECS mode. See DEPLOY_MODE=ecs above.

Admin account: Since Cognito self-signup is disabled, Step 16 creates the initial admin user. ADMIN_EMAIL and ADMIN_PASSWORD are required env vars — the script will not start without them.

Teardown

./scripts/destroy.sh                    # default stage: dev
CDK_STAGE=prod ./scripts/destroy.sh     # specific stage

Reverse order: delete AgentCore runtime (wait for deletion) → CDK destroy all stacks → delete ECR repos.

Local Development

# Run control plane locally (pointing at deployed AWS resources)
cd control-plane
cp .env.example .env   # fill in values from CDK outputs
npm run dev

# Run web console locally
cd web-console
npm run dev            # opens http://localhost:5173

Project Structure

cloud_native_nanoclaw/
├── scripts/
│   ├── deploy.sh             # One-command full deployment (17 steps)
│   └── destroy.sh            # Reverse teardown
├── shared/src/
│   ├── types.ts              # User, Bot, Channel, Message, Task, Session...
│   ├── xml-formatter.ts      # Agent context formatting (from NanoClaw)
│   └── text-utils.ts         # Output processing
├── auth-service/src/
│   ├── server.ts             # Fastify auth service (login, refresh, admin)
│   ├── jwt.ts                # RS256 signing, JWKS endpoint
│   └── password.ts           # bcrypt password hashing
├── infra/
│   ├── bin/app.ts            # CDK app entry
│   └── lib/
│       ├── foundation-stack.ts   # VPC, S3, DynamoDB, SQS, ECR
│       ├── auth-stack.ts         # Cognito
│       ├── agent-stack.ts        # IAM Roles (ABAC)
│       ├── control-plane-stack.ts# ALB, ECS Fargate, WAF
│       ├── frontend-stack.ts     # CloudFront + S3
│       └── monitoring-stack.ts   # CloudWatch, alarms
├── control-plane/src/
│   ├── index.ts              # Fastify app + SQS consumer startup
│   ├── webhooks/             # Telegram, Discord, Slack handlers
│   ├── sqs/                  # Message dispatcher + reply consumer
│   ├── routes/api/           # REST API (bots, channels, groups, tasks)
│   ├── services/             # DynamoDB, cache, credential lookups
│   └── channels/             # Channel API clients
├── agent-runtime/src/
│   ├── server.ts             # HTTP server (/invocations, /ping)
│   ├── agent.ts              # Claude Agent SDK integration
│   ├── session.ts            # S3 session sync
│   ├── memory.ts             # Multi-layer CLAUDE.md
│   ├── scoped-credentials.ts # STS ABAC
│   ├── mcp-tools.ts          # send_message, schedule_task, etc.
│   └── mcp-server.ts         # MCP stdio server
└── web-console/src/
    ├── pages/                # Login, Dashboard, BotDetail, ChannelSetup...
    ├── lib/                  # Auth (Cognito), API client
    └── components/           # Layout

Message Flow

1. User sends @Bot hello in Telegram group
2. Telegram POST → /webhook/telegram/{bot_id} (ALB → Fargate)
3. Webhook handler verifies signature, stores message in DynamoDB, enqueues to SQS FIFO
4. SQS consumer dequeues, loads recent messages, invokes AgentCore Runtime (async fire-and-forget)
5. AgentCore returns accepted immediately, agent runs in background → Claude Agent SDK query()
6. Agent generates response, optionally uses MCP tools (schedule_task, send_message)
7. Final reply sent via SQS reply queue → Reply Consumer stores in DynamoDB, sends via Telegram API
8. User sees reply in Telegram

Security

• Auth: Cognito JWT on all /api/* routes (agentcore mode) or self-hosted JWKS JWT (ecs mode)
• Webhooks: Per-channel signature verification (Telegram secret token, Discord Ed25519, Slack HMAC-SHA256)
• Data isolation: ABAC via STS SessionTags — agents can only access their owner's S3 paths and DynamoDB records
• Network: Fargate in private subnets, WAF rate limiting (2000 req/5min/IP)
• Credentials: Channel tokens stored in Secrets Manager, never exposed to agents

Cost Estimate (single user)

Documentation