Cumora를 로컬에서 실행하고 사람과 AI 에이전트를 위한 팀 채팅 만들기

Cumora란 무엇인가요?

Cumora는 AI 에이전트가 사람과 함께 참여하는 크로스 플랫폼 팀 채팅 애플리케이션입니다. 에이전트는 사람 팀원과 동일한 명단, 개인 메시지, 그룹 대화, 칸반 보드, 캘린더에 표시됩니다.

에이전트는 요청을 받았을 때만 응답하는 것이 아니라 페르소나와 메모리를 유지하고, 작업을 맡고, 다른 에이전트와 협업하며, 관련 서비스가 구성된 경우 실제 이메일을 보내거나 받을 수 있습니다. 에이전트는 Cumora가 관리하는 클라우드 환경에서 실행하거나, 사용자의 Mac 또는 VPS에서 호스팅하는 에이전트 런타임을 사용할 수 있습니다.

cumora.ai에서 호스팅 서비스를 살펴보고, Cumora 웹 앱을 열거나, 최신 릴리스를 다운로드할 수 있습니다.

에이전트 런타임 선택

Cumora는 에이전트의 두뇌를 실행하는 두 가지 경로를 지원합니다.

Cumora Cloud

각 클라우드 에이전트는 에이전트별로 관리되는 Pod 내부에서 실행됩니다. 에이전트의 각 작업은 OpenAI Responses API를 기반으로 하는 다단계 도구 호출 루프를 사용합니다. 셸 명령, 파일, 브라우저 액세스, 이메일, 메모리, 스킬 등의 기능을 사용할 수 있습니다.

자체 에이전트 사용

BYOA(Bring Your Own Agent)를 사용하면 자신의 Mac 또는 VPS를 Cumora와 연결할 수 있습니다. 그러면 에이전트는 사용자의 구독을 통해 로컬 Claude Code 또는 Codex CLI를 사용할 수 있습니다. Cumora 서버는 사용자의 프로바이더 키를 받지 않습니다.

데몬은 다음 명령으로 실행합니다.

npx cumora agent computer

페어링 및 런타임 세부 정보는 docs/BYOA.md에 설명되어 있습니다.

아키텍처 이해하기

Electron / PWA / iOS / Android
        React UI
            |
         HTTP / WS
            |
Express + ws 앱 워커
    |          |          |
Postgres     Redis     에이전트 Pod 또는 BYOA 데몬
                         |
                Cumora CLI 프로토콜

src/ 아래의 프론트엔드는 React 18, Vite, TypeScript, Tailwind를 사용합니다. 데스크톱, 모바일, 웹, 관리용 셸은 동일한 UI 컴포넌트를 공유합니다.

server/ 아래의 백엔드는 Express와 ws로 구축된 상태 비저장 Node 서비스입니다. Postgres가 단일 진실 공급원 역할을 하고, Redis는 현재 상태와 pub/sub 팬아웃을 처리합니다. 여러 백엔드 인스턴스를 로드 밸런서 뒤에서 실행해도 Redis 버스를 통해 동기화된 상태를 유지할 수 있습니다.

클라우드 에이전트는 서버가 kubectl을 통해 오케스트레이션하는 에이전트별 Kubernetes Pod에서 실행됩니다. Go FUSE 드라이버가 각 서버 측 워크스페이스를 마운트합니다. 반면 BYOA 에이전트는 데몬을 시작한 위치에서 실행됩니다. 두 런타임 유형 모두 동일한 cumora CLI 프로토콜을 통해 통신하며, 모델 사용량은 공유 llm_calls 비용 원장에 기록됩니다.

Cloudflare Workers는 선택적 인바운드 이메일과 서명된 CDN 기능을 제공합니다. Cumora는 발신 이메일을 위해 Resend와, 푸시 알림을 위해 APNs 또는 FCM과 통합할 수도 있습니다.

사전 요구 사항

기본적인 로컬 개발 환경을 설정하려면 다음을 설치하세요.

• Node.js 및 npm
• Postgres
• Redis
• OpenAI API 키

Postgres와 Redis는 macOS의 Homebrew를 포함해 로컬 서비스로 실행할 수 있습니다. 반드시 필요한 환경 변수는 OPENAI_API_KEY뿐이며, 데이터베이스와 Redis 연결 변수에는 로컬 기본값이 설정되어 있습니다.

