Conduit

AI 코딩 에이전트를 위한 온프레미스 제어 평면. 엔지니어별 비용 귀속 · 엄격한 예산 · 송신 거버넌스 · 컨텍스트 부패 관찰 · 감사 준비된 내보내기 — 모두 VPC 내에서.

Conduit은 AI 코딩 에이전트(Claude Code, Cursor, Codex, Aider)와 이미 사용 중인 공급자(Anthropic, OpenAI, Bedrock, Azure — 또는 기존 LiteLLM / Portkey 배포) 사이에 위치합니다. 하나의 환경 변수로 도입 가능, 클라이언트 변경 불필요, 프롬프트와 완성은 절대 저장되지 않습니다.

[Claude Code / Cursor / Codex]
         │  ANTHROPIC_BASE_URL=https://conduit.yourco.dev
         ▼
[Conduit]  vk_live_… (엔지니어별)
         │  계량 · 예산 · 거버넌스 · 감사 · 컨텍스트 부패
         ▼
[LiteLLM / Portkey / 직접 공급자]
         │
         ▼
[Anthropic / OpenAI / Bedrock / Azure]

스크린샷

개요 — 지출, 캐시 절감, 토큰, 차단된 요청, 거버넌스 플래그를 한눈에 확인.

엄격한 예산 집행 — 한도 초과 시 공급자에 요청이 도달하기 전에 게이트웨이에서 402를 반환합니다.

송신 거버넌스 — AWS 키를 포함한 요청이 451로 차단됨; 카테고리만 기록되고, 값은 절대 기록되지 않습니다.

활동 — 각 요청은 고유한 상태를 가집니다: 성공 · 캐시 히트 · 속도 제한 · 모델 차단 · 예산 초과 · 거버넌스 차단.

설정 — 조직, 공급자 자격 증명, 팀, 예산, 가상 키에 대한 전체 CRUD.

이유

Bedrock / Vertex / Azure 프라이빗 엔드포인트 + no-train BAA는 벤더와의 채널을 해결합니다. 하지만 재무 부서에 4만 달러를 누가 썼는지 알려주지 않고, 송신 단에서 비밀을 잡아내지 않으며, 감사자에게 기록을 제공하지 않으며, 컨텍스트 부패가 토큰 예산을 어디서 소모하는지 보여주지 않습니다. Conduit이 채우는 격차입니다 — 프롬프트를 절대 보지 않으면서 말이죠.

제공되는 기능

• 엔지니어별 / 키별 / 모델별 비용 귀속 — 공유 API 키로는 구조적으로 생성할 수 없는 세부 분석.
• 엄격한 예산 + 모델 허용 목록 — 초과 시 fail-closed 402, 허용되지 않은 모델에 대해 명확한 403 (무음 다운그레이드 없음).
• 송신 거버넌스 — T1 비밀 스캔(API 키 / 토큰 / 프라이빗 키) + T2-lite 조직별 엔터티 허용 목록(고객 이름, 코드명, 거래 코드). 알림 → 블록으로 승격(한 번에 하나의 카테고리). 카테고리는 기록하되, 값은 절대 기록하지 않음.
• 컨텍스트 부패 패널 — 입력 토큰 크기별로 요청을 그룹화하고 비용 및 오류율 곡선을 표시합니다. Conduit은 측정만 하며, 프롬프트를 수정하지 않습니다(Anthropic의 프리픽스 캐시를 깨뜨리지 않음).
• 감사 준비된 내보내기 — 모든 요청을 메타데이터 전용 CSV/JSON 행으로 내보내기.
• 가상 키 — 엔지니어는 취소 가능한 대체 키를 보유하며, 실제 공급자 자격 증명은 게이트웨이에서 AES-256-GCM으로 암호화되어 노트북에 절대 닿지 않습니다.

빠른 시작

옵션 A — 서명된 릴리스 실행 (빌드 없음, 약 30초)

GHCR에서 최신 서명된 이미지를 가져옵니다(cosign verify로 확인 가능, 보안 태세 참조).

# 1. compose 파일 + env 템플릿 가져오기 (전체 클론 불필요)
curl -fsSL https://raw.githubusercontent.com/anee769/conduit/master/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/anee769/conduit/master/.env.example -o .env

# 2. 실제 마스터 암호화 키 생성
sed -i.bak "s|^MASTER_ENCRYPTION_KEY=.*|MASTER_ENCRYPTION_KEY=$(openssl rand -base64 32)|" .env && rm .env.bak

# 3. 서명된 이미지 가져오기 + 시작
docker compose --profile app pull
docker compose --profile app up -d

# 4. 마이그레이션 실행 + 가격 책정 데이터 시드 (1회)
docker exec conduit-gateway-1 pnpm --filter @finops/db db:migrate
docker exec conduit-gateway-1 pnpm --filter @finops/db seed-pricing

# → http://localhost:3000/setup 열기 → 조직 / 자격 증명 / 팀 / 가상 키 생성

up 전에 GATEWAY_IMAGE와 CONTROL_PLANE_IMAGE를 내보내서 특정 릴리스로 고정할 수 있습니다:

export GATEWAY_IMAGE=ghcr.io/anee769/conduit-gateway:v0.1.0
export CONTROL_PLANE_IMAGE=ghcr.io/anee769/conduit-control-plane:v0.1.0

옵션 B — 소스에서 빌드 (약 2분, 해킹용)

git clone https://github.com/anee769/conduit && cd conduit
cp .env.example .env
sed -i.bak "s|^MASTER_ENCRYPTION_KEY=.*|MASTER_ENCRYPTION_KEY=$(openssl rand -base64 32)|" .env && rm .env.bak

docker compose --profile app up -d --build
docker exec conduit-gateway-1 pnpm --filter @finops/db db:migrate
docker exec conduit-gateway-1 pnpm --filter @finops/db seed-pricing

