erans/lunaroute

---
.-- --.
./ () .-. .
...

당신의 AI 코딩 어시스턴트를 위한 최고의 친구

AI 코딩 어시스턴트를 위한 초고속 로컬 프록시(Proxy)로, 모든 LLM 상호작용을 완벽하게 가시화합니다. 설정이 전혀 필요 없으며, 밀리초 미만의 오버헤드(Overhead)와 강력한 디버깅 기능을 제공합니다.

eval $(lunaroute-server env)

이게 전부입니다! 이 단 하나의 명령어로 다음을 수행합니다:

• ✅ 백그라운드에서 LunaRoute 서버를 시작합니다.
• ✅ Claude Code를 설정합니다 (ANTHROPIC_BASE_URL 설정).
• ✅ Codex CLI를 설정합니다 (OPENAI_BASE_URL 설정).
• ✅ OpenAI와 Anthropic 형식을 동시에 모두 수용합니다.
• ✅ 모든 토큰(Token), 도구 호출(Tool call), 대화 내용을 추적합니다.

즉시 AI 어시스턴트와 코딩을 시작하세요. 두 API 모두 사용할 준비가 되었습니다!

서버를 수동으로 실행하는 것을 선호한다면:

# 터미널 1: 서버 시작
lunaroute-server
# 터미널 2: AI 도구를 서버로 연결
...

끝입니다. 구성해야 할 API 키도, 작성해야 할 YAML 파일도 없습니다. LunaRoute는 자동으로 다음을 수행합니다:

• ✅ OpenAI와 Anthropic 형식을 동시에 모두 수용합니다.
• ⚡ **이중 패스스루 모드 (Dual passthrough mode)**로 동작합니다 (정규화 오버헤드 제로).
• 🔑 기존 API 키를 사용합니다 (환경 변수 또는 클라이언트 헤더에서 가져옴).
• 📊 모든 토큰, 도구 호출, 대화 내용을 추적합니다.
• 🎯 모델 접두사(Prefix)를 기반으로 요청을 라우팅합니다 (gpt-* → OpenAI, claude-* → Anthropic).

눈을 감고 작업하는 것을 멈추세요. LunaRoute는 설정 없이 모든 상호작용을 기록합니다:

🔍 AI 대화 디버깅 - 어시스턴트가 정확히 무엇을 보내고 받는지 확인하세요.
💰 토큰 사용량 추적 - 세션별로 구분된 입력, 출력, 사고(Thinking) 토큰을 확인하세요.
🔧 도구 성능 분석 - 어떤 도구가 느린가요? 어떤 도구가 가장 많이 사용되나요?
📊 오버헤드 측정 - 느린 것이 LLM인가요, 아니면 당신의 코드인가요?
🔎 과거 세션 검색 - "AI가 지난주에 그 버그를 어떻게 해결했었지?"

# 말 그대로 단 하나의 명령만 실행하세요
eval $(lunaroute-server env)

즉시 얻게 되는 것들:

• ⚡ 이중 API 지원 - OpenAI /v1/chat/completions + Anthropic /v1/messages

• 🚀
  Passthrough mode (패스스루 모드) - 밀리초 미만(Sub-millisecond)의 오버헤드, 100% API 충실도 - 🔑
  Automatic auth (자동 인증) - 환경 변수 또는 클라이언트가 제공한 키 사용 - 📊
  Session tracking (세션 추적) - 심층 분석을 위한 SQLite 데이터베이스 + JSONL 로그 - 🎨
  Web UI (웹 UI) - http://localhost:8082에서 세션 탐색

• 🔄
  Background server (백그라운드 서버) - 분리된 프로세스(Detached process)로, 터미널을 닫은 후에도 계속 실행됨

작동 방식 (How it works):

$ lunaroute-server env
export ANTHROPIC_BASE_URL=http://127.0.0.1:8081
export OPENAI_BASE_URL=http://127.0.0.1:8081/v1
...

