Getting Started
AllvIa Local OS Agent의 설치, 구성, 실행 전 과정을 안내합니다. 예상 소요 시간은 약 5분입니다.
사전 요구사항 (macOS)
macOS에서 시작하기 전에 다음 환경이 준비되어 있는지 확인하십시오.
| 항목 | 요구사항 | 비고 |
|---|---|---|
| 운영체제 | macOS 12+ (Monterey) 이상 | - |
| Rust | 1.70 이상 | rustup.rs에서 설치 |
| Build Tools | Xcode Command Line Tools | xcode-select --install |
| OpenAI API Key | GPT-4 또는 GPT-3.5 | LLM 분석 모듈에 필요 |
| Git | 최신 버전 | 저장소 클론용 |
사전 요구사항 (Windows)
Windows에서 시작하기 전에 다음 환경이 준비되어 있는지 확인하십시오.
| 항목 | 요구사항 | 비고 |
|---|---|---|
| 운영체제 | Windows 10 / 11 | 64비트 권장 |
| Rust | 1.70 이상 (msvc 툴체인) | rustup.rs에서 설치 |
| Build Tools | Visual Studio Build Tools | C++ 연크릿 도구 포함 |
| OpenAI API Key | GPT-4 또는 GPT-3.5 | LLM 분석 모듈에 필요 |
| Git | 최신 버전 | 저장소 클론용 |
Step 1 — 저장소 클론 및 환경 설정
GitHub에서 AllvIa 저장소를 클론하고 환경변수를 구성합니다.
# 저장소 클론
git clone https://github.com/allvia-ai/ALLVIA.git
cd ALLVIA
# 환경변수 파일 생성
cp core/.env.example core/.env# 저장소 클론
git clone https://github.com/allvia-ai/ALLVIA.git
cd ALLVIA
# 환경변수 파일 생성 (PowerShell)
Copy-Item core/.env.example core/.env.env 파일을 편집하여 OPENAI_API_KEY를 설정합니다.
Step 2 — 빌드
Rust 네이티브 바이너리를 빌드합니다. Release 빌드는 약 2~3분이 소요됩니다.
cargo build --manifest-path core/Cargo.toml --release빌드 완료 후 바이너리 위치: ./core/target/release/local_os_agent
빌드 완료 후 바이너리 위치: .\core\target\release\local_os_agent.exe
Step 3 — 에이전트 실행
macOS 실행
# 퀵 스타트 스크립트 실행 (권장)
bash scripts/run_local.sh
# 또는 바이너리 직접 실행
./core/target/release/local_os_agent
# 또는 cargo run 사용
cargo run --manifest-path core/Cargo.toml --bin core --releaseWindows 실행
Windows 환경에서는 PowerShell 스크립트를 사용합니다:
# PowerShell 스크립트 실행 (권장)
.scripts
un_core.ps1 -CollectorImpl rust
# 또는 직접 실행
.core arget
eleaselocal_os_agent.exe정상적으로 실행되면 다음과 같은 프롬프트가 표시됩니다:
AllvIa Agent ready
Environment Scan: Found 349 apps
Collector: running on port 8080
Write Lock: enabled (use 'unlock' to disable)
Type 'help' for available commands.
>Step 4 — 핵심 명령어
에이전트가 실행된 상태에서 다음 명령어를 사용할 수 있습니다.
| 명령어 | 설명 | 사용 예시 |
|---|---|---|
surf | 자연어로 OS 전체 제어 (핵심) | surf "Safari 열어서 날씨 검색해" |
routine | 반복 패턴 분석 결과 조회 | routine |
recommend | AI 기반 자동화 추천 | recommend |
status | 시스템 상태 확인 | status |
control | 애플리케이션 제어 | control Safari open |
exec | 셸 명령 실행 (보안 정책 적용) | exec "echo hello" |
build_workflow | 자연어 기반 워크플로우 생성 | build_workflow "매일 9시 Slack 알림" |
패턴 분석 및 자동화 추천
routine 명령어로 수집된 사용 패턴을 확인하고, recommend로 AI 기반 자동화를 추천받을 수 있습니다:
> routine
분석된 반복 패턴 (최근 7일):
1. VS Code → Terminal → git commit (매일 3회)
2. Slack → Chrome → Google Docs (매일 5회)
3. Finder → Terminal → npm run dev (매일 4회)
> recommend
추천 자동화 3건:
→ git auto-commit 워크플로우 생성
→ 문서 리뷰 알림 자동화
→ dev server 원클릭 실행자연어 워크플로우 생성
build_workflow 명령어는 자연어 프롬프트를 n8n 호환 워크플로우로 변환합니다:
> build_workflow "매일 아침 9시에 Slack 채널에 일간 리포트 전송"
LLM 분석 중...
n8n 워크플로우 생성 중...
workflow_daily_report.json 생성 완료
워크플로우가 n8n에 등록되었습니다.
Dashboard: http://localhost:5678Step 5 — 워크플로우 확장 (선택 사항)
n8n 워크플로우 오케스트레이션
n8n을 연동하면 복잡한 멀티스텝 워크플로우를 시각적 인터페이스로 관리할 수 있습니다.
# Docker로 n8n 실행
docker compose up -d n8n
# n8n 대시보드 접속
# → http://localhost:5678
# 런타임 모드 변경 (환경변수)
# STEER_N8N_RUNTIME=manual (기본값)
# STEER_N8N_RUNTIME=docker
# STEER_N8N_RUNTIME=npx데이터 수집 및 배치 분석
Rust Collector로 OS 센서 데이터를 수집하고, 배치 파이프라인으로 분석합니다:
# 통합 로컬 실행 (권장)
bash scripts/run_local.sh
# Collector 단독 실행
cargo build --manifest-path core/Cargo.toml --bin collector_rs
STEER_DB_PATH=./steer.db ./core/target/debug/collector_rs
# 배치 분석 파이프라인
bash scripts/run_pipeline_rs.sh configs/config.yaml데스크톱 앱 빌드 (Tauri)
팀 배포용 데스크톱 애플리케이션을 빌드할 수 있습니다.
./scripts/rebuild_and_deploy.sh빌드 완료 후 .app 파일이 web/src-tauri/target/release/bundle/macos/에 생성됩니다.
빌드 완료 후 .exe 설치 파일이 web/src-tauri/target/release/bundle/msi/ 또는 nsis/에 생성됩니다.
다음 단계
첫 번째 자동화 실행을 완료했습니다. 다음 문서를 통해 서비스를 심층적으로 활용할 수 있습니다:
- Tutorials — 이메일 자동 분류, 주간 리포트 생성 등 실전 시나리오 가이드
- API Reference — 로컬 코어 API를 활용한 에이전트 실행 파이프라인 연동
- FAQ — 자주 묻는 질문과 트러블슈팅
문제가 발생한 경우 GitHub Issues에서 도움을 받거나 기술팀에 직접 문의하실 수 있습니다.