AstroClaw: an AI agent framework built as serverless components

The decomposition argument, and what it buys you

AstroClaw is described as 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.

That first sentence is the architecture, and it is worth being precise about what it means for an agent, because an agent is exactly the kind of program that resists being broken up. A chat assistant is usually a long-running process that holds a session, keeps provider connections warm and reacts to messages as they arrive. AstroClaw's claim is that you can decompose that into functions, and that the cloud platform supplies what the decomposition takes away.

What it supplies is listed: observability, identity, security. In practice that means each component is a Lambda with its own IAM role, its own logs, its own metrics, and its own failure domain. A component that crashes is restarted without taking the agent with it. That is the argument for the approach and it is a reasonable one.

The second claim is about cost. Out of the box, AstroClaw agents are secure, scalable, and nearly zero-cost when idle. The nearly is doing work in that sentence. Serverless billing means an idle Lambda costs nothing, but a Lambda that is invoked often is priced per invocation and per duration, and an agent that polls a model provider or holds a websocket open is not idle by any definition.

The third claim is the deployment one. The entire infrastructure stack is defined as code and can be deployed with a single command.

That last point is the one with the most evidence behind it in the repository, because the CDK directory, the deploy script and the snapshot tests are all there to be read.

The primary language is Go, the licence is Apache-2.0, the default branch is main, and the homepage is docs.astroclaw.io. There are no GitHub releases, and the last push was on 2026-07-27, so the code is three months old as of October 2026.

The README is direct about the maturity, with a banner stating that the project is still early alpha, about eight weeks to beta, that things will break, and that a lot more is coming.

Running it locally against a throwaway Postgres

The local setup is designed to need almost nothing, which is the right instinct for a framework whose real deployment target is a cloud account.

The prerequisites are Go 1.22+, Docker for local PostgreSQL, and an 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, and the data is lost when the process exits. So the local run is a development loop, not a place to keep anything.

To persist data across restarts you point the process at an existing database.

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

The provider key is passed as an environment variable rather than configured in a file, and the database is selected by a single DATABASE_URL variable. Both are the conventional shape for a Go service, which tells you that the local and deployed configurations are the same code path with different environment.

The go.mod supports that reading. The dependencies include the Anthropic SDK at v1.38.0 and openai-go at v1.12.0, so both providers are first-class, along with the AWS Lambda Go runtime, the API Gateway management API for the websocket side, the gorilla/websocket library, and chi as the HTTP router. There is a separate TUI in the tui/ directory built on bubbletea, bubbles and lipgloss, so the same agent can be driven from a terminal.

The provider dependency is worth noting for cost reasons. The go.mod includes both the Anthropic SDK and openai-go, and the README documents both run modes, but the framework does not abstract away the difference between them, since the agent's behaviour depends on which provider is answering.

The database choice: DSQL by default, Aurora as the exception

The database decision is the one place where the framework makes a choice for you that has consequences, and the README explains it clearly.

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

So today there is no choice at the deployment layer. The two options are described so you know what you would be choosing between.

DSQL is the lower cost option, with true serverless pay-per-request and scale to zero, and the README calls it best for most workloads. Aurora PostgreSQL gives the full PostgreSQL feature set, including JSONB columns, foreign keys and extensions, and the README says to choose it if you need vector search with pgvector or other advanced query capabilities.

That distinction drives a lot of the design. A serverless database that scales to zero is what makes the nearly zero-cost idle claim plausible, and it is also a different database from the one most Go developers write against. The dependency list reflects this, with an Aurora DSQL connector for pgx alongside the regular jackc/pgx driver.

The README also names the future option explicitly, a configuration to choose between DSQL and Aurora PostgreSQL. Until it lands, a project that needs pgvector has two paths: deploy Aurora manually, or wait.

The application schema shows which side of that line the framework is designed for. Each App owns its own tables in its own schema.sql, and the queries are written with sqlc annotations. There is no mention of a shared cross-app table, which fits the isolation model that the app security boundaries require.

App security boundaries, and how the database access is scoped

The App development section divides apps into two categories with different security boundaries, and that division is the clearest statement of the framework's security model.