🔒 PII redaction (개인정보(PII) 비식별화) - 이메일, 주민등록번호(SSN), 신용카드, 전화번호를 자동 감지 및 비식별화 처리 - ⚡
0.1-0.2ms overhead (0.1-0.2ms 오버헤드) - 패스스루 모드에서 밀리초 미만의 프록시 지연 시간(Latency) - 🛡️
Zero trust storage (제로 트러스트 저장소) - 디스크에 기록된 후가 아니라, 기록되기 전에 비식별화 수행 - 🔐
Local first (로컬 우선) - 모든 데이터는 사용자의 기기에만 머무름

GitHub Releases에서 사용자의 플랫폼에 맞는 최신 릴리스를 다운로드하세요:

# Linux/macOS: 압축 해제 및 실행
tar -xzf lunaroute-server-*.tar.gz
chmod +x lunaroute-server
...

git clone https://github.com/erans/lunaroute.git
cd lunaroute
cargo build --release --package lunaroute-server
...

가장 빠르게 시작하는 방법 - 서버를 자동으로 시작하고 셸(Shell)을 구성합니다:

# 한 번의 명령으로 모든 것을 수행합니다!
eval $(lunaroute-server env)
# 이제 AI 도구들을 사용하세요 - 자동으로 구성되었습니다
...

발생하는 작업:

• 8081 포트에서 백그라운드로 서버 시작
  ANTHROPIC_BASE_URL을 http://127.0.0.1:8081로 설정
  OPENAI_BASE_URL을 http://127.0.0.1:8081/v1로 설정

• http://127.0.0.1:8082에서 Web UI 사용 가능

Custom port (사용자 정의 포트):

eval $(lunaroute-server env --port 8090)

Stop the server (서버 중지):

pkill -f "lunaroute-server serve"

서버를 직접 관리하는 것을 선호하는 경우:

# 터미널 1: LunaRoute 시작
lunaroute-server
# 터미널 2: 셸 구성
...

기본 제공 기능 (What you get out of the box):

✓ OpenAI provider 활성화됨 (API 키 불필요 - 클라이언트 인증 사용)
✓ Anthropic provider 활성화됨 (API 키 불필요 - 클라이언트 인증 사용)
📡 API 방언 (API dialect): 둘 다 (OpenAI + Anthropic)
...

더 많은 제어가 필요하신가요? 설정 파일 (config file)을 사용하세요:

# config.yaml으로 저장
host: "127.0.0.1"
port: 8081
...

lunaroute-server --config config.yaml

LunaRoute는 정규화 (normalization) 과정 없이 OpenAI와 Anthropic 형식을 동시에 수용합니다:

OpenAI 형식 /v1/chat/completions 에서

→ OpenAI로 라우팅 (routes)

Anthropic 형식 /v1/messages 에서

→ Anthropic으로 라우팅 (routes)

오버헤드 제로 (Zero overhead)

• 약 0.1-0.2ms의 지연 시간 (latency) 추가

100% API 충실도 (API fidelity)

• 확장된 사고 (extended thinking) 및 모든 응답 필드 보존

정규화 없음 (No normalization)

• 네이티브 API로 직접 전달 (direct passthrough)

이중 저장소를 통해 중요한 모든 사항을 추적하세요:

SQLite 데이터베이스 (Database) - 빠른 쿼리 및 분석:

SELECT model_used, COUNT(*), SUM(input_tokens), SUM(output_tokens)
FROM sessions
WHERE started_at > datetime('now', '-7 days')
...

JSONL 로그 (Logs) - 사람이 읽을 수 있는 전체 요청/응답 데이터:

# 실시간 세션 모니터링
tail -f ~/.lunaroute/sessions/$(date +%Y-%m-%d)/session_*.jsonl | jq
# 특정 콘텐츠 검색
...

종료 시 또는 API를 통해 상세한 분석 내용을 확인하세요:

📊 세션 통계 요약 (Session Statistics Summary)
═══════════════════════════════════════════════════════════════
Session: 550e8400-e29b-41d4-a716-446655440000
...

데이터가 디스크에 기록되기 전에 민감한 데이터를 자동으로 보호하세요:

session_recording:
  pii:
    enabled: true
...

변경 전: My email is john.doe@example.com and SSN is 123-45-6789

변경 후: My email is [EMAIL:a3f8e9d2] and SSN is [SSN:7b2c4f1a]

/metrics에서 24가지 메트릭 (metric) 유형 제공:

