OpenAB ECS Deployments (oab-ecs)

This repository manages and deploys OpenAB bot services on AWS ECS Fargate. It keeps the deployment template separate from bot instance settings so multiple bot types stay easy to operate.

Chinese version: README_zh.md

---

Prerequisites

Before deploying anything from this repo, make sure these tools are installed and configured:

If this is your first time on a new host, start with the Quick Start guide.

Tip

AI agent install hint:

help me install aws cli , session-manager-plugin and ecsctl per https://github.com/oablab/ecsctl ,
  if already installed. skip

1. AWS CLI - used for AWS authentication and API calls.
   • Installation guide
2. AWS Session Manager Plugin - required for ecsctl exec.
   • Installation guide
3. ecsctl (0.6.0+) - kubectl-style ECS Fargate CLI.
   • GitHub repo
4. yq (v4+) - YAML parser used by the deployment scripts.
   • GitHub repo
5. jq (1.6+) - JSON utility used for AWS CLI output parsing.
   • Installation guide

Note

Verified environment:

• ecsctl CLI: 0.9.1 (minimum still 0.6.0+)
• yq CLI: 4.46.1
• OpenAB image tags: 0.9.0-beta.6-antigravity, 0.9.0-beta.6-kiro

Repository Layout

• docs/ - operational and AI agent guidance
• hooks/ - container pre-boot and pre-shutdown hooks
• state/ - static overlay layers for Layer 2-5
• ops/ - deployment scripts and configuration
• restored/ - gitignored local restore target for runtime snapshots

How It Works

Architecture

                     +------------------+
                     | Local Developer  |
                     +--------+---------+
                              | 1. ecsctl apply
                              v
                   +--------------------+
     +-------------+  AWS ECS Fargate   +-------------+
     |             | (OpenAB Container) |             |
     |             +--------+-----------+             |
     |                      |                         |
     | 2. Get Token         | 3. Sync State           | 4. Write Logs
     | (via Task Role)      | (via Task Role)         |
     v                      v                         v
+-----------+          +-----------+          +---------------+
|    AWS    |          |   AWS     |          |      AWS      |
|  Secrets  |          |    S3     |          |  CloudWatch   |
|  Manager  |          |  Bucket   |          |     Logs      |
+-----------+          +-----------+          +---------------+

1. Configuration Split

The repo separates environment-level settings from bot-level settings:

• bots.yaml contains bot-specific settings such as image, secret_path, and capacity.
• ops/aws-env.yaml contains your AWS account and network settings. It is generated by aws-init.sh and ignored by git.

Example bots.yaml entry:

ghost:
  backend_agent: agy
  image: ghcr.io/openabdev/openab:0.9.0-beta.6-antigravity
  agent_command: agy-acp
  secret_path: openab/oab-ghost
  cpu: '256'
  memory: '512'
  capacity: FARGATE_SPOT
  state_bucket: ''
  pre_boot_url: 'https://gist.githubusercontent.com/...'
  pre_boot_sha256: 'f3898f7b...'
  pre_shutdown_url: 'https://gist.githubusercontent.com/...'
  pre_shutdown_sha256: '66899a5e...'

2. Service Template (openab-ecs.yaml.template)

The template defines the standard ECS service:

• service/container name: openab-{{name}}
• image, command, args, and environment injection
• configurable capacity and region
• aws-sm://{{secret_path}}#DISCORD_BOT_TOKEN in config.toml
• pre_boot and pre_shutdown hooks for restore/backup

3. State and Persona Management

When the container starts, pre-boot.sh restores and overlays state. See state_layers.md for the full model.

Layer order:

1. Layer 1: runtime snapshot (s3://<bucket>/runtime/<bot>/home.tar.gz)
2. Layer 2: shared static assets for all bots
3. Layer 3: backend-specific shared assets
4. Layer 4: bot-specific static assets
5. Layer 5: final shared AGENTS.md

4. Tool Cache and Download Flow

To speed up cold starts and keep authentication stable:

• uv is loaded from an S3 cache first, then downloaded from a pinned release if needed.
• aws is downloaded from a pinned official release on each start to avoid drift.

Deployment SOP

Initialize the AWS Environment

If you need custom resource names or explicit VPC/subnet settings, edit aws-init.yaml first.

Then run:

ops/aws-init.sh

This detects or creates the ECS/IAM/VPC setup and writes ops/aws-env.yaml.

Validate the Configuration

ops/validate.sh

This checks required fields, CPU/memory combinations, capacity values, and image formatting.

Deploy a Bot

ops/deploy.sh <bot_name>

Example:

ops/deploy.sh ghost

Render Only

ops/deploy.sh ghost render

This writes .deploy-ghost.yaml without calling ecsctl.

Check Status

ops/status.sh ghost

Interactive Login in the Container

If a bot needs manual authentication after deployment, follow the backend-specific runtime user, not root.

Warning

ecsctl exec starts as root. If you log in while root owns the credentials, the runtime user may not be able to read the token.

backend	example bot	container user	HOME / agent_home
agy / kiro	ghost, spirit	agent	/home/agent
codex	devil	node	/home/node

Steps:

ecsctl exec openab-ghost bash
su - agent
agentauth

For Codex:

su - node
agentauth

Destroy a Bot

ops/aws-destroy.sh <bot_name> [options]

Options:

• --purge-state removes the S3 state backup
• --purge-secret removes the AWS Secrets Manager secret

Backup and Restore

• Sync Layer 2-5 only:

  ops/upload-layers.sh <bot_name>

• Restore runtime snapshot locally:

  ops/restore-layer1.sh <bot_name>

Run Tests

ops/tests/deploy/test-deploy.sh

Add a Bot

See docs/add_bot.md for the full flow. Minimal summary:

1. Create the AWS Secrets Manager secret for the bot.
2. Add the bot entry to bots.yaml.
3. Validate the config.
4. Deploy the bot.

Configuration Reference

aws-env.yaml example

cluster: openab-cluster
execution_role_arn: arn:aws:iam::<ACCOUNT_ID>:role/openab-task-execution-role
task_role_arn: arn:aws:iam::<ACCOUNT_ID>:role/openab-task-role
state_bucket: openab-state-bucket-<ACCOUNT_ID>
region: us-east-1

subnets: |
  - subnet-xxx
  - subnet-xxx

security_groups: |
  - sg-xxx

Valid Fargate CPU/Memory Combinations

CPU (units)	Memory (MB)
256	512, 1024, 2048
512	1024, 2048, 3072
1024	2048, 3072, 4096
2048	4096, 5120, 6144, 8192
4096	8192, 10240, 12288, 16384
8192	16384, 20480, 24576
16384	32768, 49152, 65536

Full reference: AWS Fargate VCPU and memory