System Apps, with Chat, Calendar and Task named as examples, are maintained by the project maintainers. They share a single Lambda and database connection. Access control is enforced at the code level, with each App only importing its own db.Queries package. They use DbConnectAdmin, full database access, since the code is trusted.

Third-party Apps, marked as future, are 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 and owns. The IAM permission is dsql:DbConnect, not Admin. Database role mapping is done via a GRANT CONNECT TO with the app role, and the README says more details are yet to be planned and discussed.

The contrast is instructive. The current security boundary for system code is a Go import boundary, which is a convention rather than a control: if the code is trusted, it is allowed to reach the admin connection and the package structure is what keeps apps from colliding. The future boundary for third-party code is an IAM and database role boundary, which is an actual control enforced by the platform.

That the future design is the one with real enforcement is worth noting. When external contributors write code that runs in your account, an import convention is not a security model. A GRANT CONNECT plus a dsql:DbConnect permission on a role scoped to the app's own tables is.

The App structure reinforces it. Each App has its own db subdirectory with its own schema.sql, so there is no shared schema file for a third-party app to add a table to, and no shared queries file either.

The README is honest that this part is unfinished, and for an evaluator that matters more than the polished parts. A framework whose third-party story is still marked future with details yet to be planned is not yet ready to accept code from people you do not know.

The App layout, and the sqlc and Atlas workflow

The canonical App structure is shown in the README, and it is a conventional Go service layout with one unusual detail.

 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

The detail is that the db directory mixes hand-written and generated files, and the comments say which is which. schema.sql and queries.sql are yours. db.go, models.go and queries.sql.go are sqlc output. types.go and service.go are your business logic, and service_test.go holds integration tests.

That generated-code boundary is enforced by tooling rather than by discipline. The go.mod does not list sqlc, because it is invoked as a command, but the repository carries a sqlc.yaml at the root, and the README's creation steps require you to add the App's db config there, following the existing chat entry as a template.

The eight-step procedure for creating an App is where the workflow becomes clear. You create the App directory and db subdirectory. You write schema.sql to define your tables. You write queries.sql with sqlc annotations. You add the db config to sqlc.yaml. You add the App's schema path to atlas.hcl under the src list so Atlas knows about the new tables. You run sqlc generate, which auto-generates db.go, models.go and queries.sql.go. You write the business logic in types.go and service.go. And before deploying, you run atlas migrate diff with the migration name and the local env to generate migration files for the new tables.

So there are two generators in the loop, and they do different jobs. sqlc turns SQL into Go. Atlas turns schema differences into migration files.

sqlc generate

atlas migrate diff <migration_name> --env local

The atlas.hcl file at the repository root and the migrations/ directory are where the schema history lives.

Deploying to AWS, the CDK stack and the clients

The deployment path is AWS CDK, and the README lists three prerequisites before the deploy itself.

Install the AWS CLI and check the version.

aws --version

Install the CDK CLI through npm.

npm install -g aws-cdk
cdk --version

Then configure AWS credentials and confirm them.

aws configure
aws sts get-caller-identity

There are two ways to deploy. The recommended one is an interactive script that walks you through API key setup and generates the run command automatically.

./scripts/deploy.sh

The alternative is running the 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

The bootstrap step is the one people trip over. CDK needs an S3 bucket and IAM roles in the account and region before it can upload assets and deploy stacks, and the comment in the README says to skip it if you have bootstrapped that account and region before. The GenerateApiKey parameter is how the API key gets created as a stack output rather than typed in, and after deployment the API URL is printed in the terminal output.

Two clients are then documented. The TUI is the full client, run with the API URL, a reply URL, a websocket URL and an API key, and the CLI is described as minimal and for testing, running main.go with the same four values.

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

The four URLs point at different endpoints, which is a consequence of the serverless decomposition: the reply path and the websocket path are separate from the API path, and a client that wants streaming or asynchronous delivery talks to a different endpoint than one that just wants a request and response.

Tearing everything down is the matching CDK command.

cd deploy/aws/infra
cdk destroy

The deploy/ directory in the repository tree holds the AWS CDK code, and the scripts/ directory holds deploy.sh.

