kivo360/OmoiOS

격리된 샌드박스(sandboxes) 내에서 병렬 에이전트 스웜(agent swarms)을 사용하여 명세(specs)를 PR(Pull Requests)로 변환하는 오픈 소스 오케스트레이션 런타임(orchestration runtime).

OmoiOS가 유용하다고 생각하신다면, 별(star)을 눌러주세요. 다른 사람들이 프로젝트를 발견하는 데 도움이 됩니다.

AI 코딩 에이전트(AI coding agents)는 개별적으로는 강력하지만, 이를 대규모로 사용하는 것은 매우 혼란스럽습니다. 프롬프트를 붙여넣고, 기다리고, 검토하고, 또 다른 프롬프트를 붙여넣고, 고장 난 부분을 수정하는 과정을 반복합니다. 의존성 인식(dependency awareness), 병렬 실행(parallel execution), 작업 간의 구조화된 인계(structured handoff)가 없습니다. 에이전트들은 다른 에이전트가 무엇을 하고 있는지 알지 못합니다. 무언가 실패하면, 당신이 오케스트레이터(orchestrator)가 되어야 합니다.

OmoiOS는 이 문제를 해결합니다. 기존 코드베이스를 읽고, 실제로 존재하는 내용을 바탕으로 명세(specs)를 생성하며, 실제 의존성을 가진 작업 DAG(Directed Acyclic Graph)를 구축하고, 작업이 완료될 때까지 격리된 샌드박스(sandboxes)에서 에이전트 스웜(agent swarms)을 실행합니다. 감독 에이전트(supervisor agent)가 머지(merges)를 처리하고 모든 것이 궤도에서 벗어나지 않도록 유지합니다.

원하는 내용을 설명합니다
→ OmoiOS가 코드베이스를 탐색합니다
→ 명세(specs) 생성 (요구사항, 설계, 작업)
...

이것은 프롬프트 체이닝(prompt chaining)이 아닙니다. 이것은 의존성 그래프(dependency graphs), 샌드박스 실행(sandboxed execution), 능동적 감독(active supervision), 그리고 실제로 머지되는 코드를 갖춘 **에이전트 스웜을 위한 구조화된 런타임(structured runtime for agent swarms)**입니다.

OmoiOS는 일반적인 계획을 생성하지 않습니다. 저장소(repo)의 파일 구조, 패턴, 의존성을 읽고 실제로 존재하는 것에 기반한 명세(specs)를 생성합니다. SpecStateMachine은 각 단계가 실제 코드베이스 컨텍스트를 바탕으로 구축되는 단계(탐색(Explore) → 요구사항(Requirements) → 설계(Design) → 작업(Tasks))를 실행합니다.

작업들은 의존성 그래프(DependencyGraphService)를 형성합니다. 의존성이 충족될 때까지 아무것도 실행되지 않습니다. 임계 경로 분석(Critical path analysis)을 통해 무엇을 병렬로 실행할지 결정합니다. 이를 통해 5개의 에이전트가 서로 방해하지 않고 동시에 작업할 수 있습니다.

각 에이전트는 자체 Git 브랜치, 파일 시스템 및 리소스를 가진 격리된 Daytona 컨테이너에서 실행됩니다. 공유 상태(shared state)는 없으며, 간섭도 없습니다. 에이전트들이 작업을 마치면 ConvergenceMergeService가 Claude를 사용하여 충돌을 해결하며 최적의 순서로 브랜치들을 머지(merges)합니다.

IntelligentGuardian

60초마다 모든 에이전트의 궤적(trajectory)을 분석하여 정렬 상태를 점수화하고, 드리프트(drift)를 탐지하며, 작업 중간에 조향 개입(steering interventions)을 주입합니다. ConductorService는 시스템 전반의 일관성을 모니터링하고, 중복 작업을 탐지하며, 에이전트 간의 조율을 담당합니다. 에이전트들은 단순히 실행되는 것이 아니라, 감시를 받습니다.

실행 중에 에이전트들은 버그, 누락된 요구사항, 최적화 기회 등을 찾아냅니다. DiscoveryService는 적절한 단계에서 자동으로 새로운 태스크를 생성합니다. DAG(Directed Acyclic Graph)는 성장하고 적응합니다. 즉, 워크플로우는 에이전트들이 실제로 마주하는 상황을 바탕으로 스스로 구축됩니다.