모든 AI 도구에서 사용

export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=vk_live_…       # /setup에서 생성한 가상 키
claude                                       # 또는 cursor / codex / aider

처음부터 끝까지 전체 가이드는 INSTALL.md를 참조하세요.

이미 실행 중인 도구와 함께 작동

Conduit 비교

LiteLLM은 모델 별칭 및 라우팅에 탁월합니다 — Conduit은 보안 및 재무 팀이 요청한 계층을 추가합니다. Portkey는 기능이 가장 유사하지만, 거버넌스 + 온프레미스가 필요하면 클로즈드 소스 엔터프라이즈가 됩니다. Helicone은 관찰 전용입니다(토큰이 어디로 갔는지 알려주지만, 어디로 가는지 제어하지는 않습니다).

여기에 없는 것에 대한 솔직함

• 아직 SOC 2 / HIPAA / ISO 인증 없음. 없는 것을 있다고 주장하지 않습니다. Conduit은 귀하의 감사를 지원하고 아티팩트(SBOM, 서명된 이미지, 보안 백서, CAIQ-lite)를 제공하도록 설계되었습니다. 전체 태세는 SECURITY.md를 참조하세요.
• 아직 SSO / SAML / RBAC 없음 — 현재는 관리자 토큰 + 대시보드 비밀번호 게이트입니다. 구매자가 요청하면 로드맵에 올릴 예정입니다.
• Bedrock 스트리밍은 완료되지 않음(바이너리 AWS 이벤트 스트림 프레이밍). Bedrock 비스트리밍 /invoke는 작동합니다.
• Google Vertex 어댑터는 구축되지 않음.
• 전체 ML 기반 T2 거버넌스(엔터티 유형 추론)는 구축되지 않음 — 라이트 버전만 있음(운영자가 붙여넣은 엔터티 허용 목록). 파트너의 실제 트래픽을 기반으로 구축했으며, 그 전에는 아닙니다.

보안 태세

Conduit은 귀하의 클라우드 내에서 완전히 실행됩니다 — 요청 경로에 벤더가 없고, 전화 집 없음, 에어갭 가능. 백서(데이터 흐름 다이어그램, 저장되는 데이터, 암호화, fail-closed 인증, 컴플라이언스 태세, 위협 모델)는 SECURITY.md를 참조하세요.

• 컨테이너 이미지는 Sigstore cosign(키리스 OIDC)을 통해 서명되며 CycloneDX SBOM 증명과 함께 제공됩니다. 모든 v* git 태그에서 ghcr.io/anee769/conduit-gateway 및 ghcr.io/anee769/conduit-control-plane으로 릴리스됩니다(.github/workflows/release.yml 참조). 릴리스된 태그 확인:
  root@kitploit:~

  cosign verify ghcr.io/anee769/conduit-gateway:<tag> \
    --certificate-identity-regexp 'https://github.com/anee769/conduit' \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com
  

• bash scripts/sbom.sh로 언제든지 로컬에서 SBOM을 생성할 수 있습니다.
• 86개의 자동화된 테스트가 모든 PR에서 실행됩니다 — AWS SigV4 참조 벡터와 거버넌스 프라이버시 불변성(비밀/엔터티 값이 저장된 이벤트에 절대 나타나지 않음)을 포함합니다.

아키텍처 (간략히)

• apps/gateway — Hono on Node, 핫 패스 데이터 플레인. 빌드 단계 없음(tsx). 제로 의존성 ClickHouse 클라이언트 + ioredis.
• apps/control-plane — Next.js 15 / React 19 대시보드 + 관리 API + 첫 실행 /setup 마법사.
• packages/db — Drizzle 스키마, AES-256-GCM 암호화, 키 해싱, 가격 책정 + 예산.
• 저장소: Postgres (구성 / 신원 / 예산 / 가격 책정) + ClickHouse (추가 전용 usage_events) + Redis (캐시 + 속도 제한 + 실시간 예산 카운터).

요청 수명 주기(apps/gateway/src/routes/proxy.ts):

인증(vk) → 속도 제한 → 모델 허용 목록 → 예산 확인
         → 거버넌스 스캔(T1 비밀 + T2-lite 엔터티)
         → 캐시 조회 → 자격 증명 해결 → adapter.prepare()
         → 전달 + 스트림 분기(클라이언트는 변경되지 않음; 계량 브랜치는 백그라운드에서)

테스트

bash scripts/run-tests.sh             # 전체 유닛 + 라이브 시스템 스위트 (72개 테스트)
bash scripts/run-tests.sh --unit-only # 순수 로직, Docker 스택 불필요
pwsh scripts/run-tests.ps1            # Windows 동등 명령

CI (.github/workflows/ci.yml)는 모든 PR에서 두 작업을 모두 실행합니다 — 녹색일 때만 병합하세요.

기여

PR 환영합니다. 빠른 경로:

git checkout -b feat/my-change
# …
bash scripts/ci-local.sh              # CI에서 실행하는 것과 동일한 검사 실행
bash scripts/ci-local.sh --fast       # 타입체크 + 유닛만, Docker 없음
git push -u origin feat/my-change
gh pr create --base dev

브랜치 흐름: 기능 → dev → master. 병합 전에 CI 통과 필수.

라이선스

Apache License 2.0 — Kubernetes, Terraform, Kafka와 동일한 라이선스. 상업적으로 사용, 수정, 벤더에 포함 가능; 단, Conduit을 귀하의 고유 작업으로 주장하지 마십시오.

링크

• 사이트: getconduit.vercel.app
• 보안 태세: SECURITY.md
• LiteLLM과 함께 실행: docs/run-with-litellm.md
• 설치 가이드: INSTALL.md