Testing, and the snapshot tests that guard the infrastructure

The test story is unusually complete for an early-alpha project, and it is worth looking at because it shows what the maintainer considers fragile.

The Go tests are run with a count of 1 and a package filter.

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

The two flags have documented reasons. The count of 1 disables test caching, so a test run always executes. The grep for infra excludes the CDK directory, which contains Go template files in node_modules that break go test. Both are the kind of detail that only appears when someone has been bitten by it.

Tests auto-start a PostgreSQL container via testcontainers, so there is no manual setup, and the testcontainers-go postgres module is in the dependency list at v0.42.0.

The CDK side has its own test suite.

cd deploy/aws/infra
npx jest

And the failure mode is described: if you changed the CDK stack, the snapshot test will fail, and you review the diff and then update the snapshot with npx jest --updateSnapshot.

That is the most valuable test in the repository for an infrastructure project. A snapshot of the synthesised CloudFormation template catches an accidental change to IAM permissions, a changed Lambda configuration or a new resource, which is exactly the kind of change that is easy to make by accident and expensive to notice later. Reviewing a diff and then accepting it is the right workflow, and having the diff forced into a review is the point.

The README also records where the design came from, with acknowledgements to openclaw, picoclaw, opencode and hermes-agent, thanking their authors for open-sourcing their work. AstroClaw is described as inspired by ideas from those projects.

There is also a skills/ directory and a websites/ directory at the repository root, which are not explained in the README.

Where AstroClaw is the wrong choice

There are three limits, and the first is the maturity statement at the top of the README.

The first is that it is early alpha. The README says so in a banner, says about eight weeks to beta, and says things will break and a lot more is coming. That is an unusually explicit warning, and it should be taken at face value. An agent framework that splits into Lambdas has a lot of moving parts: API Gateway, Lambda, a websocket management API, a serverless database, IAM roles, and a provider API that bills per token. When something breaks in that stack at three in the morning, the debugging session will involve all of them.

The second is the AWS specificity. The CDK deployment, the Lambda runtime, the DSQL default, the dsql:DbConnect IAM permission, the GRANT CONNECT role mapping, the API Gateway management API for websockets, and the testcontainers setup all point one way. There is a portable core, since the local run is a plain go run against Postgres, but the infrastructure story is AWS only. A team on GCP or Azure would be deploying the Go service themselves with no IaC to start from.

The third is that the third-party app story does not exist yet. The README marks it future, and says more details are yet to be planned and discussed. The current model for system apps relies on code-level access control through Go package imports, which is a convention that works because the code is trusted and written by the same maintainers. That is not a model for accepting code from people you do not know, and anyone whose plan involves community-contributed apps is building on a part that does not exist.

There is also a quieter limitation in the cost story. Nearly zero-cost when idle is true for a Lambda that is not invoked. An agent with a websocket connection held open, or one polling a provider, or one running a scheduled job, is invoked continuously. The README does not break down the cost model, and the difference between a batch-style agent and a streaming one is the difference between a rounding error and a line item.

The honest alternatives are different in kind. For a self-hosted agent, a single long-running process, a container on a small VM and a Postgres database is less machinery and easier to reason about, at the cost of paying for the server whether or not it is busy. For a serverless agent without the IaC, an established framework with a deploy target you already use, plus a database you already run, is faster to stand up and easier to hand over.

What AstroClaw offers that those do not is the specific combination of per-component isolation, a single-command infrastructure definition, and a schema-per-app structure that makes the security model legible. If you are building a multi-component agent on AWS and intend to keep it that way, that combination is worth an alpha framework. If you want a working agent this week, the alpha banner is the reason to look elsewhere.

Editorial conclusion

Adopt AstroClaw only if you are building an agent that must run as discrete serverless components on AWS and want the infrastructure defined as code from the start, since that is the design the whole repository is built around. Do not adopt it for anything time-sensitive, because the README calls it early alpha with things expected to break. Before you start, confirm you can live with Aurora DSQL as the default database, and note the last push was on 2026-07-27 with no tagged releases.

Frequently asked questions

Official sources

1. 0xjeffro/astroclaw on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README