OpenJarvis install (on Mac)

공식 사이트 참조

Table of Contents

Javis 설치

git clone

git clone https://github.com/open-jarvis/OpenJarvis.git

프로젝트 경로에서

cd OpenJarvis

의존성 동기화: uv sync를 실행하여 핵심 프레임워크를 설치한다. 만약 원격 클라이언트와의 통신을 위한 FastAPI 서버 기능을 포함하려면 uv sync --extra server 옵션을 사용해야 한다

uv sync --extra server

Rust Native 설치 (이미 설치되어있으면 스킵)

설치

curl https://sh.rustup.rs -sSf | sh

Current installation options:


   default host triple: aarch64-apple-darwin  ## 정상
     default toolchain: stable (default)          ## stable
               profile: default
  modify PATH variable: yes

1) Proceed with standard installation (default - just press enter)
2) Customize installation
3) Cancel installation

그냥 엔터

2번은 CI 최적화 하거나 어떤이유로 최소한으로만 설치하거나, Rust 버전 지정하거나, nightly 기능 필요할때

설치 후 환경변수 추가 필수

source $HOME/.cargo/env

설치 확인

rustc --version
cargo --version

Javis 이어서 설치

OpenJavis 빌드

uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml

파이썬 버전이 3.14 이상인경우 환경변수 설정해야함

이미 컴파일했어도 걱정하지말고 아래 명령어를 실행. 환경변수 관련된 부분만 재 컴파일됨.

export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml

여기까지 하면 설치 끝

하드웨어 진단 및 초기설정

이 유틸리티는 macOS의 CPU, RAM 용량, 그리고 GPU 가속 가능 여부를 탐지하여 적합한 추론 엔진(Ollama 등)과 모델 크기를 추천한다.

uv run jarvis init

에이전트 사용시**

에이전트 사용시엔 모델성능(지능) 보다는 context size가 더 중요. M1 Max를 에이전트로 활요하기위해 모델 크기 9.6gb 짜리 gemma4:e4b-it-q4_K_M 선택함. 위에 모델은 18GB짜리라서 context늘리고 혹시 컴파일하거나 에이전트가 이런저런 작업을할때 메모리가 부족해짐.

ollama pull gemma4:e4b-it-q4_K_M

어떤 엔진을 사용할건지 물어본다. 올라마를 이미 설치했기때문에 (running) 표시가 있다.

mlx가 애플 GPU 최적화모델이라서 (recommended)가 있는데 mlx는 instruction 모델이 없다. 어쩔수없이 올라마 사용.

Detecting running inference engines...
  Found running: ollama

Available engines:
  ollama  (running)
  mlx  (recommended)
  vllm
  sglang
  llamacpp
  lmstudio
  exo
  nexa

Select inference engine (ollama, mlx, vllm, sglang, llamacpp, lmstudio, exo, nexa) [ollama]:

기본 설정파일 내용

╭───────────────── /Users/_name_/.openjarvis/config.toml ──────────────────╮
│ # OpenJarvis configuration                                                                                                                                                                                    │
│ # Hardware: Apple M1 Max (10 cores, 32.0 GB RAM)                                                                                                                                                              │
│ # GPU: Apple M1 Max (32.0 GB unified memory)                                                                                                                                                                  │
│ # Full reference config: jarvis init --full                                                                                                                                                                   │
│                                                                                                                                                                                                               │
│ [engine]                                                                                                                                                                                                      │
│ default = "ollama"                                                                                                                                                                                            │
│                                                                                                                                                                                                               │
│ [engine.ollama]                                                                                                                                                                                               │
│ # host = "http://localhost:11434"  # set to remote URL if engine runs elsewhere                                                                                                                               │
│                                                                                                                                                                                                               │
│ [intelligence]                                                                                                                                                                                                │
│ default_model = "qwen3.5:9b"                                                                                                                                                                                  │
│                                                                                                                                                                                                               │
│ [agent]                                                                                                                                                                                                       │
│ default_agent = "simple"                                                                                                                                                                                      │
│                                                                                                                                                                                                               │
│ [tools]                                                                                                                                                                                                       │
│ enabled = ["code_interpreter", "web_search", "file_read", "shell_exec"]                                                                                                                                       │
│                                                                                                                                                                                                               │
╰─────────────────────────────────────────────────────╯

모델 설정 방법

아래 명령어로 config파일을 수정한다. _name_ 은 사용자계정이름.

sudo nano /Users/_name_/.openjarvis/config.toml

default_model 을 우리가 사용하는 모델로 수정해주고 저장

default_model = "gemma4:e4b-it-q4_K_M"

시스템 정검

시스템 점검: 설치 중 문제가 발생하거나 성능이 기대에 미치지 못할 경우 uv run jarvis doctor를 실행하여 하드웨어 상태와 의존성 무결성을 진단할 수 있다.