• 요청률 (Request rates) (전체, 성공, 실패)
• 지연 시간 히스토그램 (Latency histograms) (P50, P95, P99)
• 토큰 사용량 (Token usage) (입력/출력/사고)
• 도구 호출 통계 (Tool call statistics)
• 스트리밍 성능 (Streaming performance)

Grafana 대시보드에 최적화되어 있습니다.

세션을 탐색할 수 있는 내장 웹 인터페이스:

# http://localhost:8082 에서 자동으로 사용 가능
lunaroute-server

기능 (Features):

• 📊 필터링 및 검색 기능이 포함된 대시보드 (Dashboard)
• 🔍 타임라인 뷰가 포함된 세션 상세 정보 (Session details)
• 📄 원시 JSON 검사 (Raw JSON inspection)
• 📈 토큰 사용량 및 성능 분석 (Token usage and performance analytics)

env 명령은 서버를 백그라운드에서 시작하고 환경 설정을 위한 셸 (shell) 명령어를 출력합니다:

# 기본 사용법 - 기본 포트 8081에서 서버 시작
eval $(lunaroute-server env)
# 사용자 정의 포트
...

동작 과정:

• 서버가 백그라운드에서 시작됩니다 (터미널에서 분리됨)
• 현재 셸 (shell)에 환경 변수 (Environment variables)가 설정됩니다
• 터미널을 닫아도 서버는 계속 실행됩니다
• Claude Code와 Codex CLI 모두 즉시 구성됩니다

서버 중지:

pkill -f "lunaroute-server serve"

설정 파일 없이 동작 제어하기:

# API 방언 (API dialect) (기본값: both)
export LUNAROUTE_DIALECT=both # openai, anthropic, 또는 both
# 제공자 API 키 (선택 사항 - 클라이언트 헤더 사용 가능)
...

HTTP 클라이언트 성능 조정:

providers:
openai:
http_client:
...

또는 환경 변수 사용:

export LUNAROUTE_OPENAI_TIMEOUT_SECS=300
export LUNAROUTE_OPENAI_POOL_MAX_IDLE=64

자세한 내용은 연결 풀 구성 (Connection Pool Configuration)을 참조하세요.

LunaRoute는 속도 제한 (rate limits), 오류, 또는 서킷 브레이커 (circuit breaker) 이벤트로 인해 요청이 대체 제공자 (alternative providers)로 라우팅될 때 사용자에게 자동으로 알림을 보낼 수 있습니다.

기능 (Features):

• 🔔 LLM 응답을 통한 자동 사용자 알림
• 🎛️ 제공자별 맞춤 설정이 가능한 글로벌 On/Off 기능
• 🔄 교차 방언 페일오버 (cross-dialect failover) 지원 (OpenAI ↔ Claude)
• 📝 맞춤 설정을 위한 템플릿 변수 (Template variables)
• 🛡️ 멱등성 보장 (Idempotent) (중복 알림 없음)

구성 (Configuration):

routing:
provider_switch_notification:
enabled: true
...

템플릿 변수 (Template Variables):

${original_provider}

• 실패한 제공자 (Provider that failed)

${new_provider}

• 사용 중인 제공자 (Provider being used)

${reason}

• 일반적인 사유 (높은 수요, 서비스 문제, 유지보수)

${model}

• 모델 이름 (Model name)

전체 예시는 examples/configs/provider-switch-notification.yaml을 참조하세요.

문제: 당신의 AI 세션 비용이 5달러가 발생했지만, 그 이유를 모릅니다.

해결책: 세션 통계 (Session stats)를 확인하여 AI의 출력이 지나치게 장황했는지 확인하세요.

문제: AI 어시스턴트가 느리게 느껴집니다.

해결책: 세션 통계 (Session statistics)를 통해 Bash 명령어가 평균 850ms가 소요됨을 확인했습니다. 이를 최적화하세요!

문제: 팀이 하나의 프록시 (Proxy)를 공유하지만, 구성원마다 API 키가 다릅니다.

해결책: LunaRoute는 클라이언트가 제공하는 인증 (Auth)을 사용하므로, 공유 비밀값 (Shared secrets)이 필요하지 않습니다.

