RoboCo

AI Agents Company - 26개의 AI 에이전트와 1명의 인간 CEO로 구성된 가상 조직으로, 완전한 소프트웨어 개발 인력으로 작동하도록 설계되었습니다.

26개의 에이전트 = Intake + Secretary + PR Reviewer + DevOps + 이사회(3) + 메인 PM + 세 개의 6개 에이전트 셀(18). 에이전트는 기본적으로 Anthropic Claude 또는 xAI Grok, OpenAI Codex, Google Gemini, Moonshot Kimi K3에서 실행됩니다 (각각 자체 공식 CLI와 구독 필요하며, 측정형 API 키는 사용하지 않습니다) — 구성 섹션의 제공업체 참고 사항을 참조하십시오.

작동 방식

당신이 회사에 작업을 맡기면, 이 작업은 실제 빌드 → 검토 → 문서화 → 병합 파이프라인을 거쳐 당신에게 승인을 위해 돌아옵니다.

한 전체 루프는 간단히 말해 다음과 같습니다:

1. 당신이 이사회에 작업을 요청하면 — 그들이 이를 검토합니다. 제품 오너(Product Owner)와 마케팅 책임자(Head of Marketing)가 당신의 요구 사항을 요구사항 및 승인 기준(acceptance criteria)으로 바꿉니다.
2. 당신이 승인하면 — 메인 PM이 작업을 시작합니다. 알림이 당신의 승인 및 시작(Approve & Start) 결정을 요청하며, 승인하면 메인 PM은 이를 셀별 하위 작업으로 나눕니다.
3. 각 셀의 PM이 개발자들(UX/UI, 프론트엔드, 백엔드)에게 위임하고, 지원하며, 트리아지합니다.
4. 개발자들이 빌드하고, QA가 검증 및 게이트를 설정하며, 문서 작성자들이 기록을 유지합니다.
5. 셀 PM들이 자신들의 PR(Pull Request)을 메인 PM의 브랜치로 병합합니다.
6. 메인 PM이 최종 PR을 열고 당신에게 "완료되었습니다!"라고 알립니다 — 당신은 이를 승인하고 병합하거나, 재작업을 위해 되돌려 보냅니다. (오직 당신만이 master에 병합할 수 있습니다.)

— 완전한 순환 과정 —

스크린샷과 함께 전체 워크스루를 확인하세요 →

또는 전체 패널 워크스루(비디오)를 시청하세요 →

프로젝트 구조

roboco/
├── roboco/	# 메인 Python 패키지
│   ├── api/	# FastAPI 라우트 및 스키마
...

RoboCo 실행하기

Docker와 Docker Compose, 그리고 호스트에 Claude Code 인증 디렉토리(~/.claude)가 필요합니다(오케스트레이터로 마운트되어 에이전트들이 모델에 접근할 수 있도록 함). .env.example을 복사하여 .env로 만들고 최소한 ROBOCO_ENCRYPTION_KEY와 ROBOCO_AGENT_AUTH_SECRET를 설정하세요(해당 파일에서 각각 생성하는 방법을 확인할 수 있습니다). 어떻게 시작하든, 전체 회사는 하나의 원점인 **http://localhost:3000**에서 접근 가능합니다.

선택 사항 — Claude 대신 xAI Grok에서 에이전트 실행. RoboCo는 SuperGrok 구독으로 인증된 xAI의 공식 grok CLI를 사용하여 에이전트를 생성할 수 있습니다(사용량 기반 API 키 없음). 호스트에서 한 번 grok login을 실행하고, ROBOCO_HOST_GROK_DIR을 결과로 나온 ~/.grok에 지정하여 Grok 에이전트가 마운트하도록 합니다. 오케스트레이터가 ~6시간 동안 토큰을 자동으로 새로 고쳐줍니다. .env.example의 Grok 블록(ROBOCO_HOST_GROK_DIR, ROBOCO_GROK_AGENT_IMAGE, ROBOCO_GROK_CLI_MODEL, ROBOCO_GROK_REASONING_EFFORT)을 참고하세요.

선택 사항 — Claude 대신 Moonshot Kimi K3에서 에이전트 실행. RoboCo는 Kimi 구독으로 인증된 Moonshot의 공식 kimi (kimi-code) CLI를 사용하여 에이전트를 생성할 수 있습니다(OAuth 디바이스 코드 로그인, 사용량 기반 API 키 없음). 호스트에서 한 번 kimi login을 실행합니다. ROBOCO_HOST_KIMI_DIR은 결과로 나온 ~/.kimi-code를 가리키며(선택 사항 — 기본값이 합리적임), 모든 Kimi 에이전트가 호스트의 하나의 순환 자격 증명 체인을 공유하기 때문에 읽기/쓰기로 마운트됩니다. .env.example의 Kimi 블록(ROBOCO_HOST_KIMI_DIR, ROBOCO_KIMI_CLI_MODEL — 기본값 kimi-code/k3, kimi-code/kimi-for-coding이 더 저렴한 옵션임)을 참고하세요.

