Local Mode추천비용 0

Local Governance Mode

본인 노트북/워크스테이션에서 직접 claude를 실행하면서 회사 거버넌스(예산 한도, IAM 권한 경계, 사용량 추적)는 그대로 적용받는 모드. EC2-per-user DevEnv를 띄우지 않으므로 인프라 비용이 들지 않습니다.

1. 전체 흐름

사용자 PC → Cognito → Dashboard → STS Issuer Lambda → per-user IAM role → Bedrock 호출 후 사용량이 로깅·집계·한도 평가되는 13 단계.

거래 흐름 (Local Governance Mode)

ASCII 버전 (mermaid 미지원 환경)

User PC (cc-bedrock-local CLI or /local page)
   ↓ 1. Cognito USER_PASSWORD_AUTH → JWT
   ↓ 2. POST /api/local/credentials (Bearer)
Dashboard (Next.js)
   ↓ 3. invoke STS Issuer Lambda (IAM auth)
STS Issuer Lambda
   ↓ 4. ensure_role + AssumeRole 1h
per-user IAM role (cc-on-bedrock-local-user-*)
   ↓ 5. read DENY#active
cc-on-bedrock-limits DynamoDB
   ↑ 6. STS credentials + limit_status
Dashboard → User PC
   ↓ 7. claude → Bedrock → invocation logging
   → CloudWatch Logs → subscription filter → tracker Lambda
   → cc-on-bedrock-usage DynamoDB (Streams)
   → token-limit-enforcer Lambda
   → 한도 초과 시 DENY#active + IAM Deny attach

2. CLI 사용법 — cc-bedrock-local

2.1 설치

원라인 설치bash

curl -fsSL https://cconbedrock-dashboard.<your-domain>/tools/cc-bedrock-local.sh \
  -o ~/.local/bin/cc-bedrock-local
chmod +x ~/.local/bin/cc-bedrock-local

# PATH (이미 있으면 생략)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2.2 설정 파일

~/.config/cc-bedrock/config (mode 600)bash

# 필수
DASHBOARD_URL=https://cconbedrock-dashboard.<your-domain>
COGNITO_REGION=ap-northeast-2
COGNITO_USER_POOL_ID=ap-northeast-2_xxxxxxxxx
COGNITO_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
EMAIL=you@company.com

# 선택
AWS_PROFILE_NAME=cc-bedrock
AWS_REGION=ap-northeast-2

# 모델 매핑 (Opus는 최신인 4.8로 두는 것을 권장)
ANTHROPIC_DEFAULT_SONNET_MODEL=global.anthropic.claude-sonnet-5
ANTHROPIC_DEFAULT_OPUS_MODEL=global.anthropic.claude-opus-4-8
ANTHROPIC_DEFAULT_HAIKU_MODEL=global.anthropic.claude-haiku-4-5-20251001-v1:0
CLAUDE_CODE_SUBAGENT_MODEL=global.anthropic.claude-sonnet-5

2.3 하루 사용 흐름

cc-bedrock-local login        # 비밀번호 → Cognito 인증
cc-bedrock-local claude       # 자동 refresh + claude 실행
cc-bedrock-local status       # 잔여 TTL + Deny 상태
cc-bedrock-local logout       # 토큰 캐시 삭제

2.4 서브커맨드 레퍼런스

명령	동작
`login`	비밀번호 → Cognito → 1h STS + refresh token
`refresh`	캐시된 refresh token으로 silent 재발급
`logout`	refresh + state 캐시 삭제
`status`	남은 TTL + 활성 Deny / 한도 상태
`claude [args]`	세션 확보 + 모델 env 주입 후 claude 실행
`set-model K=V`	sonnet / opus / haiku / subagent / pin 별칭으로 모델 ID 교체
`models`	현재 모델 매핑 + 추천 ID
`run -- <cmd>`	자격증명만 확보 후 임의 명령 실행
`config`	현재 설정 + 경로

3. Dashboard /local 페이지

CLI 없이 브라우저에서 직접 자격증명 발급:

3.1 첫 진입 화면

3.2 자격증명 발급 후

만료 시간이 1시간인 이유

AWS role chaining(한 role이 다른 role을 AssumeRole)은 어떤 설정에도 관계없이 세션을 최대 1시간으로 제한. CLI는 잔여 10분 미만이면 자동 refresh.

4. 토큰 사용량 위치

페이지	누가	내용
`/local`	본인	본인 + 부서 normalized token, Deny 상태
`/user`	본인	일일 토큰 사용량 카드 (EC2 모드 포함)
`/dept`	부서 관리자	멤버별 분포 + 부서 예산
`/admin/tokens`	Admin	1d/7d/30d 차트 + top users + 부서별 분해
`/analytics`	Admin	모델 비율 + 비용 트렌드 + 리더보드
`/monitoring`	Admin	실시간 세션 + Bedrock 호출

Admin Token Dashboard `/admin/tokens`

Normalized 토큰 가중치

1×

Haiku 4.5

~3.5×

Sonnet 5

~15×

Opus 4.8

5. Admin 컨트롤

`/admin/limits` — 한도 CRUD

API

GET    /api/admin/limits           — list active limits
POST   /api/admin/limits           — upsert (entity, key, period, maxNormalized)
DELETE /api/admin/limits?entity=USER&key=...&period=daily
POST   /api/admin/limits/reset     — force-reset + detach Deny policy

6. 트러블슈팅

login이 NotAuthorizedException으로 실패

원인: USER_PASSWORD_AUTH 미허용 App Client 또는 비밀번호 강제 변경 상태

조치: 브라우저 /login으로 1회 통과 후 cc-bedrock-local login

refresh 실패

원인: refresh token TTL 만료 (보통 30일)

조치: cc-bedrock-local login

claude가 AccessDeniedException

원인: 활성 Deny / 자격증명 만료 / 모델 ID 정책 누락

조치: cc-bedrock-local status 로 확인 → reset 요청 또는 refresh

/model 픽커에 "Custom"만 보임

원인: ANTHROPIC_MODEL 이 config에 세팅됨

조치: cc-bedrock-local set-model pin=

ValidationException: invalid model identifier

원인: region에 모델 미활성

조치: aws bedrock list-inference-profiles 로 활성 ID 확인 후 set-model

7. EC2 모드와의 차이

항목	EC2 DevEnv	Local Governance
PC 환경	code-server (browser)	본인 IDE/터미널
컴퓨팅	EC2 t4g.large	본인 PC
저장소	EBS 40–100 GB	본인 PC 디스크
세션	Hibernation ~5s resume	1h STS + auto-refresh
인프라 비용	EC2 + EBS 시간당	0
거버넌스	동일	동일