문제: 세션을 기록해야 하지만 개인정보 (PII)를 저장할 수 없습니다.

해결책: 자동 PII 삭제 (PII redaction) 기능을 활성화하세요. 모든 민감한 데이터는 디스크에 저장되기 전에 제거됩니다.

설정 예시 (Config Examples)

• 일반적인 시나리오를 위한 사전 구축된 설정들
  서버 README (Server README)

• 전체 설정 참조
  Claude Code 가이드 (Claude Code Guide)

• Claude Code 통합
  연결 풀 설정 (Connection Pool Configuration)

• HTTP 클라이언트 튜닝
  PII 탐지 (PII Detection)

• PII 삭제 상세 정보

• ✅
  Claude Code- 완전한 패스스루 (Passthrough) 지원, 설정 불필요 - ✅
  OpenAI Codex CLI- 자동 auth.json 통합. HTTP 및 WebSocket 전송 방식을 모두 지원합니다. WS 경로를 사용하려면 ~/.codex/config.toml에서 supports_websockets = true로 설정하세요 (LunaRoute가 WS를 종료하고 HTTP 파이프라인을 구동하며, 세션 기록, 마커 및 메트릭은 모두 동일하게 작동합니다). - ✅
  OpenCode- 표준 OpenAI/Anthropic API 호환성 - ✅
  커스텀 클라이언트 (Custom Clients)- OpenAI 또는 Anthropic API를 사용하는 모든 도구

추가 지연 시간 (Added latency): 0.1-0.2ms (P95 < 0.5ms)
메모리 오버헤드 (Memory overhead): 기본 ~2MB + 요청당 ~1KB
CPU 사용률 (CPU usage): 유휴 시 <1%, 100 RPS 시 <5%
API 충실도 (API fidelity): 100% (제로 카피 프록시 (Zero-copy proxy))

추가 지연 시간 (Added latency): 0.5-1ms (비동기, 논블로킹 (Non-blocking))
디스크 I/O (Disk I/O): 100ms마다 배치 쓰기 (Batched writes)
저장 공간 (Storage): 요청당 ~10KB (비압축), ~1KB (압축)

테스트 커버리지 (Test coverage): 73.35% (2042/2784 라인)
단위 테스트 (Unit tests): 544개 통과
통합 테스트 (Integration tests): 11개 테스트 파일
Clippy 경고 (Clippy warnings): 0

LunaRoute는 모듈형 Rust 워크스페이스 (Workspace)로 구축되었습니다:

┌─────────────────────────────────────────────────────────────┐
│ Claude Code / OpenAI Codex CLI / OpenCode │
└─────────────────────────┬───────────────────────────────────┘
...

주요 크레이트 (Key Crates):

lunaroute-core

• 타입 및 트레이트 (Types and traits)

lunaroute-ingress

• HTTP 엔드포인트 (OpenAI, Anthropic)

lunaroute-egress

• 커넥션 풀링 (Connection pooling)을 지원하는 프로바이더 커넥터 (Provider connectors)

lunaroute-session

• 기록 및 검색

lunaroute-pii

• PII (개인정보) 탐지 및 비식별화 (Redaction)

lunaroute-observability

• 메트릭 (Metrics) 및 상태 확인 (Health)

lunaroute-server

• 프로덕션 바이너리 (Production binary)

기여를 환영합니다! 다음과 같은 내용 모두 가능합니다:

• 버그 보고 및 수정
• 새로운 PII 탐지기
• 추가 메트릭
• 문서 개선
• 성능 최적화

가이드라인은 CONTRIBUTING.md를 참조해 주세요.

Apache License, Version 2.0 (LICENSE)에 따라 라이선스가 부여됩니다.

달 🌕이 밤길을 가는 여행자를 안내하듯, LunaRoute는 여러분의 AI 상호작용을 밝혀줍니다. 모든 요청, 모든 토큰, 모든 결정이 가시화되고 추적 가능해집니다.

가시성, 제어권, 그리고 성능을 원하는 개발자들을 위해 ❤️를 담아 만들었습니다.

여러분의 AI 코딩 어시스턴트에게 마땅히 누려야 할 가시성을 부여하세요.

lunaroute-server