uv run jarvis doctor

클라우드 엔진 연동

로컬 자원이 부족하거나 보다 강력한 추론 능력이 필요한 경우, OpenAI, Anthropic, Google Gemini 등의 클라우드 API를 병행하여 사용할 수 있다. 이를 위해 .env 파일 또는 환경 변수에 다음과 같은 API 키를 설정해야 한다.

서비스 제공자	환경 변수명	용도
OpenAI	`OPENAI_API_KEY`	GPT-4o 등 고성능 비전 및 추론 모델 사용
Anthropic	`ANTHROPIC_API_KEY`	Claude 3.5 Sonnet 등 정교한 코딩 및 문서 분석
Google	`GOOGLE_API_KEY`	Gemini 모델을 통한 방대한 컨텍스트 처리

지능형 에이전트 포트폴리오 및 세부 활용 가이드

OpenJarvis의 핵심 가치는 특정 목적에 맞게 설계된 다양한 빌트인 에이전트들에 있다. 각 에이전트는 독립적인 사고 루프와 도구 사용 능력을 갖추고 있어 복잡한 작업을 자율적으로 수행한다.

Stanford Researchers Release OpenJarvis: A Local-First Framework for Building On-Device Personal AI Agents with Tools, Memory, and Learning

에이전트 유형 및 주요 기능 비교

OpenJarvis가 제공하는 에이전트들은 작업의 호흡(Short-horizon vs Long-horizon)과 개입 방식에 따라 구분된다.

에이전트 명칭	실행 유형	주요 역할 및 특징
Morning Digest	스케줄 기반 (Cron)	이메일, 일정, 건강 데이터를 종합하여 음성 브리핑 생성
Deep Research	온디맨드 (요청 시)	웹 및 로컬 문서를 가로지르는 다중 단계 심층 조사
Monitor Operative	지속형 (Continuous)	장기적인 데이터 모니터링, 압축 저장 및 필요 시 호출
Orchestrator	온디맨드 (요청 시)	복잡한 과업을 하위 작업으로 분해하고 적절한 도구 선택
Native ReAct	온디맨드 (요청 시)	‘생각-행동-관찰’ 루프를 통한 터미널 도구 및 코드 실행
Operative	지속형 (Continuous)	상태 관리를 동반한 반복적인 개인 워크플로우 자동화
Simple	온디맨드 (요청 시)	도구 사용이 필요 없는 가벼운 단일 턴 대화

심층 연구 에이전트 (Deep Research) 활용법

deep_research 에이전트는 단순한 검색을 넘어 수십 개의 소스를 분석하여 구조화된 보고서를 작성한다.

준비 과정: jarvis init --preset deep-research 명령어로 환경을 설정하고, jarvis memory index./documents/를 통해 사용자의 로컬 PDF나 텍스트 문서를 지능형 메모리에 인덱싱한다.
실행 예시: jarvis ask "최근 2년간의 로컬 LLM 효율성 추세에 대해 보고서를 작성해줘"라고 명령하면, 에이전트는 로컬 인덱스와 웹 검색을 병행하여 인라인 인용이 포함된 정교한 문서를 생성한다.
성능 지표: 대략 11분 동안 25개 이상의 상위 소스와 100개 이상의 웹 페이지를 분석할 수 있는 능력을 갖추고 있다.

개인 업무 요약 에이전트 (Morning Digest) 활용법

morning_digest는 매일 아침 사용자의 개인 데이터를 종합하여 맞춤형 정보를 제공한다.

연동 설정: jarvis connect gdrive를 실행하여 Google 계정(Gmail, Calendar, Tasks)에 대한 OAuth 인증을 수행한다. 이 과정은 SSH 환경에서 생성된 링크를 로컬 브라우저에서 승인하는 방식으로 진행된다.
브리핑 생성: jarvis digest --fresh 명령어를 사용하면 에이전트가 최신 데이터를 긁어모아 TTS(Text-to-Speech) 오디오와 텍스트 요약을 생성한다.
자동화: launchd나 cron을 통해 매일 오전 7시에 이 명령이 실행되도록 설정함으로써 완전 자율형 개인 비서를 구현할 수 있다.

uv run jarvis connect gdrive

실행하면 ClientID 입력하라고 나오는데 바로 위에있는 구글 클라우드 링크로 들어가서

OAuth 클라이언트 ID 만들기 눌러서

클라이언트 ID & 클라이언트 보안 비밀번호 를 차례로 입력해주면 된다.

그럼 로컬 컴퓨터(OpenJarvis가 설치된 컴퓨터)에서 웹브라우저가 뜨고

원격 SSH 환경에서의 프로세스 영속성 관리