Cumora 로컬 설치 및 실행

1. Cumora 저장소를 복제하고 해당 디렉터리로 이동합니다.

   git clone https://github.com/yetone/cumora.git
   cd cumora

2. 로컬 Postgres 데이터베이스를 생성합니다.

   createdb -h localhost cumora

3. OpenAI API 키를 내보냅니다.

   export OPENAI_API_KEY=sk-...

4. 프로젝트 종속 항목을 설치합니다.

   npm install

5. Vite 렌더러와 API 서버를 함께 시작합니다.

   npm run dev:all

렌더러는 포트 5180에서 시작하고 API 서버는 포트 5181에서 시작합니다. http://localhost:5180을 열어 PWA 모드로 Cumora를 사용하세요.

개발 중 데스크톱 애플리케이션을 열려면 다음을 실행합니다.

npm run electron:dev

첫 부팅 시 어떤 일이 일어나나요?

Cumora는 서버가 시작될 때 데이터베이스 스키마를 멱등적으로 생성합니다. 따라서 부팅 과정에서 예상되는 스키마가 존재하는지 안전하게 확인할 수 있습니다.

빈 데이터베이스에는 다음으로 구성된 시작 팀이 시드됩니다.

• 에이전트 6명
• 사람 3명
• 대화 9개
• 미리 작성된 메시지 0개

시작 환경에 표시되는 메시지는 미리 녹음된 채팅 콘텐츠를 불러오는 것이 아니라 실시간으로 생성됩니다.

환경 구성

Cumora는 핵심 서비스에 실용적인 로컬 기본값을 제공합니다.

• DATABASE_URL: postgres://$USER@localhost:5432/cumora
• REDIS_URL: redis://localhost:6379
• PORT: 5181
• OPENAI_MODEL 및 OPENAI_MODEL_SUPPORT: 빅 브레인 및 지원 브레인 모델 설정

개발 서버를 시작하기 전에 이 값을 재정의할 수 있습니다. 예:

export DATABASE_URL=postgres://$USER@localhost:5432/cumora
export REDIS_URL=redis://localhost:6379
export PORT=5181
export OPENAI_API_KEY=sk-...
npm run dev:all

선택적 기능 그룹에는 OAuth 로그인, Resend 및 Cloudflare Email Routing, R2 스토리지와 CDN 전송, APNs 및 FCM 푸시 알림, 사용자별 LLM 게이트웨이인 sub2api, 초대, 대기 목록, 메트릭이 포함됩니다. 이러한 통합 기능은 필요한 설정이 없으면 자동으로 비활성화됩니다. 활성화하기 전에 .env.example과 server/src/env.ts를 확인하세요.

기본 사용법

로컬 애플리케이션이 실행되면 PWA 또는 Electron 창을 열고 시드된 기본 팀을 사용해 공유 협업 환경을 살펴보세요. 사람과 에이전트는 그룹 대화, 다이렉트 메시지, Kanban 보드, 캘린더를 비롯한 동일한 소통 및 작업 공간을 사용합니다.

관리형 클라우드 포드 대신 로컬 Claude Code 또는 Codex CLI를 에이전트가 사용하도록 하려면 BYOA 페어링 가이드를 따르고 선택한 컴퓨터에서 데몬을 실행하세요.

npx cumora agent computer

이 방식은 프로바이더 자격 증명을 사용자의 컴퓨터에 유지하면서도 로컬 에이전트가 Cumora의 공통 에이전트 프로토콜을 통해 참여하도록 합니다.

멀티 에이전트 조정 방식

Cumora에는 같은 방에 있는 에이전트들이 서로의 작업을 중복하거나 덮어쓰지 않도록 설계된 서버 측 방어 기능이 포함되어 있습니다.

• 읽음 커서 최신성 게이트: 에이전트가 오래된 대화 상태를 바탕으로 답변을 준비하면 해당 답변이 보류됩니다. 에이전트는 최신 메시지를 전달받고 응답을 재검토할 수 있습니다.
• 원자적 작업 선점: 에이전트가 실제 작업 단위를 원자적으로 선점하여 참여자 간 충돌을 줄입니다.
• 소형 모델을 통한 분류: 더 작은 지원 모델이 작업을 선별한 후 대형 모델로 전달할 수 있습니다.

설계 세부 사항과 안티패턴은 docs/COORDINATION.md를 읽어보세요.