선택 사항: Nebius Token Factory에서 에이전트 실행하기 (NVIDIA Nemotron). RoboCo는 전체 플릿을 Nebius Token Factory를 통해 라우팅할 수 있습니다. 이곳은 60개 이상의 오픈 모델(NVIDIA Nemotron, DeepSeek, Qwen, Llama)을 하나의 측정 가능한 API 키 뒤에서 제공하는 OpenAI 호환 추론 API입니다. 호스트 로그인이나 환경 변수 설정이 필요하지 않습니다: Settings -> AI Routing -> Nebius API key 패널에 키를 저장하고 (서버 측 Fernet 암호화로 저장됨), Nebius 모드 버튼을 클릭하면 됩니다. 플릿 전체의 기본 모델은 NVIDIA의 오픈 소스 Nemotron 3 Super (nvidia/nemotron-3-super-120b-a12b)입니다. 검색 가능한 피커를 사용하면 나머지 Token Factory 카탈로그로 범위를 좁힐 수 있습니다. 에이전트는 opencode CLI에서 속도 제한 파킹 및 에이전트별 토큰/비용 측정을 통해 생성됩니다. 이 경로는 Nebius x NVIDIA 해커톤에서 평가된 내용이며, HACKATHON.md를 참조하여 당시 구축한 내용을 확인하세요.

옵션 1 — 사전 빌드된 이미지 실행하기 (가장 빠름)

모든 릴리스는 GitHub Container Registry와 Docker Hub 모두에 모든 RoboCo 이미지를 게시하므로, 아무것도 빌드할 필요 없이 전체 스택을 실행할 수 있습니다. 다음 명령 한 줄로 실행됩니다:

git clone https://github.com/rennf93/roboco.git && cd roboco
make quickstart                    # make가 없다면 ./scripts/bootstrap.sh를 직접 실행하세요

make quickstart (scripts/bootstrap.sh)는 반복 실행이 가능합니다 (idempotent) — 언제든지 다시 실행해도 안전합니다. 이 스크립트가 하는 일은 다음과 같습니다:

cp .env.example .env              # 누락된 경우에만 — 기존의 .env 파일은 절대 건드리지 않습니다
# ...ROBOCO_ENCRYPTION_KEY / ROBOCO_AGENT_AUTH_SECRET / ROBOCO_PANEL_AGENT_TOKEN을 제자리에 생성합니다

...

참고: ROBOCO_PANEL_AGENT_TOKEN은 상시 CEO 자격 증명(credential)입니다 — 나중에 클라우드 인증을 설정할 경우 ('.env.example' 참조) 비워두세요.

새로운 .env 파일에는 ROBOCO_HOST_PROJECT_DIR와 ROBOCO_HOST_DATA_DIR가 체크아웃 위치로 고정됩니다. 이들은 오케스트레이터(orchestrator)가 생성되는 모든 에이전트(agent)에 바인드 마운트하는 호스트 측 경로입니다. 만약 이 변수들을 설정하지 않은 기존의 .env 파일을 재사용한다면, quickstart는 누락된 것이 안전한지 확인합니다. 이는 체크아웃 위치가 이미 /opt/roboco (compose 기본값)에 있는 경우에만 조용히(silently) 통과됩니다. 다른 곳에서는 정확히 추가해야 할 줄을 표시하며 큰 오류로 실패합니다 (예: ROBOCO_HOST_PROJECT_DIR=/your/checkout/path). 왜냐하면 변수가 설정되지 않으면 Docker가 /opt/roboco에 빈 디렉터리를 생성하고, 모든 에이전트 스폰(spawn)은 시스템 프롬프트를 읽기 전에 IsADirectoryError로 종료되기 때문입니다. 명시적으로 설정된 값은 항상 있는 그대로 신뢰됩니다. 호스트/데몬 분리 구성(원격 또는 rootless Docker, 바인드 마운트된 체크아웃)의 경우 합법적으로 스크립트가 볼 수 없는 경로 이름을 지정할 수 있습니다.

두 개의 환경 변수(ROBOCO_REGISTRY와 ROBOCO_VERSION)를 사용하여 레지스트리와 버전을 선택하세요 (기본값 표시). make quickstart를 실행하기 전에 .env에 설정해야 합니다:

ROBOCO_REGISTRY=ghcr.io/rennf93   # 또는 docker.io/renzof93
ROBOCO_VERSION=latest             # 또는 고정된 릴리스, 예: 0.15.0

오케스트레이터는 요청에 따라 일치하는 사전 구축된 에이전트 이미지(pre-built agent images)를 스폰합니다. 호스트에서 빌드 도구 체인이나 소스 컴파일이 필요하지 않습니다.

옵션 2 — 소스에서 빌드하기 (Build from source)

풀링(pulling)하는 대신 Dockerfile을 사용하여 로컬에서 동일한 전체 스택을 구축합니다:

git clone https://github.com/rennf93/roboco.git && cd roboco
cp .env.example .env              # 그리고 비밀값을 편집하세요
docker compose up -d              # 첫 실행 시 이미지를 빌드하고, 모든 것을 시작합니다

옵션 3 — 로컬 개발 (전체 스택 없음) (Local development)

코드 자체를 해킹(hacking)하려면, 백엔드 서비스만 Docker에서 실행하고 API는 호스트에서 실행하세요. RoboCo의 코드는 Python 3.13 이상을 요구합니다 (uv가 필요할 경우 가져옵니다):

uv sync
docker compose up -d postgres redis ollama   # 백엔드 서비스만
uv run alembic upgrade head                   # 데이터베이스 마이그레이션
...

설정 (Configuration)

주요 환경 변수(모든 옵션은 roboco/config.py 참조). 패널의 Settings → Feature Flags 카드에서 전체 36개 기능 플래그를 관리하는 것이 가장 정확한 방법입니다. 수동으로 환경 변수를 편집하기보다는 해당 카드를 통해 토글하세요. 아래 bash 블록은 몇 가지 대표적인 플래그와 패널에 토글이 없는 설정을 위한 env-var(환경 변수) 등가물을 보여줍니다:

# API Server
ROBOCO_HOST=0.0.0.0
ROBOCO_PORT=8000
...

패널에 노출된 36개 기능 플래그는 여덟 가지 범주로 나뉩니다:

• Communication (통신): telegram_enabled, telegram_inbound_enabled, x_engine_enabled, x_replies_enabled, x_feature_spotlight_enabled — Telegram 알림 및 X(Twitter) 계정 관련.
• Content (콘텐츠): video_engine_enabled, video_on_release, video_on_spotlight — 동영상 생성 엔진과 그 트리거들.
• Governance (거버넌스): provisioning_enabled, strategy_engine_enabled, roadmap_engine_enabled, research_enabled, release_manager_enabled — 보드 프로그램 및 게이트가 설정된 릴리스 관리자 관련.
• Infrastructure (인프라): ci_watch_enabled, dep_update_enabled, env_sync_enabled, docs_sync_enabled, gateway_health_enabled, self_heal_enabled, self_heal_originate_enabled, sandbox_db_enabled, rag_auto_update_enabled, transcript_prune_enabled — 백그라운드 루프, 샌드박스 DB, 작업 공간 상태 관련.
• Quality (품질): conventions_enabled, org_memory_enabled, fable_mode_enabled, possibilities_matrix_enabled, routing_strict — 아키텍처 강제화, 조직 메모리, 행동 원칙(behavioral doctrine), 모델 라우팅 엄격성 관련.
• Budgets (예산): task_budgets_enabled — 프로젝트별 월간 및 작업별 비용 상한선.
• Vault (금고): obsidian_vault_enabled, vault_intake_enabled, vault_report_enabled, vault_kb_enabled — Obsidian 금고 투영, 수집(intake), 보고서, KB 인덱싱 관련.
• PR review (PR 검토): external_pr_enabled, internal_pr_enabled, toolchain_match_enabled — 외부/내부 PR 검토, 내부 PR 검토 및 툴체인 매칭 관련.

각 플래그는 패널 카드에 한 줄 설명이 있습니다. 나머지 열두 개의 보드 프로그램(Pest Control, Spackle, Scales, Dogfood, Periscope, Megaphone, Mirror, Barfly, War Room, Coroner, Librarian, Sentinel)은 기능 플래그 카드 대신 전용 보드 프로그램 페이지(Business 섹션)에서 각 프로그램별로 관리됩니다.

다중 에이전트 워크스페이스 구조

각 에이전트는 병렬 개발을 위해 자체 git 클론을 가집니다:

{ROBOCO_WORKSPACES_ROOT}/
└── {project-slug}/
    └── {team}/
...

작업 수명 주기(Task Lifecycle)

backlog → pending → claimed → in_progress → verifying → awaiting_qa
    ↓                              ↓              ↓           ↓
cancelled                      blocked      needs_revision   awaiting_documentation
...

조립된, PR(Pull Request)을 포함하는 작업은 PM이 병합하기 전에 추가 단계인 인-패스 PR 검토 게이트를 통과합니다:

in_progress → awaiting_pr_review → awaiting_pm_review
   (submit_up /      (pr_pass)
    submit_root)     (pr_fail → needs_revision)

셀 PM의 submit_up(cell→root PR)과 메인 PM의 submit_root(root→master PR)는 조립된 PR을 열고 게이트에 진입합니다. PR 검토자는 이를 PM 병합으로 pr_pass하거나 다시 pr_fail시킵니다. 리프 개발 작업(QA가 검토함)과 브랜치 없는 조정 루트는 이 게이트를 건너뜁니다.

API 엔드포인트

도메인 경로는 /api 아래에 마운트됩니다:

개발

# dev 의존성 설치
uv sync --all-extras

...

핵심 원칙