단계 전환(Phase transitions)에는 품질 게이트(quality gates)가 있습니다. 당신은 전략적인 지점(단계 완료, PR 등)에서 검토를 수행합니다. 게이트 사이의 모든 과정은 자율적으로 실행됩니다. 당신은 방향을 설정하고, 스웜(swarm)이 실행을 처리합니다.

에이전트 스웜을 오케스트레이션하는 것을 넘어, OmoiOS에는 전체 코드베이스를 이해하는 내장 코드 어시스턴트가 포함되어 있습니다. 무엇이든 물어보세요. 어시스턴트는 저장소(repo)의 구조를 탐색하고, 실제 코드를 읽으며, 근거 있는 답변을 제공합니다. 빌드할 시간이 되면, 격리된 샌드박스(sandboxes)를 생성하고 당신을 위해 코드를 작성합니다.

+---------------------------+
| Frontend (Next.js 15) |
| Dashboard, Kanban Board, |
...

1. 기능 요청(feature request)을 제출합니다
└→ API가 Spec 레코드를 생성합니다
2. SpecStateMachine이 단계를 자동으로 실행합니다:
...

Docker, Python 3.12+, Node.js 22+, uv, pnpm, 그리고 just가 필요합니다. 아래에서 플랫폼을 선택하세요.

macOS

# Docker Desktop
brew install --cask docker
# Python + Node.js
...

Ubuntu / Debian

# Docker Engine
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
...

Fedora / RHEL / CentOS

# Docker Engine
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
...

Arch Linux

sudo pacman -S docker docker-compose python nodejs pnpm just
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER
...

Windows (WSL2 권장)

# WSL2 + Ubuntu를 설치한 후, 위의 Ubuntu 지침을 따르세요
wsl --install
# 또는 네이티브 Windows:
...

just를 설치하는 다른 방법

just는 대부분의 패키지 관리자(package managers)에서 사용할 수 있습니다. 만약 사용 중인 플랫폼이 위에 나열되어 있지 않다면:

방법	명령어
설치 스크립트 (Installer script)	`curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh
...
전체 목록: github.com/casey/just — Packages

모든 설치 사항 확인:

docker --version # Docker 24+
python3 --version # Python 3.12+
node --version # Node.js 22+
...

단 하나의 명령어로 환경 파일 (env files), 데이터베이스 서비스 (database services), 의존성 (dependencies), 그리고 마이그레이션 (migrations)을 모두 설정할 수 있습니다:

git clone https://github.com/kivo360/OmoiOS.git
cd OmoiOS
just quickstart

그 다음 개발을 시작하세요:

just dev-all # API + 프론트엔드 (frontend) 시작 (http://localhost:3000)

참고: 모든 기능을 온전히 사용하려면 .env.local을 편집하여 API 키 (LLM_API_KEY 등)를 추가해야 합니다. 키가 없어도 앱은 실행되지만 기능이 제한됩니다.

just quickstart가 완료되면 환경을 구성하세요:

# API 키를 사용하여 .env.local 편집
# 최소한 AI 기능이 작동하도록 LLM_API_KEY를 설정해야 합니다:
$EDITOR .env.local

변수 (Variable)	필수 여부	용도
LLM_API_KEY	AI 기능을 위해 필요	Fireworks AI 또는 OpenAI 호환 키
ANTHROPIC_API_KEY	에이전트 실행을 위해 필요	Claude Agent SDK 키
GITHUB_TOKEN	Git 통합을 위해 필요	GitHub 개인 액세스 토큰 (personal access token)
DAYTONA_API_KEY	샌드박스 (sandboxes)를 위해 필요	Daytona 격리 워크스페이스 (isolated workspace) 키

그 외 모든 기능 (대시보드, 작업 관리, API)은 키 없이도 작동합니다.

# 하나의 터미널에서 모든 것(API + 프론트엔드)을 시작
just dev-all
# 또는 별도의 터미널에서 서비스를 개별적으로 시작:
...

서비스 (Service)	URL
프론트엔드 (Frontend)	http://localhost:3000
...
모든 백엔드 포트 (backend ports)는 로컬 서비스와의 충돌을 피하기 위해 +10,000만큼 오프셋(offset)되어 있습니다.

Docker permission denied (Linux)

# docker 그룹에 사용자를 추가하고 다시 로그인하세요
sudo usermod -aG docker $USER
newgrp docker

포트가 이미 사용 중임 (Port already in use)

just status # 실행 중인 항목 확인
just kill-port 18000 # 특정 포트의 프로세스 종료
just stop-all # 모든 OmoiOS 서비스 중지

데이터베이스 연결 오류 (Database connection errors)

just docker-up # Postgres + Redis 재시작
just db-migrate # 마이그레이션 (migrations) 재실행
just bootstrap # 전체 환경 상태 점검 (health check)

Python/Node 의존성 문제 (Python/Node dependency issues)

# 백엔드 (Backend): 클린 재설치
cd backend && uv sync --group test
# 프론트엔드 (Frontend): 클린 재설치
...

대안 설정: Docker 전용 (로컬 툴체인 미사용) (Alternative setup: Docker-only (no local toolchain))

로컬에 Python/Node를 설치하고 싶지 않다면, 루트 디렉토리의 docker-compose.yml이 모든 것을 빌드합니다:

cp .env.example .env.local
docker compose up # 모든 서비스 빌드 및 실행

just dev-all # 풀스택 (full stack) 시작
just test # 영향받은 테스트만 실행 (빠름, ~10-30초)
just test-all # 전체 테스트 스위트 (test suite)
...

just test # 스마트 방식: 변경 사항의 영향을 받는 테스트만 실행 (testmon)
just test-all # 커버리지 (coverage)를 포함한 전체 스위트
just test-unit # 유닛 테스트 (Unit tests)만 실행
...

just check # 린트 (lint) 이슈 자동 수정 + 포맷팅 (format) (ruff)
just lint # 린트만 실행 (수정 없음)
just format # 포맷팅만 실행
...

Pre-commit hooks를 통해 모든 커밋 시 Ruff 린팅 및 포맷팅이 강제됩니다.

just db-migrate # 모든 대기 중인 마이그레이션 적용
just db-revision "add user table" # 새로운 마이그레이션 생성
just db-history # 마이그레이션 히스토리 보기
...

계층 (Layer)	기술 (Technology)	목적 (Purpose)
Frontend	Next.js 15 (App Router)	SSR을 포함한 전체 대시보드
UI	ShadCN UI + Tailwind	컴포넌트 라이브러리 (Radix primitives)
State	Zustand + React Query	클라이언트 + 서버 상태 관리 (State management)
Visualization	React Flow v12	의존성 그래프 (Dependency graphs) + 워크플로우 DAGs
Terminal	xterm.js	라이브 에이전트 워크스페이스 터미널
Backend	FastAPI 0.104+	비동기 Python API 프레임워크
Database	PostgreSQL 16 + pgvector	관계형 (Relational) + 벡터 검색 (Vector search)
Cache / Queue	Redis 7 + Taskiq	캐싱 (Caching), 발행/구독 (Pub/sub), 백그라운드 작업 (Background jobs)
ORM	SQLAlchemy 2.0+	비동기 데이터베이스 액세스
LLM	Claude (Agent SDK)	AI 에이전트 백본 (Backbone)
Sandbox	Daytona	격리된 워크스페이스 실행
Auth	JWT + API Keys	인증 (Authentication) + 인가 (Authorization)
Observability	Sentry + OpenTelemetry + Logfire	모니터링 (Monitoring) + 트레이싱 (Tracing)

OmoiOS/
├── backend/ # Python FastAPI 백엔드
│ ├── omoi_os/
...

문서 (Document)	설명 (Description)
Installation Runbook	설정 가이드 + 기여 워크플로우
ARCHITECTURE.md	전체 시스템 아키텍처 (여기서 시작하세요)
App Overview	핵심 기능 + 시스템 개요
Page Architecture	모든 프론트엔드 페이지 상세 정보
Frontend Architecture	프론트엔드 패턴 + 컴포넌트
...

아키텍처 심층 분석 (Architecture Deep-Dives)

문서 (Document)	설명 (Description)
Planning System	Spec-Sandbox 상태 머신 (State machine), 단계 평가기 (Phase evaluators)
...

기여를 환영합니다. 설정 지침, 코딩 표준 및 PR 프로세스는 CONTRIBUTING.md를 참조하세요.

빠른 버전:

• 저장소 포크 (Fork the repo)
• 기능 브랜치 생성 (git checkout -b feature/amazing-feature)
• 변경 사항 적용
• just check를 실행하여 품질 검증
• PR 제출

취약점을 발견하셨나요? 책임감 있게 보고해 주세요. 보안 정책 및 보고 프로세스는 SECURITY.md를 참조하세요.

OmoiOS는 Apache License 2.0 라이선스 하에 배포됩니다.

잠을 자러 가세요. 풀 리퀘스트 (Pull requests)를 확인하며 깨어나세요.