SSH 접속은 네트워크 불안정성으로 인해 언제든 끊길 수 있다. 따라서 OpenJarvis와 같은 에이전트 프레임워크를 안정적으로 운용하기 위해서는 프로세스를 세션과 분리하는 기술이 필수적이다.

터미널 멀티플렉서 (tmux) 활용

tmux는 원격 접속이 끊겨도 터미널 내 프로세스를 유지시켜 주는 가장 직관적인 도구다.

세션 생성: tmux new -s jarvis_session 명령어로 새로운 작업 공간을 만든다.
작업 수행: 해당 세션 안에서 uv run jarvis ask... 또는 uv run jarvis serve를 실행한다.
세션 이탈: Ctrl+B를 누른 후 D를 눌러 세션에서 빠져나온다. 이후 SSH를 종료해도 에이전트는 계속 구동된다.
재접속: 나중에 다시 SSH로 접속하여 tmux attach -t jarvis_session을 입력하면 이전 작업 상태를 그대로 확인할 수 있다.

macOS 전용 백그라운드 서비스 (launchd) 활용

보다 영구적인 서비스 운영을 위해서는 macOS 고유의 데몬 관리자인 launchd를 사용하는 것이 좋다.

Plist 파일 작성: ~/Library/LaunchAgents/com.openjarvis.service.plist 파일을 생성하여 실행 경로와 인자값을 설정한다.
자동 재시작 설정: KeepAlive 옵션을 true로 설정하면 프로그램이 예기치 않게 종료되어도 시스템이 자동으로 다시 실행해 준다.
서비스 로드: launchctl load ~/Library/LaunchAgents/com.openjarvis.service.plist 명령어로 서비스를 활성화한다.

환경 설정 최적화 및 보안 가드레일

OpenJarvis의 모든 동작은 ~/.openjarvis/config.toml 파일에 의해 제어된다. 이 설정 파일을 정교하게 조정함으로써 에이전트의 권한과 자원 사용량을 최적화할 수 있다.

주요 설정 섹션 (`[agent]`) 상세 분석

필드명	기본값	설명 및 권장 설정
default_agent	`"simple"`	주로 사용하는 에이전트(예: `orchestrator`)로 변경 권장
max_turns	`10`	복잡한 추론을 위해 15-20 정도로 상향 조정 가능
context_from_memory	`true`	질문 시마다 로컬 지식 베이스를 검색하여 컨텍스트에 주입
system_prompt	`""`	에이전트의 페르소나와 제약 사항을 정의하는 최상위 지침

보안 가드레일 섹션 (`[security]`)

에이전트가 로컬 파일 시스템에 접근하거나 명령어를 실행할 때 발생할 수 있는 위험을 방지하기 위해 OpenJarvis는 강력한 보안 계층을 제공한다.

실행 모드 (mode): warn(경고만), block(차단), redact(민감정보 마스킹) 중 선택할 수 있다. 운영 환경에서는 redact 또는 block을 권장한다.
시스템 경계 (system_boundary): 에이전트가 접근할 수 있는 디렉토리 범위를 특정 경로로 제한하여 시스템의 핵심 파일을 보호한다.
도구 실행 확인 (enforce_tool_confirmation): 에이전트가 도구를 사용하기 전 항상 사용자의 승인을 받도록 설정할 수 있다. 자율성을 높이려면 이를 false로 설정하되, 보안 위험을 충분히 인지해야 한다.

스킬 시스템을 통한 에이전트 기능 확장

OpenJarvis 에이전트는 기본 기능 외에도 외부에서 개발된 ‘스킬(Skills)’을 학습하고 사용할 수 있다. 이는 Model Context Protocol (MCP) 기반의 도구 표준을 준수한다.

스킬 설치 및 동기화

사용자는 jarvis skill 명령어를 통해 커뮤니티에서 검증된 스킬셋을 간편하게 추가할 수 있다.

스킬 설치: jarvis skill install hermes:arxiv와 같이 특정 리포지토리의 스킬을 설치한다.
스킬 동기화: jarvis skill sync를 통해 설치된 스킬들의 정의와 사용법을 에이전트가 인식할 수 있도록 동기화한다.
동적 활용: 에이전트는 질문의 의도를 분석하여 필요한 스킬이 있다면 자동으로 호출한다. 예를 들어, “최근 논문을 검색해줘”라는 명령에 에이전트는 설치된 arxiv 스킬을 스스로 선택하여 실행한다.

학습 루프(Learning Loop)와 지속적 최적화 전략

OpenJarvis의 독보적인 특징 중 하나는 사용자와의 상호작용 결과를 데이터로 활용하여 스스로 성능을 개선하는 학습 루프에 있다.

추적 데이터(Trace Data) 수집 및 분석

