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.
- Go 1.22+
- Docker (for local PostgreSQL)
- OpenAI or Anthropic API key
# 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 .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.
-
Install AWS CLI
aws --version
-
Install CDK CLI
npm install -g aws-cdk cdk --version
-
Configure AWS credentials
aws configure aws sts get-caller-identity
We have an interactive script that walks you through API key setup and generates the run command automatically:
./scripts/deploy.shAlternatively, 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=trueAfter deployment, the API URL will be printed in the terminal output.
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.
API_URL=<API_URL> \
REPLY_URL=<REPLY_URL> \
WS_URL=<WS_URL> \
API_KEY=<API_KEY> \
go run main.goApps 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.Queriespackage. - 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
-
Create the App directory and db subdirectory:
pkg/app/<app-name>/db/ -
Write
schema.sqlin the db directory. Define your tables here. -
Write
queries.sqlin the db directory. Define your SQL queries with sqlc annotations. -
Add the App's db config to
sqlc.yamlin the project root (follow the existing chat entry as a template). -
Add the App's schema path to
atlas.hclunder thesrclist so Atlas knows about the new tables. -
Run
sqlc generatefrom the project root. This auto-generatesdb.go,models.go, andqueries.sql.goin your db directory. -
Write your business logic:
types.go,service.go, etc. -
Before deploying, run
atlas migrate diff <migration_name> --env localto generate migration files for your new tables.
sqlc generateatlas migrate diff <migration_name> --env localgo 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.
cd deploy/aws/infra
npx jestIf you changed the CDK stack, the snapshot test will fail. Review the diff, then update the snapshot:
npx jest --updateSnapshotTo destroy all deployed AWS resources:
cd deploy/aws/infra
cdk destroyAstroClaw'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.