diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2001ce9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# CrowdSec Bunny Bouncer
+
+[CrowdSec](https://crowdsec.net) bouncer for [Bunny CDN](https://bunny.net). CrowdSec의 차단 목록을 Bunny CDN Edge Script와 연동하여 악성 IP를 CDN 엣지에서 차단합니다.
+
+## Architecture
+
+```
+CrowdSec LAPI ──stream──▶ bouncer.py ──libSQL──▶ Bunny Database
+                                                       │
+                                               Edge Script (index.ts)
+                                               onOriginRequest 에서
+                                               DB 조회 → 403 / pass
+```
+
+- **bouncer.py** — CrowdSec LAPI Streaming API를 폴링하여 차단 결정을 Bunny Database(libSQL HTTP API)에 동기화
+- **edge-script/index.ts** — Bunny CDN Edge Script 미들웨어. 모든 요청에 대해 DB를 조회하고 차단 IP면 403 응답
+- **setup.py** — Edge Script 코드를 Bunny CDN에 업로드 및 퍼블리시
+- **monitor.py** — Edge Script 사용량, CDN 트래픽/에러, WAF 이벤트 로그 모니터링
+
+## Features
+
+- CrowdSec Streaming API 기반 실시간 동기화 (기본 60초 간격)
+- CAPI(Community Blocklist) 포함 27,000+ IP 처리
+- Edge Script 인메모리 캐시 (정상 IP 5분, 차단 IP 1분 TTL)
+- Fail-open 설계 — DB 장애 시 요청 허용
+- 6시간 주기 전체 재동기화
+- 헬스체크 파일 기반 컨테이너 모니터링
+
+## Prerequisites
+
+- CrowdSec LAPI 접속 가능 (bouncer API 키 필요)
+- Bunny CDN 계정 + Pull Zone
+- Bunny Database (libSQL)
+- Bunny Edge Scripting 활성화
+- Python 3.12+
+- Docker/Podman (운영 환경)
+
+## Quick Start
+
+### 1. Bunny Database 및 Edge Script 준비
+
+Bunny 대시보드에서:
+1. Database 생성 → URL과 Token 기록
+2. Edge Scripting에서 스크립트 생성 → Script ID 기록
+3. Edge Script에 `BUNNY_DATABASE_URL`, `BUNNY_DATABASE_AUTH_TOKEN` 환경변수 설정
+4. Edge Script를 Pull Zone에 연결
+
+### 2. 환경변수 설정
+
+```bash
+cp .env.example .env
+# .env 파일 편집
+```
+
+| 변수 | 필수 | 설명 |
+|------|------|------|
+| `CROWDSEC_LAPI_URL` | O | CrowdSec LAPI 주소 |
+| `CROWDSEC_LAPI_KEY` | O | Bouncer API 키 |
+| `BUNNY_DB_URL` | O | Bunny Database libSQL URL |
+| `BUNNY_DB_TOKEN` | O | Bunny Database 인증 토큰 |
+| `SYNC_INTERVAL` | | 동기화 간격 초 (기본: 60) |
+| `INCLUDE_CAPI` | | CAPI 차단 목록 포함 (기본: true) |
+| `FULL_RESYNC_INTERVAL` | | 전체 재동기화 간격 초 (기본: 21600) |
+| `LOG_LEVEL` | | 로그 레벨 (기본: INFO) |
+| `BUNNY_API_KEY` | | Bunny API 키 (setup.py, monitor.py용) |
+| `BUNNY_SCRIPT_ID` | | Edge Script ID (setup.py용) |
+
+### 3. Edge Script 배포
+
+```bash
+python setup.py
+```
+
+### 4. Bouncer 실행
+
+```bash
+# Docker/Podman
+podman compose up -d
+
+# 또는 직접 실행
+pip install -r requirements.txt
+python bouncer.py
+```
+
+## Monitoring
+
+```bash
+# 기본 (최근 30일)
+python monitor.py
+
+# 기간 지정
+python monitor.py 7
+```
+
+출력 항목:
+- **Edge Script 사용량** — 월간 요청 수, CPU 시간, 무료 한도(25M) 대비 비율
+- **CDN 통계** — 총 요청, 캐시 히트율, 대역폭, 3xx/4xx/5xx 에러
+- **WAF / Bunny Shield** — Shield 상태, WAF 룰 현황, 이벤트 로그 요약 (공격 유형, IP, 국가별)
+
+## Edge Script Pricing
+
+| 항목 | 단가 |
+|------|------|
+| 요청 | $0.20 / 1M |
+| CPU 시간 | $0.02 / 1,000초 |
+
+처음 25M 요청은 무료. CDN 대역폭 비용은 별도.
+
+## License
+
+MIT