시스템은 모든 추론 과정, 도구 호출 시퀀스, 성공 여부를 ‘트레이스(Trace)’라는 구조화된 데이터로 기록한다. 이 데이터는 다음과 같은 방식으로 활용된다.

스킬 최적화: jarvis optimize skills 명령어를 실행하면, 과거의 성공적인 도구 호출 사례를 바탕으로 모델의 프롬프트나 퓨샷(Few-shot) 예시를 자동으로 업데이트한다.
에이전트 정책 학습: agent_advisor 정책은 트레이스 패턴을 분석하여 어떤 에이전트와 도구 조합이 가장 효율적이었는지를 학습하고, 향후 유사한 작업에 대해 전략을 수정한다.
로컬 모델 미세 조정: 충분한 트레이스 데이터가 쌓이면, 사용자의 선호도와 작업 특성에 맞게 로컬 LLM을 SFT(Supervised Fine-Tuning)나 DPO(Direct Preference Optimization) 방식으로 미세 조정할 수 있는 기반이 마련된다.

시장 내 타 에이전트 프레임워크와의 비교 분석

OpenJarvis를 선택하기 전, 유사한 목적을 가진 다른 도구들과의 차이점을 명확히 이해하는 것이 중요하다. 2026년 기준, 에이전트 시장은 고유의 장단점을 가진 여러 솔루션이 경합하고 있다.

프레임워크 명칭	주요 특징	OpenJarvis 대비 장점	OpenJarvis 대비 단점
Claude Code	Anthropic 공식 CLI 에이전트	극도로 높은 추론 및 코딩 능력	높은 API 비용 및 프라이버시 우려
OpenHands	Docker 기반 샌드박스 에이전트	강력한 실행 격리 및 보안	복잡한 설정 및 높은 리소스 소모
Aider	Git 기반 페어 프로그래밍 도구	터미널 작업의 뛰어난 효율성	로컬 추론 미지원 및 단일 목적성
Codex CLI	OpenAI 기반 고속 터미널 에이전트	초당 240개 토큰의 압도적 속도	추론 깊이 부족 및 폐쇄형 생태계

OpenJarvis는 이러한 경쟁 도구들 사이에서 ‘로컬 우선’과 ‘지능 효율성’이라는 독보적인 위치를 점하고 있다. 특히 하드웨어 텔레메트리와 학습 루프를 통합한 방식은 단순한 도구 사용을 넘어 시스템 전체의 에너지 대비 성능을 최적화하려는 Stanford SAIL의 연구 철학을 충실히 반영하고 있다.

결론 및 향후 운용 제언

macOS 환경에서 SSH를 통한 OpenJarvis 구축은 단순한 소프트웨어 설치 이상의 의미를 갖는다. 이는 사용자의 개인 데이터를 안전하게 보호하면서도 고성능 AI의 혜택을 온전히 누릴 수 있는 ‘프라이빗 지능 거점’을 마련하는 과정이다.

효과적인 운용을 위해 다음과 같은 전략적 제언을 남긴다.

첫째, 하드웨어 최적화를 적극 활용하라. Apple Silicon의 특성을 고려하여 jarvis init이 추천하는 엔진 설정을 따르되, 메모리 여유가 있다면 보다 큰 파라미터의 모델로 상향 조정을 검토해야 한다.

둘째, 로컬 메모리의 품질이 에이전트의 지능을 결정한다. deep_research나 orchestrator 에이전트의 성능은 인덱싱된 문서의 양과 질에 직결되므로, 업무와 관련된 주요 문서를 지속적으로 메모리 저장소에 업데이트하는 습관이 필요하다.

셋째, 보안과 자율성 사이의 균형을 유지하라. 초기 설치 단계에서는 enforce_tool_confirmation을 활성화하여 에이전트의 행동 패턴을 관찰하고, 시스템이 안정화됨에 따라 점진적으로 자율 범위를 넓혀가는 접근 방식이 바람직하다.

마지막으로, 학습 루프를 통한 주기적 최적화를 수행하라. 정기적으로 jarvis optimize 명령을 실행하여 시스템이 사용자의 피드백과 과거 기록으로부터 학습할 기회를 제공함으로써, 시간이 흐를수록 더 똑똑해지는 개인화된 AI 에이전트를 완성할 수 있다.

OpenJarvis는 지속적으로 진화하는 프레임워크이며, Stanford SAIL의 로드맵에 따라 향후 더 많은 하드웨어 가속기와 복합적인 멀티 에이전트 통신 프로토콜을 지원할 예정이다. 본 보고서에서 제시한 가이드를 바탕으로 구축된 시스템은 미래의 로컬 AI 생태계에서 핵심적인 역할을 수행할 준비가 된 최첨단 지능형 인프라가 될 것이다.