J.A.R.V.I.S OS
Just A Rather Very Intelligent System — 모듈식 스킬 아키텍처, 에이전트 계획 실행(agentic plan execution), 그리고 홀로그래픽 HUD를 갖춘 완전한 로컬 AI 비서입니다.
Built by Sami Porokka / Poro-IT OÜ
기능 (Features)
-
4-Pass Memory Router — 모호성(Ambiguity), 메모리, 도구 선택 및 경로 분류를 단일하고 빠른 Gemma4 패스로 처리합니다.
-
Agentic Plan System — build X → 구조화된 8~10단계 계획 → 인간 승인(human approval) → plan_runner 실행 → 스테이징 파이프라인을 거칩니다.
-
Self-Healing Plan Runner — 4개의 병렬 워커, 충돌 자동 복구(orphaned tasks는 부팅 시 재큐잉), dep-timeout 재큐잉, 재시도 백오프(retry backoff), 그리고 LLM 실패 진단 루프 (CAUSE/FIX를 vault에 기록 + 하나의 진단 기반 재시도) 기능을 갖추고 있습니다.
-
Plan Rerun & Versioning — POST /rerun/{plan_id}를 사용하여 버전이 지정된 ID(PLAN-X-001 → -2 → -3) 하의 모든 계획을 복제할 수 있습니다.
-
systemd 서비스 — 17개 유닛 + 설치 프로그램; 모든 것이 linger를 통해 WSL 부팅 시 자동 시작됩니다 (systemctl --user start jarvis.target).
-
Claude API 모드 — claude_proxy.py는 Claude API를 통해 Ollama 및 llama.cpp API를 에뮬레이션합니다. 전체 스택은 코드 변경 없이 클라우드 전용으로 실행됩니다 (선택적 Voyage AI 임베딩).
-
백엔드 폴백 체인(Fallback Chain) — llama.cpp가 다운되면 → 자동 Ollama 폴백(최소 모델 가드 포함) → 또는 11434 포트에 있는 경우 Claude 프록시로 전환됩니다.
-
다중 메시지 텔레그램 — ---next--- 라인을 포함하는 모든 스킬 또는 모델 응답은 별도의 Telegram 메시지로 자동 분할됩니다. 긴 응답은 잘리지 않고 청크(chunk)로 처리됩니다.
-
스테이징 파이프라인 — staging/dev/ → Playwright/Podman 테스트 → staging/tested/ → 인간 승인(human approval) → staging/approved/ 순서로 진행됩니다.
-
Codex UI — 계획 선택기, 단계 상태, 파일 브라우저, PTY 터미널 및 승인 버튼이 있는 인앱 코딩 작업 공간입니다.
-
ReAct 에이전트 루프 — 생각(Think) → 도구(Tool) → 관찰(Observe) → 작업 완료 시까지 반복 (최대 8회 반복)합니다.
-
모듈식 스킬 — 35개 이상의 플러그 앤 플레이(plug-and-play) 스킬 모듈을 제공하며, 설정(config)을 통해 활성화/비활성화할 수 있고 파일을 드롭하고 재시작할 수 있습니다.
-
멀티 모델 라우팅(Multi-Model Routing) — 요청별로 Fast (8b) / Reason (30b) / Code (qwen3.6:27b) / Deep / Cloud 사용
-
음성 입출력(Voice I/O) — 웨이크 워드 "Hey JARVIS", Whisper STT, 5.1 센터 채널 출력을 지원하는 Kokoro/Orpheus TTS
-
영구 메모리(Persistent Memory) — MemPalace 벡터 DB + Obsidian 볼트 (2000개 이상의 기억), Redis를 활용한 작업 메모리
-
스탁 인더스트리 HUD(Stark Industries HUD) — GPU 모니터, 격자형 페이스, 실시간 시스템 로그가 포함된 Next.js 홀로그래픽 대시보드
-
홈 자동화(Home Automation) — Denon AVR, NVIDIA Shield, LG TV, Panasonic Blu-ray, Philips Hue, 인터넷 라디오 연동
-
n8n 통합(n8n Integration) — 양방향: Jarvis가 n8n 워크플로우를 트리거하고, n8n이 작업/이벤트를 다시 Jarvis로 전송
-
클라우드 LLM — Claude, GPT-4, Gemini, Groq, Mistral, OpenRouter를 통합된 스킬을 통해 사용
-
AI 이미지 생성(AI Image Gen) — Qwen3 프롬프트 향상 기능을 갖춘 FLUX 텍스트-이미지 생성 + VRAM 자동 교체 기능
-
전화/SMS/이메일 — Twilio 통화 및 SMS, SMTP/IMAP 이메일 연동
-
Telegram 게이트웨이(Telegram Gateway) — 모바일 제어, 계획 승인, 그리고 Telegram으로 트리거되는 작업 처리
-
컴패니언 앱(Companion App) — JARVIS Mobile — 온디바이스 Gemma 라우팅 및 Telegram 전송 기능을 갖춘 React Native (Expo) 모바일 클라이언트
-
Unreal Engine 5.8 MCP — Claude 코드를 UE 에디터에 직접 연결하는 네이티브 MCP 플러그인: 액터 스폰, MetaHuman 표정 구동, 조명 제어, 애니메이션 트리거 등 파일 브리지를 실시간 도구 호출로 대체
-
Android 테스트 — Gradle + Playwright/Podman을 통해 Android 에뮬레이터에서 React Native / Expo 앱 빌드 및 테스트를 수행하며, 계획 시스템과 연결됨
아키텍처(Architecture)
User Input (음성 / HUD / Telegram / API)
│
┌─────▼──────────┐
...
Unreal Engine 5.8 통합(Integration)
UE 5.8은 에디터 프로세스 내부에 MCP 서버를 임베드하는 네이티브 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 플러그인을 제공합니다. Jarvis는 이를 로컬 HTTP를 통해 연결하여 에디터를 직접 구동하며 — 파일 폴링이나 브리지 스크립트가 필요 없습니다.
Agent loop에서 "set Jarvis emotion to thinking"라고 지시함
│
skills/unreal.py
...
UE 측 설정(UE Side Setup)
편집(Edit) → 플러그인(Plugins)으로 이동하여 Unreal MCP를 검색하고 활성화한 후 에디터를 재시작합니다.- 콘솔에서
ModelContextProtocol.GenerateClientConfig를 실행하고 출력 로그(Output Log)에서 포트를 기록합니다.
- 선택적으로 Claude Code에 직접 추가합니다:
claude mcp add unreal --transport http http://localhost:3000/mcp
스킬 기능 (What the Skill Can Do)
| 카테고리 | 도구 | |
|---|
| 액터(Actors) | spawn_actor, set_transform, get_actors, delete_actor | |
| ... | | |
감정 프리셋 (Emotion Presets)
"Jarvis의 감정을 행복하게 설정" → mouthSmile + cheekSquint 모프(morphs)
"Jarvis의 감정을 생각하는 상태로 설정" → browInnerUp + eyeLookUp 모프(morphs)
"Jarvis의 감정을 집중한 상태로 설정" → browDown + eyeSquint 모프(morphs)
...
TTS 진폭(amplitude)은 직접 파이프됩니다: Kokoro TTS가 생성하는 모든 오디오 프레임은 set_amplitude에 공급되어 MetaHuman 입이 음성과 실시간으로 움직입니다. 동일한 신호가 HUD의 Three.js 격자 얼굴과 UE MetaHuman 모두를 구동합니다.
전체 문서: docs/skills/unreal.md
플랜 시스템 (Plan System)
플랜 시스템은 Jarvis가 인간의 개입(human gates)을 거쳐 다단계 코딩 프로젝트를 자율적으로 실행할 수 있게 합니다.
User: "7x7 그리드로 복권 웹사이트 구축"
│
build_simple_code_plan() ← qwen3:14b
...
스테이징 디렉토리 (Staging Directories)
| 경로 | 단계 | 의미 |
|---|
staging/dev/PLAN-ID/ | 개발(Development) | plan_runner가 작성한 파일 |
| ... | | |
스킬 (Skills)
JARVIS는 모듈식 스킬 시스템을 사용합니다. 각 스킬은 skills/ 내의 독립적인 Python 모듈이며, 자체 도구(tools), 키워드, 실행기(executors)를 등록합니다.
| 스킬 | 주요 도구 | 설명 |
|---|
| coding | coding, code_edit | qwen3.6:27b를 통한 코드 생성 — 플랜, diff(차이점), 파일 쓰기 |
| ... | | |
| 전체 스킬 문서: docs/SKILLS.md | | |
모델 (Models)
| 슬롯 | 모델 | 크기 | 사용 사례 |
|---|
| Router | gemma4:4b | 2.5 GB | 메모리 라우팅 (llama.cpp :8081) |
| ... | | | |
전제 조건 (Prerequisites)
- NVIDIA GPU와 CUDA (RTX 3090 24GB에서 테스트됨)
- Windows 11 + WSL2 (권장) 또는 Ubuntu 22.04 이상
- Node.js 20 이상
- Python 3.12 이상
- 모델을 풀(pull)한 Ollama
- Redis (플랜 큐, 작업 메모리, 태스크 상태용)
- Unreal Engine 5.8 (선택 사항) — MCP를 통한 MetaHuman 얼굴 및 3D 장면 제어용
- Android Studio + SDK (선택 사항) — 안드로이드 에뮬레이터 테스트용 (Pixel_6 AVD)
설치(Installation)
Windows 11 + WSL2 (권장)
git clone https://github.com/porokka/jarvis-os.git
cd jarvis-os
.\
install-windows.ps1
네이티브 Linux (Ubuntu 22.04+ / Debian 12+)
git clone https://github.com/porokka/jarvis-os.git
cd jarvis-os
bash install-linux.sh
설치 후(Post-Install)
Unreal Engine 5.8 MCP (선택 사항)
- UE 5.8 프로젝트를 엽니다.
Edit → Plugins에서 Unreal MCP를 검색하여 활성화하고 에디터를 재시작합니다.- UE Output Log 콘솔:
ModelContextProtocol.GenerateClientConfig — 포트를 기록합니다.
- jarvis-os 루트의
.env 파일에 추가합니다:
UE_MCP_URL=http://localhost:3000/mcp
UE_TCP_PORT=55557
- jarvis를 재시작하면
unreal 스킬이 자동으로 로드됩니다.
Android 에뮬레이터 (선택 사항)
- Android Studio + Android SDK를 설치합니다.
- AVD 매니저에서 Pixel_6 AVD (API 33 이상)를 생성합니다.
.env 파일에 추가합니다:
ANDROID_HOME=C:/Users/yourname/AppData/Local/Android/Sdk
JAVA_HOME=C:/Program Files/Microsoft/jdk-21
android 스킬은 빌드 시 에뮬레이터의 시작/중지를 자동으로 처리합니다.
사용법(Usage)
시작 / 중지 / 상태 확인
systemd (권장 — WSL 부팅 시 자동 시작):
bash systemd/install.sh --start
systemctl --user start jarvis.target
systemctl --user stop jarvis.target
...
WSL 참고 사항: WSL2는 마지막 wsl.exe 클라이언트가 종료되면 VM을 종료합니다. 따라서 내부 서비스들은 이를 유지하지 못합니다. 설치자 문서는 keep-alive를 위한 방법(wsl.exe -e sleep infinity를 Windows 시작 폴더에서 실행)을 다루고 있습니다. 이것 없이는 Jarvis는 WSL 터미널이 열려 있는 동안에만 존재합니다.
클래식 스크립트 (여전히 작동함):
bash jarvis.sh start
bash jarvis.sh stop
bash jarvis.sh status
...
Claude API 모드 (로컬 모델 없음)
export ANTHROPIC_API_KEY=sk-ant-...
sudo systemctl stop ollama
systemctl --user stop jarvis-llama
...
프록시는 Ollama(/api/chat, /api/tags, /api/embeddings) 및 llama.cpp(v1/chat/completions) 형식을 사용하여 Anthropic으로 전달합니다. 모델 매핑: small/fast 이름 → Haiku, 그 외 모든 것은 Sonnet (JARVIS_CLAUDE_MODEL / JARVIS_CLAUDE_FAST_MODEL). VOYAGE_API_KEY가 설정된 경우 Voyage AI를 통해 임베딩을 사용하며, 그렇지 않으면 시맨틱 검색은 점진적으로 저하됩니다.
Plan 재실행 (Plan Rerun)
curl -X POST http://127.0.0.1:8766/rerun/PLAN-20260629-001
실패한 작업은 자동 진단(CAUSE/FIX via qwen3:14b)되며, <vault>/.jarvis/plan_failures.md에 기록되고, 진단 내용이 코더 프롬프트에 주입되어 한 번 재시도됩니다.
Plan 명령어 (Plan Commands)
"로컬 스토리지를 사용한 투두 앱 구축" → 플랜 생성 → 승인 대기
"PLAN-20260619-001 진행" → plan_runner에 큐 추가
"PLAN-20260619-001 취소" → 활성 플랜 취소
...
음성 (Voice)
python3 scripts/voice_capture.py
python3 scripts/voice_capture.py --wake
인터페이스 (Interfaces)
인터페이스
API 엔드포인트 (API Endpoints)
POST /api/chat ReAct 루프 — 메인 진입점
GET /api/health 상태 확인(Health check) + 서비스 상태
GET /api/skills 로드된 모든 스킬 및 도구
...
파일 구조 (File Structure)
jarvis-os/
├── jarvis.sh # 시작/중지/재시작/상태 확인 (클래식)
├── systemd/ # systemd 사용자 유닛 + install.sh (권장)
...
n8n 통합 (n8n Integration)
Jarvis와 n8n은 양방향으로 통신합니다:
Jarvis → n8n (워크플로우 트리거):
"add task to n8n: research competitor pricing"
→ n8n 스킬: add_task
→ POST /webhook/jarvis-task { task, callback_url }
...
n8n → Jarvis (작업/이벤트 푸시):
POST http://jarvis:7900/api/events
{ "type": "workflow_done", "task": "build X", "data": {...} }
→ 이벤트로 기록됨
...
infra/.env.n8n.local에 설정:
N8N_TASK_WEBHOOK=/webhook/jarvis-task
N8N_EVENT_WEBHOOK=/webhook/jarvis-event
JARVIS_API_URL=http://<wsl-ip>:7900
페르소나 모드 (Personality Modes)
| Mode | Character | Address |
|---|
| J.A.R.V.I.S | 영국식 집사, 건조한 재치 | "sir" |
| ... | | |
예시 명령어 (Example Commands)
"build a lottery website with a 7x7 number grid"
"proceed PLAN-20260619-001"
"add task to n8n: send weekly report to team"
...
컴패니언 앱 (Companion App)
JARVIS Mobile — JARVIS OS용 React Native (Expo) 모바일 클라이언트.
- 로컬에서 요청을 라우팅하는 온디바이스 Gemma4 모델이 데스크톱으로 전송하기 전에 처리합니다.
- Telegram 봇 및 직접 API를 통해 jarvis-os와 통신합니다.
- 휴대폰에서 플랜 승인, 음성 명령, 상태 확인 가능
- 시각적 컨텍스트를 위한 카메라 입력 지원
- Expo 52 + React Native로 구축됨
Phone mic → Gemma4 (온디바이스) → 경로 결정
├── 간단한 경우: 기기 내에서 답변
└── 복잡한 경우: Telegram을 통해 jarvis-os로 전송
라이선스
MIT License — 자세한 내용은 [LICENSE]를 참조하십시오.