0xjeffro/astroclaw

AstroClaw는 클라우드 네이티브 (cloud-native) AI 에이전트 프레임워크입니다. 이 프레임워크는 전통적인 장기 실행 모놀리식 (monolithic) 프로세스를 단일 책임 서버리스 (serverless) 컴포넌트로 분해하는 동시에, 관찰성 (observability), ID (identity), 보안 (security) 등을 위해 클라우드 플랫폼의 성숙한 생태계를 활용합니다.
기본적으로 AstroClaw 에이전트는 *보안 (secure)*이 뛰어나고, *확장 가능 (scalable)*하며, 유휴 상태일 때는 비용이 거의 *제로 (zero-cost)*에 가깝습니다.

전체 인프라 스택은 코드로서의 인프라 (IaC, Infrastructure as Code)로 정의되어 있으며, 단 한 번의 명령으로 배포할 수 있습니다.

🚧 아직 초기 알파 (alpha) 단계입니다. 베타 (beta)까지 약 8주 정도 남았습니다. 기능이 작동하지 않을 수 있으며, 훨씬 더 많은 기능이 추가될 예정입니다. 피드백을 환영합니다.

• Go 1.22+
• Docker (로컬 PostgreSQL용)
• OpenAI 또는 Anthropic API 키

# Anthropic 사용 시
ANTHROPIC_API_KEY=sk-ant-xxx go run .
# 또는 OpenAI 사용 시
...

임시 PostgreSQL 컨테이너가 자동으로 시작됩니다. 프로세스가 종료되면 데이터는 손실됩니다.

재시작 시에도 데이터를 유지하려면 기존 데이터베이스를 사용하세요:

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

CDK 배포는 현재 기본적으로 Aurora DSQL을 사용합니다. 향후 릴리스에서는 DSQL과 Aurora PostgreSQL 중에서 선택할 수 있는 설정 옵션이 추가될 예정입니다.

DSQL: 더 낮은 비용 (진정한 서버리스 방식의 요청당 과금, scale to zero). 대부분의 워크로드에 가장 적합합니다. Aurora PostgreSQL: 전체 PostgreSQL 기능 세트 (JSONB 컬럼, 외래 키 (foreign keys), 확장 기능 (extensions)). 벡터 검색 (pgvector) 또는 기타 고급 쿼리 기능이 필요한 경우 이를 선택하세요.

AWS CLI 설치

aws --version

CDK CLI 설치

pm install -g aws-cdk cdk --version

AWS 자격 증명 (credentials) 설정

aws configure aws sts get-caller-identity

API 키 설정을 안내하고 실행 명령어를 자동으로 생성해 주는 대화형 스크립트가 준비되어 있습니다:

./scripts/deploy.sh

또는 CDK 명령어를 직접 실행할 수도 있습니다:

cd deploy/aws/infra
npm install
cdk bootstrap # 계정/리전당 1회 수행: CDK가 자산을 업로드하고 스택을 배포하는 데 필요한 S3 버킷과 IAM 역할을 생성합니다. 이 계정/리전에서 이전에 부트스트랩(bootstrap)을 수행했다면 이 단계를 건너뛰세요.
...

배포가 완료되면 터미널 출력에 API URL이 표시됩니다.

API_URL=<API_URL> \
REPLY_URL=<REPLY_URL> \
WS_URL=<WS_URL> \
...

값들을 cdk deploy의 출력 결과로 교체하세요.

또는 명령어를 자동으로 생성해 주는 ./scripts/deploy.sh를 사용하세요.

API_URL=<API_URL> \
REPLY_URL=<REPLY_URL> \
WS_URL=<WS_URL> \
...

앱은 서로 다른 보안 경계(security boundaries)를 가진 두 가지 카테고리로 나뉩니다:

시스템 앱 (System Apps) (예: Chat, Calendar, Task)

• 프로젝트 유지 관리자(maintainers)가 관리합니다.
• 단일 Lambda 및 데이터베이스 연결을 공유합니다.
• 액세스 제어(Access control)는 코드 수준에서 강제됩니다: 각 앱은 자신의 db.Queries 패키지만 임포트(import)합니다. - 코드가 신뢰되므로 DbConnectAdmin(전체 데이터베이스 액세스)을 사용합니다.

제3자 앱 (Third-party Apps) (향후 예정)

• 외부 기여자(contributors)가 개발합니다.
• 각 제3자 앱은 전용 데이터베이스 역할(Role)을 가진 자체 Lambda에서 실행되며, 해당 앱이 생성/소유한 테이블로만 제한됩니다.
• IAM 권한: dsql:DbConnect (Admin 아님). - GRANT CONNECT TO '<lambda-role-arn>' WITH <app_role>를 통한 데이터베이스 역할 매핑. - 더 자세한 내용은 아직 계획 및 논의 단계에 있습니다.

이 섹션은 시스템 앱(System App) 개발을 다룹니다.
앱은 apps/ 디렉토리에서 개발됩니다. 각 앱은 자체 하위 디렉토리(예: apps/chat/)를 가지며 일반적으로 다음과 같은 구조를 갖습니다:

pkg/app/chat/
├── db/
│ ├── schema.sql # 이 앱을 위한 테이블 정의
...

• 앱 디렉토리와 db 하위 디렉토리를 생성합니다:
  pkg/app/<app-name>/db/

• db 디렉토리에 schema.sql을 작성합니다. 여기서 테이블을 정의합니다.

• db 디렉토리에 queries.sql을 작성합니다. sqlc 어노테이션(annotations)을 사용하여 SQL 쿼리를 정의합니다.

• sqlc.yaml에 앱의 db 설정을 추가합니다.

프로젝트 루트(project root)에 (기존 채팅 항목을 템플릿으로 사용하세요) -

atlas.hcl 파일의 src 리스트 아래에 앱의 스키마(schema) 경로를 추가하여 Atlas가 새로운 테이블을 인식할 수 있도록 합니다. -

프로젝트 루트에서 sqlc generate를 실행합니다. 이렇게 하면 db 디렉토리에 db.go, models.go, queries.sql.go 파일이 자동으로 생성됩니다. -

비즈니스 로직을 작성합니다: types.go, service.go 등. -

배포하기 전에 atlas migrate diff <migration_name> --env local을 실행하여 새로운 테이블에 대한 마이그레이션(migration) 파일을 생성합니다.

sqlc generate
atlas migrate diff <migration_name> --env local
go test -count=1 $(go list ./... 2>/dev/null | grep -v infra)

-count=1은 테스트 캐싱(caching)을 비활성화합니다. grep -v infra는 go test를 깨뜨리는 node_modules 내의 Go 템플릿 파일을 포함하고 있는 CDK 디렉토리를 제외합니다.

테스트는 testcontainers를 통해 PostgreSQL 컨테이너를 자동으로 시작합니다. 수동 설정은 필요하지 않습니다.

cd deploy/aws/infra
npx jest

CDK 스택(stack)을 변경했다면 스냅샷 테스트(snapshot test)가 실패할 것입니다. 차이점(diff)을 검토한 후 스냅샷을 업데이트하세요:

npx jest --updateSnapshot

배포된 모든 AWS 리소스를 삭제하려면:

cd deploy/aws/infra
cdk destroy

AstroClaw의 설계는 openclaw, picoclaw, opencode, 그리고 hermes-agent 프로젝트의 아이디어에서 영감을 받았습니다. 자신들의 작업물을 오픈 소스로 공개해 준 해당 프로젝트의 저자들에게 감사를 표합니다.