AstroClaw: Cloud-Native AI Agent

AstroClaw is a cloud-native AI agent framework. It breaks down traditional long-lived monolithic processes into single-responsibility serverless components, while leveraging the cloud platform’s mature ecosystem for observability, identity, security, and more. Out of the box, AstroClaw agents are secure, scalable, and nearly zero-cost when idle.

The entire infrastructure stack is defined as code (IaC) and can be deployed with a single command.

 🚧 Still early alpha. ~8 weeks to beta. Things will break, and a lot more is coming. Feedback is welcome.

Prerequisites

• Go 1.22+
• Docker (for local PostgreSQL)
• OpenAI or Anthropic API key

Run Locally

# With Anthropic
ANTHROPIC_API_KEY=sk-ant-xxx go run .

# Or with OpenAI
OPENAI_API_KEY=sk-xxx go run .

A temporary PostgreSQL container starts automatically. Data is lost when the process exits.

To persist data across restarts, use an existing database:

DATABASE_URL="postgres://user:pass@localhost:5432/astroclaw" \
ANTHROPIC_API_KEY=sk-ant-xxx go run .

Database

CDK deployment currently defaults to Aurora DSQL. A future release will add a configuration option to choose between DSQL and Aurora PostgreSQL.

• DSQL: Lower cost (true serverless pay-per-request, scale to zero). Best for most workloads.
• Aurora PostgreSQL: Full PostgreSQL feature set (JSONB columns, foreign keys, extensions). Choose this if you need vector search (pgvector) or other advanced query capabilities.

Deploy to AWS

Prerequisites

1. Install AWS CLI bash aws --version

2. Install CDK CLI bash npm install -g aws-cdk cdk --version

3. Configure AWS credentials bash aws configure aws sts get-caller-identity

Deploy

We have an interactive script that walks you through API key setup and generates the run command automatically:

./scripts/deploy.sh

Alternatively, you can run CDK commands directly:

cd deploy/aws/infra
npm install
cdk bootstrap   # one-time per account/region: creates an S3 bucket and IAM roles that CDK needs to upload assets and deploy stacks. Skip this if you've bootstrapped this account/region before.
cdk deploy --parameters AnthropicApiKey=<YOUR-KEY> --parameters GenerateApiKey=true

After deployment, the API URL will be printed in the terminal output.

Run TUI

API_URL=<API_URL> \
REPLY_URL=<REPLY_URL> \
WS_URL=<WS_URL> \
API_KEY=<API_KEY> \
go run ./tui/

Replace the values with the outputs from cdk deploy. Or use ./scripts/deploy.sh which generates the command automatically.

Run CLI (minimal, for testing)

API_URL=<API_URL> \
REPLY_URL=<REPLY_URL> \
WS_URL=<WS_URL> \
API_KEY=<API_KEY> \
go run main.go

Development

• Installing or updating to the latest version of the AWS CLI
• Getting started with the AWS CDK

App development

Apps are divided into two categories with different security boundaries:

System Apps (e.g. Chat, Calendar, Task) - Maintained by the project maintainers. - Share a single Lambda and database connection. - Access control is enforced at the code level: each App only imports its own db.Queries package. - Use DbConnectAdmin (full database access) since the code is trusted.

Third-party Apps (future) - Developed by external contributors. - Each third-party App runs in its own Lambda with a dedicated database Role, restricted to only the tables it creates/owns. - IAM permission: dsql:DbConnect (not Admin). - Database role mapping via GRANT CONNECT TO '<lambda-role-arn>' WITH <app_role>. - More details are yet to be planned and discussed.

This section covers System App development. Apps are developed in the apps/ directory. Each App has its own subdirectory (e.g. apps/chat/) and commonly with the following structure:

 pkg/app/chat/
  ├── db/
  │   ├── schema.sql       # table definitions for this App
  │   ├── queries.sql      # SQL queries with sqlc annotations
  │   ├── db.go            # generated by sqlc: Queries struct, New(), WithTx()
  │   ├── models.go        # generated by sqlc: Go types matching table columns
  │   └── queries.sql.go   # generated by sqlc: type-safe Go functions for each query
  ├── types.go             # business types (Session, Message) and DB-to-domain conversion
  ├── service.go           # business logic (NewSession, Reply, etc.)
  ├── utils.go             # helper functions (type conversion between provider and chat)
  └── service_test.go      # integration tests

Creating a new App

1. Create the App directory and db subdirectory: pkg/app/<app-name>/db/

2. Write schema.sql in the db directory. Define your tables here.

3. Write queries.sql in the db directory. Define your SQL queries with sqlc annotations.

4. Add the App's db config to sqlc.yaml in the project root (follow the existing chat entry as a template).

5. Add the App's schema path to atlas.hcl under the src list so Atlas knows about the new tables.

6. Run sqlc generate from the project root. This auto-generates db.go, models.go, and queries.sql.go in your db directory.

7. Write your business logic: types.go, service.go, etc.

8. Before deploying, run atlas migrate diff <migration_name> --env local to generate migration files for your new tables.

Generate code after schema/query changes

sqlc generate

Generate migration files before deployment

atlas migrate diff <migration_name> --env local

Run tests

go test -count=1 $(go list ./... 2>/dev/null | grep -v infra)

-count=1 disables test caching. grep -v infra excludes the CDK directory which contains Go template files in node_modules that break go test.

Tests auto-start a PostgreSQL container via testcontainers. No manual setup needed.

CDK tests

cd deploy/aws/infra
npx jest

If you changed the CDK stack, the snapshot test will fail. Review the diff, then update the snapshot:

npx jest --updateSnapshot

Tear down

To destroy all deployed AWS resources:

cd deploy/aws/infra
cdk destroy

Acknowledgements

AstroClaw's design was inspired by ideas from the following projects: openclaw, picoclaw, opencode, and hermes-agent. We thank their authors for open-sourcing their work.