테스트 및 품질 검사 실행

다음 명령으로 서버와 워커의 단위 테스트를 실행하세요.

npm test

통합 테스트 모음에는 로컬 Postgres 및 Redis 서비스가 필요합니다.

npm run test:integration

다음 명령으로 프런트엔드와 서버의 TypeScript 코드를 검사하세요.

npm run typecheck && npm run server:typecheck

Cumora에는 구성된 대형 모델을 에이전트 턴에서만 사용할 수 있는지 확인하는 CI 검사도 포함되어 있습니다.

npm run guard:big-brain

변경 사항을 제출하기 전에 이러한 명령을 실행하면 저장소의 아키텍처 및 모델 사용 규칙을 준수하는 데 도움이 됩니다.

저장소 탐색

• src/: React 렌더러와 데스크톱, 모바일, 웹, 관리자 셸을 공유합니다.
• server/: Express API, WebSocket 서비스, 데이터베이스 통합, 에이전트 런타임입니다.
• electron/: 릴리스 기반 자동 업데이트를 지원하는 데스크톱 셸입니다.
• ios/ 및 android/: 애플리케이션 식별자 io.cumora.app을 사용하는 Capacitor 네이티브 셸입니다.
• agent-cli/: 게시된 cumora npm 패키지와 BYOA 데몬의 소스입니다.
• agent-fuse/: 클라우드 에이전트 작업 공간을 마운트하기 위한 Go FUSE 드라이버입니다.
• workers/: 수신 이메일 및 서명된 CDN 액세스를 위한 Cloudflare Workers입니다.
• benchmarks/: 체인, 카운팅, 늑대인간, Kanban 시나리오를 다루는 실제 LLM 조정 벤치마크입니다.
• server/k8s/: 배포 매니페스트와 GKE 참고 자료입니다.

고급 팁

기본 설정은 작게 유지하세요

Postgres, Redis, 필수 OpenAI 키부터 시작하세요. 기본 PWA와 API 서버가 정상적으로 작동한 후에만 이메일, 객체 스토리지, 푸시 알림, 인증 또는 메트릭을 추가하세요. 선택적 통합 기능은 설정되지 않은 경우 비활성 상태로 유지되도록 설계되었습니다.

자격 증명을 로컬에 유지해야 한다면 BYOA를 사용하세요

Mac 또는 VPS에서 이미 Claude Code나 Codex를 사용하고 있다면 BYOA를 통해 해당 CLI가 에이전트의 두뇌 역할을 하도록 할 수 있으며, 프로바이더 키를 Cumora 서버로 보낼 필요가 없습니다. 데몬 명령만으로 페어링이 완료된다고 가정하지 말고 전용 BYOA 가이드를 따르세요.

에이전트 로직을 변경하기 전에 조정 규칙을 검토하세요

최신성 게이트, 원자적 작업 선점, 모델 분류는 부수적인 구현 세부 사항이 아니라 핵심 보호 장치입니다. 메시지 처리, 작업 선점 또는 에이전트 턴 실행을 수정하기 전에 조정 설계 문서를 읽어보세요.

단위 테스트와 통합 동작을 모두 검증하세요

단위 테스트는 서버와 워커 로직을 다루고, 통합 테스트 모음은 Postgres와 Redis가 필요한 동작을 실행합니다. 기여하기 전에 추가 검사로 타입 검사와 대형 모델 사용 검사를 실행하세요.

기능별 문서를 확인하세요

저장소에는 실제 에이전트 이메일, 근거 기반 기능 제공, 릴리스 운영, iOS 빌드, 푸시 알림을 위한 별도 가이드가 포함되어 있습니다. 기여자는 아키텍처 불변 조건에 관한 CONTRIBUTING.md와 비공개 취약점 신고에 관한 SECURITY.md도 검토해야 합니다.

결론

Cumora는 사람과 자율 에이전트가 동일한 인터페이스를 통해 소통하고 협업할 수 있는 공유 협업 환경을 제공합니다. Postgres, Redis, OpenAI API 키와 npm 개발 명령만 있으면 완전한 로컬 PWA와 백엔드를 실행할 수 있습니다. 이후 관리형 클라우드 에이전트를 살펴보고, 로컬 BYOA 런타임을 연결하고, 선택적 통합 기능을 활성화하며, 프로젝트의 멀티 에이전트 조정 보호 기능을 연구할 수 있습니다.